blackwalltier-com Forecast API

openapi: 3.2.0
info:
  title: Black_Wall Forecast 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: Forecast
paths:
  /v1/forecast:
    post:
      summary: Predict the outcome of a proposed action
      description: 'Send a description of an action the agent is about to take.

        Receive a forecast: predicted outcome, risk score, red flags, GO/CAUTION/STOP.


        Token cost typically 50–200 per call (depth: standard), 250–800 (depth: deep).

        Charge is debited from the caller''s account on success.


        Returns 402 if the account has insufficient tokens.

        Returns 429 if rate-limited.'
      operationId: createForecast
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForecastRequest'
            examples:
              email:
                summary: Email send check
                value:
                  action: send_email
                  inputs:
                    to: client@acme.com
                    subject: Invoice
                    body: Hi Sarah, attached is invoice
                  context:
                    agent_role: AR collections bot
                    user_intent: Send overdue invoice reminder
                    prior_actions:
                    - fetched_invoice_4521
                    - verified_amount_against_stripe
                  options:
                    depth: standard
              sql:
                summary: SQL write check
                value:
                  action: run_sql
                  inputs:
                    statement: UPDATE customers SET status = 'archived' WHERE last_login < '2024-01-01'
                  context:
                    agent_role: data cleanup bot
                    user_intent: Archive long-inactive customers
                  options:
                    depth: deep
      responses:
        '200':
          description: Forecast successfully generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForecastResponse'
        '400':
          description: Missing or malformed fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Insufficient tokens — top up to continue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Forecast
  /v1/forecast/{id}/outcome:
    patch:
      summary: Report the actual outcome of a forecast
      description: 'After your agent executes (or aborts) the action, send back what

        actually happened. This builds the dataset that compounds prediction

        accuracy for all Black_Wall customers (yours and others). Opt-in.


        Reporting outcomes is FREE — no token cost.'
      operationId: reportOutcome
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: The forecast ID returned in the original POST response
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutcomeReport'
      responses:
        '200':
          description: Outcome recorded
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  id:
                    type: string
                    description: The forecast id the outcome was recorded against.
        '400':
          description: 'The body is not JSON, or is JSON that is not an object — `null`, a

            number, a string, a boolean or an array (`bad_request`); or it is an

            object whose `actual_outcome` is absent or is not itself an object

            (`missing_fields`). `message` is present on every arm but the

            unparseable-JSON one.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Forecast not found (or not owned by caller)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Forecast
