FLINT Network Trust Graph API

openapi: 3.2.0
info:
  title: FLINT Agent Transaction Control Trust Graph 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: Trust Graph
  description: Read partner-safe aggregate agent reputation and graph health.
paths:
  /api/graph/agent/{flint_agent_id}:
    get:
      x-flint-release-state: production
      security: []
      tags:
      - Trust Graph
      operationId: lookupAgentReputation
      summary: Lookup partner-safe aggregate agent reputation
      description: Returns partner-facing aggregate reputation for a partner-scoped FLINT agent ID. Raw runtime provider identifiers and internal signal fields are not returned.
      parameters:
      - name: flint_agent_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^faid_[a-f0-9]{24}$
        description: Partner-scoped FLINT agent identifier.
      responses:
        '200':
          description: Agent reputation summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentReputationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/Unavailable'
  /api/graph/health:
    get:
      x-flint-release-state: production
      security: []
      tags:
      - Trust Graph
      operationId: getTrustGraphHealth
      summary: Check Trust Graph health
      description: Operational endpoint that checks Trust Graph configuration and connectivity.
      responses:
        '200':
          description: Trust Graph is reachable or intentionally unconfigured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphHealthResponse'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '502':
          $ref: '#/components/responses/BadGateway'
  /.well-known/flint.json:
    get:
      x-flint-release-state: production
      security: []
      tags:
      - Trust Graph
      operationId: getFlintTrustManifest
      summary: Get FLINT Trust Manifest
      description: Returns this domain's Trust Manifest for agent commerce authorization semantics.
      responses:
        '200':
          description: FLINT Trust Manifest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustManifest'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
components:
  schemas:
    AgentReputationResponse:
      type: object
      required:
      - ok
      - agent_reputation
      properties:
        ok:
          type: boolean
        agent_reputation:
          $ref: '#/components/schemas/AgentReputation'
    TrustManifest:
      type: object
      required:
      - version
      - requires_flint_authorization
      - partner_id
      properties:
        version:
          type: string
        issuer:
          type: string
        name:
          type: string
        description:
          type: string
        requires_flint_authorization:
          type: boolean
        partner_id:
          type: string
        authorization_record:
          type: object
        agent_commerce:
          type: object
        trust_graph:
          type: object
        outcome_feedback:
          type: object
        docs:
          type: object
        privacy:
          type: object
        contact:
          type: object
    AgentReputation:
      type: object
      required:
      - flint_agent_id
      - global_stats
      - runtime_diversity
      - principal_consistency
      - recent_outcomes
      properties:
        flint_agent_id:
          type: string
        global_stats:
          type: object
          required:
          - first_seen
          - total_transactions
          - dispute_rate
          properties:
            first_seen:
              type:
              - string
              - 'null'
              format: date-time
            total_transactions:
              type: integer
              minimum: 0
            dispute_rate:
              type: number
              minimum: 0
        runtime_diversity:
          type: integer
          minimum: 0
        principal_consistency:
          type: integer
          minimum: 0
        recent_outcomes:
          type: array
          items:
            type: string
            enum:
            - completed
            - disputed
            - flagged
    GraphHealthResponse:
      type: object
      required:
      - ok
      - status
      properties:
        ok:
          type: boolean
        status:
          type: string
          enum:
          - ok
          - configured
          - unconfigured
        latency_ms:
          type: integer
          minimum: 0
        message:
          type: string
    ErrorResponse:
      type: object
      properties:
        ok:
          type: boolean
        error:
          type: string
        detail:
          type: string
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unavailable:
      description: Service unavailable or not configured
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    MethodNotAllowed:
      description: HTTP method not allowed for this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadGateway:
      description: Upstream graph or service failure
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  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.'