FLINT Network Outcome Feedback API

openapi: 3.2.0
info:
  title: FLINT Agent Transaction Control Outcome Feedback API
  version: 1.0.0
  description: FLINT verifies agent authority before autonomous economic activity, issues signed verification records, accepts outcome feedback, and returns partner-safe Trust Graph reputation.
  x-guidance: 'Use POST /api/x402/scan for a $0.01 x402-paid bounded pre-transaction scan of a separate intended commerce transaction. Use POST /api/x402/verify for high-assurance $0.01 x402-paid agent-authority verification after obtaining the required FLINT capability and DPoP proof. Free operations are explicitly marked with security: [].'
  contact:
    name: FLINT Support
    email: support@flint.network
    url: https://flint.network
  license:
    name: Proprietary
    identifier: LicenseRef-FLINT-Proprietary
servers:
- url: https://flint.network
  description: Production
security: []
tags:
- name: Outcome Feedback
  description: Submit transaction outcomes that seed Trust Graph reputation.
paths:
  /api/records/{record_id}/outcome:
    post:
      x-flint-release-state: staging
      security:
      - {}
      - WorkOSOwnerSession: []
      - bearerAgentSession: []
      - PartnerServiceBearer: []
      tags:
      - Outcome Feedback
      operationId: reportRecordOutcome
      summary: Report what actually happened after a Scout scan
      description: 'FLINT cannot stop a wallet; this is the enforce-or-attest half of the contract. Reports whether the scanned transaction executed, was held, or was cancelled. Auth is one of: a bearer or cookie session whose account owns the passport presented on the record, the anonymous caller_binding_token issued with the scan (open security, no scheme), or a partner service credential. Idempotent: the first write wins and a later write returns 409 with the existing outcome. Reporting executed or executed_despite_block after a BLOCK verdict is stored as an override, appended to the passport ledger, and alerts the passport owner through Sentinel.'
      parameters:
      - $ref: '#/components/parameters/RecordId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutcomeReportRequest'
      responses:
        '200':
          description: Outcome recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutcomeReportResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: No session, caller_binding_token, or partner credential was presented.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The presented session does not own the passport bound to this record, or the caller_binding_token does not match.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: An outcome was already reported for this record. The existing outcome is returned unchanged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutcomeReportResponse'
  /api/outcomes:
    post:
      x-flint-release-state: production
      security:
      - PartnerServiceBearer: []
      tags:
      - Outcome Feedback
      operationId: submitTransactionOutcome
      summary: Submit transaction outcome feedback
      description: Authenticated partner callback used after a transaction completes, is disputed, or is flagged. The bearer identity must match the partner bound into the stored signed record; caller-supplied partner ids are ignored.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutcomeRequest'
      responses:
        '201':
          description: Outcome accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutcomeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  responses:
    ServerError:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: The cheap caller-admission quota for paid attempts was exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid partner service credential
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: Conflict or idempotency collision
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Authenticated partner does not own the signed record
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    RecordId:
      name: record_id
      in: path
      required: true
      description: FLINT verification record identifier.
      schema:
        type: string
        pattern: ^frv_[0-9A-HJKMNP-TV-Z]{26}$
  schemas:
    OutcomeGroundTruthRequest:
      type:
      - object
      - 'null'
      description: Optional F3 ground truth. Null is retained as null. Omitted or null lists normalize to empty arrays; string IDs are trimmed, uppercased, checked against the F3 catalog, and deduplicated. Other object keys are ignored.
      properties:
        f3_techniques_confirmed:
          type:
          - array
          - 'null'
          items:
            type: string
        f3_techniques_rejected:
          type:
          - array
          - 'null'
          items:
            type: string
    ErrorResponse:
      type: object
      properties:
        ok:
          type: boolean
        error:
          type: string
        detail:
          type: string
    OutcomeGroundTruthResponse:
      type:
      - object
      - 'null'
      description: Null when ground truth was omitted or null; otherwise contains the 2 normalized F3 ID lists.
      required:
      - f3_techniques_confirmed
      - f3_techniques_rejected
      additionalProperties: false
      properties:
        f3_techniques_confirmed:
          type: array
          items:
            type: string
        f3_techniques_rejected:
          type: array
          items:
            type: string
    OutcomeReportResponse:
      type: object
      required:
      - ok
      - record_id
      - outcome
      properties:
        ok:
          type: boolean
        record_id:
          type: string
          pattern: ^frv_
        outcome:
          $ref: '#/components/schemas/RecordOutcome'
    OutcomeRequest:
      type: object
      required:
      - record_id
      - outcome
      properties:
        record_id:
          type: string
          pattern: ^frv_
          description: Signed verification record ID.
        outcome:
          type: string
          enum:
          - completed
          - disputed
          - flagged
        merchant_note:
          type:
          - string
          - 'null'
          maxLength: 500
          description: Optional merchant context. Accepts null or a string of at most 500 Unicode code points. Empty and whitespace-only strings are preserved.
        ground_truth:
          $ref: '#/components/schemas/OutcomeGroundTruthRequest'
        partner_id:
          type: string
          deprecated: true
          description: Ignored. The partner identity is derived from the bearer credential and must match the stored signed record. Retained for existing callers.
    OutcomeReportRequest:
      type: object
      additionalProperties: false
      required:
      - outcome
      properties:
        outcome:
          type: string
          enum:
          - executed
          - held
          - executed_despite_block
          - cancelled
        tx_hash:
          type: string
          pattern: ^0x[0-9a-fA-F]{64}$
          description: Required when outcome starts with executed.
        chain:
          type: string
          pattern: ^[-a-z0-9]{3,8}:[-_A-Za-z0-9]{1,32}$
        note:
          type: string
          maxLength: 280
        caller_binding_token:
          type: string
          description: Required to report anonymously as the caller instead of via session or partner credential.
    RecordOutcome:
      type: object
      description: What actually happened after a scan, as reported through POST /api/records/{record_id}/outcome. GET /api/records/{id} and GET /api/counterparty/{address} strip reporter.ref from this shape before returning it publicly; reporter.type is always kept.
      required:
      - outcome
      - reported_at
      - reporter
      - override
      properties:
        outcome:
          type: string
          enum:
          - executed
          - held
          - executed_despite_block
          - cancelled
        tx_hash:
          type:
          - string
          - 'null'
        chain:
          type:
          - string
          - 'null'
        reported_at:
          type: string
          format: date-time
        reporter:
          type: object
          required:
          - type
          properties:
            type:
              type: string
              enum:
              - owner_session
              - caller
              - partner
            ref:
              type:
              - string
              - 'null'
              description: Stripped from every public projection of this shape; present only in the reporter's own POST response.
        verdict_at_scan:
          type:
          - string
          - 'null'
        override:
          type: boolean
          description: True when verdict_at_scan was block and outcome starts with executed.
        tx_verified:
          type:
          - boolean
          - 'null'
          description: Best-effort etherscan check of tx_hash against the scanned counterparty and amount. null when Etherscan is not configured or the check was inconclusive; a definitive non-match is rejected 400 tx_hash_mismatch instead of being stored.
        ledger_recorded:
          type: boolean
          description: 'True only when an override was actually written to the passport''s Scout ledger and Sentinel was notified: requires the override to be reported while the record''s passport binding was credited, or by the passport owner''s own session.'
        reason:
          type:
          - string
          - 'null'
          enum:
          - passport_not_credited
          - null
          description: Set to passport_not_credited when an override could not be written to the passport's Scout ledger because the binding was not credited and the reporter was not the owner's session.
    OutcomeResponse:
      type: object
      required:
      - ok
      - outcome_id
      - record_id
      - outcome
      - ground_truth
      - stored_at
      properties:
        ok:
          type: boolean
        outcome_id:
          type: string
        record_id:
          type: string
        outcome:
          type: string
          enum:
          - completed
          - disputed
          - flagged
        ground_truth:
          $ref: '#/components/schemas/OutcomeGroundTruthResponse'
        stored_at:
          type: string
          format: date-time
  securitySchemes:
    WorkOSOwnerSession:
      type: apiKey
      in: cookie
      name: flint_session
      description: Sealed WorkOS session required for claimed-Passport owner actions. Unclaimed mandate updates require the claim token as a management capability.
    PartnerServiceBearer:
      type: http
      scheme: bearer
      description: Server-only partner credential. The authenticated partner must match the partner in the stored signed verification record.
    X402Payment:
      type: apiKey
      in: header
      name: PAYMENT-SIGNATURE
      description: Canonical x402 v2 payment proof on a paid retry. Initial unpaid challenge requests require no payment proof.
    FlintCapability:
      type: apiKey
      in: header
      name: FLINT-CAPABILITY
      description: Short-lived Passport-owner-issued capability bound to the exact x402 Verify request.
    DPoP:
      type: apiKey
      in: header
      name: DPoP
      description: Fresh caller proof bound to the capability, request, and x402 payment proof.
    X401Proof:
      type: apiKey
      in: header
      name: PROOF-RESPONSE
      description: Base64url-encoded x401 principal-identity presentation. Omit to request a proof challenge.
    bearerAgentSession:
      type: http
      scheme: bearer
      bearerFormat: flint_sess_...
      description: 'Agent session bearer token minted by POST /api/auth/otp-verify (Authorization: Bearer flint_sess_...). Accepted everywhere a WorkOSOwnerSession cookie is accepted, so an MCP agent never needs a browser. Also accepted via the X-FLINT-Session header.'