blackwalltier-com Receipts API

openapi: 3.2.0
info:
  title: Black_Wall Receipts API
  description: 'Pre-action outcome prediction for AI agents.


    Your AI agent has a twin. The twin tries it first.


    Black_Wall is a token-metered REST API. Send your agent''s proposed action;

    we return a predicted outcome, a 0–100 risk score, a list of red flags,

    a reversibility class + rollback cost, and a GO / CAUTION / STOP recommendation

    in a few seconds — before the action runs.


    Free tier: ~100 forecasts/mo, no credit card. Get a key at https://blackwalltier.com'
  version: 1.0.0
  contact:
    name: Black_Wall Support
    email: hello@forecast.dev
    url: https://blackwalltier.com
servers:
- url: https://blackwalltier.com/api
  description: Production
- url: http://localhost:3000/api
  description: Local development
security:
- bearerAuth: []
tags:
- name: Receipts
paths:
  /v1/receipts/{id}:
    get:
      summary: Look up a previously-issued decision receipt
      description: 'Returns the envelope metadata (hashes + Ed25519 signature) for a

        receipt issued by an earlier `/v1/forecast` call. Black_Wall stores

        only the envelope — never the raw request or response bodies — so this

        endpoint returns the cryptographic fingerprint, not the payloads.


        Auth: requires the same Bearer key that issued the receipt.

        Cross-tenant lookups return 404, not 403 (does not leak existence).


        To verify, combine this envelope with your stored copy of the original

        request + response and POST to `/v1/receipts/verify`.'
      operationId: getReceipt
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: The receipt ID returned in the `/v1/forecast` response under `receipt.id`.
      responses:
        '200':
          description: Receipt envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receipt'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found, or owned by a different tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Receipts
  /v1/receipts/verify:
    post:
      summary: Verify a decision receipt (stateless, public)
      description: 'Public, no API key required. Verifies an Ed25519 decision receipt

        against the request + response bodies you provide. Intended for

        auditors and any third party who needs to confirm that Black_Wall

        actually signed off on a specific (request, response) pair.


        Stateless: no database lookup. The receipt envelope carries the

        `key_id`; we load the matching published public key from

        `/.well-known/blackwall-signing-keys.json` and verify the signature

        over the canonical hashes of your bodies.


        If you want to verify entirely offline (no network call to Black_Wall):

        cache the public key from the well-known URL and run the same

        Ed25519 verify locally — this endpoint is a convenience, not a trust

        dependency.


        Strip the UNSIGNED top-level keys from your response_body before

        posting — the signature is over the response without them:


        * `receipt` — the envelope cannot sign itself.

        * `confirmation` — the confirmation handle, added AFTER signing

        on any held gate (CONFIRM / HUMAN_REQUIRED).

        * `receipt_unavailable` — the reason no receipt was issued.


        Every other field in the body IS signed. (We tolerate it if you forget

        those three; we''ll strip them for you. Any OTHER unexpected key is left

        in place and fails as `response_hash_mismatch` — response_hash is the

        only thing binding the body, so unknown keys are never ignored.)'
      operationId: verifyReceipt
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - envelope
              - request_body
              - response_body
              properties:
                envelope:
                  $ref: '#/components/schemas/Receipt'
                request_body:
                  type: object
                  description: The exact body you originally POSTed to `/v1/forecast`.
                  additionalProperties: true
                response_body:
                  type: object
                  description: The exact response body returned by `/v1/forecast`, with the unsigned top-level keys removed (`receipt`, `confirmation`, `receipt_unavailable`).
                  additionalProperties: true
      responses:
        '200':
          description: Verification result
          content:
            application/json:
              schema:
                type: object
                required:
                - valid
                - reason
                properties:
                  valid:
                    type: boolean
                  reason:
                    type: string
                    description: 'A VERDICT about the receipt. One of:

                      ok | request_hash_mismatch | response_hash_mismatch |

                      signature_invalid | unknown_key_id |

                      unsupported_receipt_version | decision_hash_missing |

                      decision_hash_mismatch | decision_hash_unsigned


                      `unknown_key_id` means the envelope names a key_id we do

                      not publish, so we never issued that receipt. It is a

                      verdict, not an error: key_id is caller-supplied, and an

                      unrecognised one must not be able to produce a 5xx.


                      `verification_error` is returned with 400, not 200 — see

                      below. A verdict is never reached with HTTP 503.

                      '
                    example: ok
        '400':
          description: 'The request could not be processed: the body is not a JSON object,

            a required field is missing, or the envelope could not be parsed

            (`bad_request` / `missing_fields` / `verification_error`). Shape is

            `{valid: false, reason, message}`.

            '
          content:
            application/json:
              schema:
                type: object
                required:
                - valid
                - reason
                properties:
                  valid:
                    type: boolean
                    description: Always false on a 400.
                  reason:
                    type: string
                    enum:
                    - bad_request
                    - missing_fields
                    - verification_error
                  message:
                    type: string
                    description: Human-readable explanation of what was wrong.
        '503':
          description: 'NO VERDICT WAS REACHED. We publish a key for the `key_id` on the

            envelope and could not load it — the value is unset or is not an

            importable Ed25519 key — so this endpoint cannot say anything about

            the receipt. `reason` is `verifier_unavailable`.


            A `key_id` we do NOT publish is a different answer:

            `200 unknown_key_id`. We never published that key, so we never

            issued that receipt — that is a verdict, and it stays 200 because

            `key_id` is caller-supplied and an unrecognised one must not be able

            to produce a 5xx.


            DO NOT treat this as a failed verification. The receipt may be

            perfectly genuine; the fault is ours. Honour `Retry-After` and ask

            again, or verify offline against a public key you already cached.


            Before 2026-10-11 this condition was served as

            `200 {valid: false, reason: "signature_invalid"}` — i.e. a genuine

            receipt was reported as forged, with a success status. If you have

            logic keyed on that, it was always wrong and this is the fix.

            '
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying.
            Cache-Control:
              schema:
                type: string
                enum:
                - no-store
              description: 'Always `no-store`. An outage must not be cached: a shared cache pinning this response would turn a momentary misconfiguration into minutes of refused verification.'
          content:
            application/json:
              schema:
                type: object
                required:
                - valid
                - reason
                properties:
                  valid:
                    type: boolean
                    description: 'Always false. Present because the schema requires it and

                      because false is the safe direction — never read it as a

                      statement that the receipt is invalid. The status code and

                      `reason` are what carry the meaning here.

                      '
                  reason:
                    type: string
                    enum:
                    - verifier_unavailable
      tags:
      - Receipts
