Agentic Fabrication Network Attestations API

openapi: 3.2.0
info:
  title: AFN — Agentic Fabrication Network Attestations API
  version: 0.3.0
  description: 'The agent-facing API of AFN, a network speaking UFP — the Universal Fabrication Protocol (the aggregator profile): quote, refine, checkout, track. Live processes: decals/stickers, FDM 3D printing, paper print (cards/flyers/posters), sheet metal, CNC machining, resin 3D printing (SLA/DLP), laser cutting, and apparel; US shipping. Human-readable docs at /docs; full schema spec at /docs/protocol.md; vendor-hosted binding at /docs/vendor-binding.md; agent summary at /llms.txt.'
servers:
- url: https://agenticfabricationnetwork.ai
security:
- bearerAuth: []
tags:
- name: Attestations
paths:
  /v1/attestations:
    post:
      summary: Vendor-attested off-network transaction (vendor key auth)
      description: 'Vendors report transactions that happened outside this network — direct agent-to-vendor over the UFP vendor binding, or any other channel — to earn reputation credit and feed demand-gap routing. Auth is a vendor attestation key (ufp_vk_…), never an agent key; vendor identity comes from the key, a vendor_id in the payload is ignored. Idempotent on attestation_id: resubmitting updates (quoted_only → fulfilled). Credit is a ladder: bare attestation = partial, always labeled attested_transaction; evidence makes it spot-checkable; buyer confirmation = full (an unverified token never earns full). Full doc: /docs/attestations.md.'
      security:
      - vendorKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionAttestation'
      responses:
        '200':
          description: Attestation receipt — graded credit plus a detail string saying exactly what would have earned more
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttestationReceipt'
        '400':
          description: Malformed attestation (per-field issues in the body)
        '401':
          description: Missing or unknown vendor attestation key
      tags:
      - Attestations
      operationId: postV1Attestations
      x-operation-id-source: derived
components:
  schemas:
    TransactionAttestation:
      type: object
      required:
      - attestation_id
      - ufp_version
      - request
      - outcome
      - occurred_at
      properties:
        attestation_id:
          type: string
          description: Vendor-generated idempotency key — resubmitting the same id updates the attestation (quoted_only → fulfilled), never duplicates
        ufp_version:
          type: string
          example: 0.3.0
        request:
          type: object
          description: What the buyer asked for — raw, pre-resolution (demand-signal grade)
          properties:
            process:
              type: string
              enum:
              - fdm_print
              - resin_print
              - powder_print
              - metal_print
              - elastomer_print
              - cnc
              - sheetmetal
              - laser_cut
              - decal
              - print
              - apparel
            spec:
              type: object
              additionalProperties: true
            constraints:
              type: object
              additionalProperties: true
        offer:
          type: object
          description: What was offered/made. Prices may be omitted if commercially sensitive (less credit)
          properties:
            spec_resolved:
              type: object
              additionalProperties: true
            quantity:
              type: integer
            subtotal_cents:
              type: integer
        outcome:
          type: string
          enum:
          - quoted_only
          - ordered
          - fulfilled
          - cancelled
          - refunded
          - lost_capability_gap
        gaps:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              requested:
                description: string or number
              provided:
                description: string or number; null = the sale was lost on this gap
              reason:
                type: string
                enum:
                - vendor_minimum
                - vendor_maximum
                - out_of_stock
                - capability_gap
                - lead_time
                - price
                - other
              note:
                type: string
          description: What could not be delivered as asked — e.g. {field:"quantity", requested:3, provided:10, reason:"vendor_minimum"}. Feeds the network's demand-gap routing.
        occurred_at:
          type: string
          format: date-time
        fulfilled_at:
          type: string
          format: date-time
        evidence:
          type: object
          additionalProperties: true
          description: 'Evidence bundle — mandatory when available, never necessitated: tracking (or a declared-untracked marker), request/offer/file payload hashes, result photos, invoice_ref, delivered_at, buyer_hash (HMAC — no PII), buyer_confirmation_token'
    AttestationReceipt:
      type: object
      properties:
        attestation_id:
          type: string
        status:
          type: string
          enum:
          - accepted
          - pending_buyer_confirmation
          - rejected
        reputation_credit:
          type: string
          enum:
          - none
          - partial
          - full
        detail:
          type: string
          description: 'The feedback loop: exactly what would have earned more credit'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key from POST /v1/agents, e.g. ''Authorization: Bearer ufp_sk_...'''
    vendorKey:
      type: http
      scheme: bearer
      description: 'Vendor attestation key (''Authorization: Bearer ufp_vk_...'') — issued by the network operator to vendors, distinct from agent API keys. Used only on POST /v1/attestations.'