components:
  schemas:
    ForecastRequest:
      type: object
      required:
      - action
      - inputs
      properties:
        action:
          type: string
          description: 'What the agent intends to do. Free-form, but consistent values help

            us build per-action accuracy stats. Common values:

            send_email, send_sms, slack_post, run_sql, file_write, file_delete,

            api_call, make_payment, refund, transfer, issue_invoice,

            grant_permission, rotate_key, create_share_link,

            purchase, accept_contract, publish_content.

            '
          example: send_email
        inputs:
          type: object
          description: The concrete payload of the action.
          additionalProperties: true
          example:
            to: client@acme.com
            subject: Invoice
            body: Hi Sarah, attached is invoice
        context:
          type: object
          properties:
            agent_role:
              type: string
              example: AR collections bot for SaaS startup
            user_intent:
              type: string
              example: Send overdue invoice reminder
            prior_actions:
              type: array
              items:
                type: string
              example:
              - fetched_invoice_4521
              - verified_amount_against_stripe
            prior_findings:
              type: array
              description: 'Optional risk signals from analysis tools that ran BEFORE this call

                (e.g. a multi-agent test harness that flagged a risky agent, tool, or

                interaction edge offline). The gate treats these as PRIORS, not verdicts:

                a finding that matches this action raises the risk and can justify

                CONFIRM/STOP, but the runtime forecast still decides from the concrete

                action + inputs + reversibility. Findings contradicted by the actual

                inputs are down-weighted.

                '
              items:
                type: object
                properties:
                  source:
                    type: string
                    description: What produced the finding.
                    example: swarm-test
                  agent_role:
                    type: string
                    example: data cleanup bot
                  tool_name:
                    type: string
                    example: run_sql
                  edge:
                    type: string
                    description: Interaction edge, source_role → target_role.
                    example: planner → executor
                  risk_type:
                    type: string
                    example: cascade
                  severity:
                    type: string
                    enum:
                    - low
                    - medium
                    - high
                    - critical
                    example: critical
                  blast_radius:
                    type: integer
                    minimum: 0
                    maximum: 100
                    example: 80
                  recommendation:
                    type: string
                    description: The upstream tool's suggested verdict (advisory only).
                    example: STOP
                  note:
                    type: string
              example:
              - source: swarm-test
                agent_role: data cleanup bot
                tool_name: run_sql
                edge: planner → executor
                risk_type: cascade
                severity: critical
                blast_radius: 80
                recommendation: STOP
        options:
          type: object
          properties:
            depth:
              type: string
              enum:
              - standard
              - deep
              default: standard
              description: deep mode costs ~1.5-2x more tokens (and runs ~10-13s vs 4-8s) but returns reasoning trace + counterfactuals + mitigations
    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
    ForecastResponse:
      type: object
      required:
      - id
      - recommendation
      - risk_score
      - gate
      - reversibility
      - predicted_result
      - red_flags
      - tokens_charged
      - latency_ms
      properties:
        id:
          type: string
          example: fc_01JKABCD1234567890
        parent_forecast_id:
          type: string
          description: 'Echoed only when the request supplied parent_forecast_id (per-call swarm

            threading) — links this forecast to the parent action it was run under.

            '
        recommendation:
          type: string
          enum:
          - GO
          - CAUTION
          - STOP
        risk_score:
          type: integer
          minimum: 0
          maximum: 100
        confidence:
          type: number
          format: float
          minimum: 0
          maximum: 1
        gate:
          type: string
          enum:
          - AUTO
          - CONFIRM
          - HUMAN_REQUIRED
          description: 'The actionable control, derived from risk_score AND reversibility:

            AUTO = proceed automatically; CONFIRM = hold for human confirmation;

            HUMAN_REQUIRED = block until a human approves. An irreversible action

            is gated at a lower risk threshold than a reversible one.

            '
        reversibility:
          type: object
          description: Can the action be undone, and at what cost?
          properties:
            class:
              type: string
              enum:
              - REVERSIBLE
              - RECOVERABLE
              - IRREVERSIBLE
            rollback_cost:
              type: integer
              minimum: 0
              maximum: 100
              description: 0 = trivially undoable, 100 = permanent/catastrophic
            rollback_window_sec:
              type:
              - integer
              - 'null'
              description: Seconds available to undo; null = no window / permanent
            rationale:
              type: string
        predicted_result:
          type: object
          properties:
            outcome:
              type: string
              description: One-sentence prediction
              example: Email delivers; likely customer response is confusion or pushback.
            side_effects:
              type: array
              items:
                type: string
        red_flags:
          type: array
          items:
            type: object
            required:
            - severity
            - code
            - message
            properties:
              severity:
                type: string
                enum:
                - low
                - medium
                - high
                - critical
              code:
                type: string
                example: AMOUNT_UNVERIFIED
              message:
                type: string
        alternative_actions:
          type: array
          items:
            type: string
        decision_trace:
          type: array
          items:
            type: string
          description: Only present when depth is "deep"
        counterfactuals:
          type: array
          items:
            type: string
          description: Only present when depth is "deep"
        mitigations:
          type: array
          items:
            type: string
          description: Only present when depth is "deep"
        prior_findings_truncated:
          type: integer
          minimum: 1
          description: 'Only present when the per-call cap dropped some caller-supplied

            context.prior_findings — either more than 100 findings, or the array''s

            total serialized size exceeded the byte ceiling. The value is how many

            findings were dropped (the gate scored a subset of your swarm). Absent

            when nothing was dropped. Send fewer/smaller findings per call to clear it.

            '
        tokens_charged:
          type: integer
          example: 87
        latency_ms:
          type: integer
          example: 3400
        receipt:
          $ref: '#/components/schemas/Receipt'
        receipt_unavailable:
          type: string
          enum:
          - not_persisted
          - signing_failed
          description: 'Present ONLY when `receipt` is absent, and never alongside it. A receipt is

            attached if and only if its row was stored, so that a receipt you hold is

            always one `GET /v1/receipts/{id}` can honour. The forecast itself is

            unaffected (and is not re-charged) — you simply have no signed receipt for

            this call.


            `not_persisted` — the receipt was signed but its row did not land.

            `signing_failed` — the signature could not be produced.


            Both are issuer-side faults worth reporting. Neither is retried for you.


            Unsigned: like `receipt` and `confirmation`, strip this key before

            re-deriving `response_hash`.

            '
    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
    OutcomeReport:
      type: object
      required:
      - actual_outcome
      description: 'Body for PATCH /v1/forecast/{id}/outcome. Reports what actually

        happened after the action ran (or after it was deliberately not run

        because of a STOP verdict). The `actual_outcome` object is free-form

        jsonb on the server side, but the MCP `observe` tool and Black_Wall''s

        admin dashboard recognize the well-known fields below — using them

        gives consistent rendering and (later) accuracy-tracking analytics.

        '
      properties:
        actual_outcome:
          type: object
          properties:
            outcome_class:
              type: string
              enum:
              - matched
              - over_scope
              - under_scope
              - no_op
              - diverged
              - aborted
              description: 'How the actual outcome compared to the prediction.

                matched = exactly as predicted.

                over_scope = affected MORE than predicted (e.g. DELETE hit 1247 rows when 1 was expected).

                under_scope = affected less than predicted.

                no_op = action ran but had no effect.

                diverged = result was qualitatively different.

                aborted = action was NOT taken (e.g. agent obeyed a STOP/HUMAN_REQUIRED verdict).

                '
            divergence_severity:
              type: string
              enum:
              - none
              - low
              - medium
              - high
              - critical
              description: How bad the divergence was. Use `none` for `matched` or `aborted`.
            actual_targets:
              type: array
              items:
                type: string
              description: IDs / paths / hashes of what was actually affected.
            details:
              type: string
              description: Free-form details — error messages, observed side effects, etc.
              maxLength: 2000
            matched_prediction:
              type: boolean
              description: 'Deprecated boolean shortcut, kept for backward compatibility with the original

                outcome shape. Prefer `outcome_class`.

                '
          additionalProperties: true
        customer_notes:
          type: string
  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).

        '