components:
  schemas:
    Receipt:
      type: object
      description: 'Cryptographic decision receipt — an Ed25519 signature over canonical

        hashes of the request + response of a single forecast call. Anyone

        with the published public key (see /.well-known/blackwall-signing-keys.json)

        can verify offline without contacting Black_Wall.


        We sign and store HASHES ONLY — the raw request/response bodies are

        never persisted on our side. To verify later, you (or your auditor)

        provide the bodies and we re-hash to check against the signed envelope.

        '
      required:
      - id
      - forecast_id
      - issued_at
      - algorithm
      - key_id
      - request_hash
      - response_hash
      - signature
      properties:
        id:
          type: string
          description: Receipt's own UUID (distinct from forecast_id).
          example: 1b3f25a8-9c4e-4f0a-9b1d-2d0e5c6b7a89
        forecast_id:
          type: string
          description: The forecast this receipt vouches for.
        issued_at:
          type: string
          format: date-time
        algorithm:
          type: string
          enum:
          - ed25519
        key_id:
          type: string
          description: 'Which signing key was used. Look it up in

            /.well-known/blackwall-signing-keys.json. Receipts issued before

            a key rotation continue to verify against the retired key.

            '
          example: k1
        request_hash:
          type: string
          description: SHA-256 (hex) of canonical(request_body), prefixed `sha256:`.
          example: sha256:9af4...8c2e
        response_hash:
          type: string
          description: SHA-256 (hex) of canonical(response_body without receipt), prefixed `sha256:`.
          example: sha256:3d1c...e7b0
        signature:
          type: string
          description: Base64url Ed25519 signature over the canonicalized envelope (minus signature).
        verify_url:
          type: string
          format: uri
          description: Convenience URL for POST verification.
          example: https://blackwalltier.com/api/v1/receipts/verify
    Error:
      type: object
      properties:
        error:
          type: string
          description: Machine-readable error slug
          example: insufficient_tokens
        message:
          type: string
          description: Human-readable explanation
        details:
          type: object
          additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Pass your API key as a Bearer token in the Authorization header.

        Keys are prefixed `bw_live_` (or `bw_test_` if you''re in test mode).

        '