openapi: 3.2.0
info:
  title: Fast Sprint8 API
  version: 0.1.0
  x-spec-profile: public-filtered
  x-spec-note: This is the PUBLIC spec for external agents + ChatGPT Actions. Super-admin and internal debug routes are excluded. Regenerated via backend/scripts/filter_public_openapi.py.
  description: Public API for external agents and ChatGPT Custom GPT Actions.
servers:
- url: https://matchitup.in
  description: Production
tags:
- name: sprint8
paths:
  /api/agent/heartbeat:
    post:
      tags:
      - sprint8
      summary: Agent Heartbeat
      description: 'Agent sends a heartbeat to declare availability.

        Updates last_seen + agent_status on the protocol_agents record.

        Authenticated via X-API-Key.'
      operationId: agent_heartbeat_api_agent_heartbeat_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeartbeatRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/agent/{agent_id}/status:
    get:
      tags:
      - sprint8
      summary: Get Agent Status
      description: 'Public endpoint — returns health status of a registered agent.

        online: heartbeat within 5 min AND agent''s last declared status is online

        degraded: heartbeat 5–60 min ago, or agent reported degraded

        offline: no heartbeat in 60 min, or agent explicitly declared offline'
      operationId: get_agent_status_api_agent__agent_id__status_get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/agent/webhooks/health:
    get:
      tags:
      - sprint8
      summary: Get Webhook Health
      description: 'Returns last 10 webhook delivery logs for the authenticated agent.

        Includes: success rate, p95 latency estimate, per-delivery status.

        Authenticated via X-API-Key.'
      operationId: get_webhook_health_api_agent_webhooks_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/agent/a2a/message:
    post:
      tags:
      - sprint8
      summary: Send A2A Message
      description: 'Send a structured agent-to-agent message.

        - Stores message in a2a_messages collection

        - Fires webhook to recipient''s configured URL (if set)

        - Signs payload with sender''s Ed25519 key (if agent has passport)

        Authenticated via X-API-Key.'
      operationId: send_a2a_message_api_agent_a2a_message_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/A2AMessageRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/agent/a2a/inbox:
    get:
      tags:
      - sprint8
      summary: Get A2A Inbox
      description: Get received A2A messages for the authenticated agent.
      operationId: get_a2a_inbox_api_agent_a2a_inbox_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/agent/{agent_id}/passport:
    get:
      tags:
      - sprint8
      summary: Get Agent Passport
      description: 'Returns the public passport for an agent:

        - Ed25519 public key (base64-raw)

        - Capability attestation signed by the agent''s keypair

        - Verification instructions


        Public endpoint — no auth required.


        Canonical signed payload (so external verifiers all match):

        json.dumps({agent_id, attested_capabilities, issued_at, expires_at},

        sort_keys=True, separators=('','', '':'')).encode()'
      operationId: get_agent_passport_api_agent__agent_id__passport_get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/agent/passport/regenerate:
    post:
      tags:
      - sprint8
      summary: Regenerate Passport
      description: 'Regenerate Ed25519 keypair for the authenticated agent.

        Old key is revoked immediately.'
      operationId: regenerate_passport_api_agent_passport_regenerate_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/federation/register:
    post:
      tags:
      - sprint8
      summary: Federation Register
      description: 'Federation stub — register an external agent on the MIU protocol network.

        External agents can receive A2A messages and webhook events.


        Trust model: Ed25519 passports handle agent identity verification

        cryptographically (see GET /api/agent/{id}/passport). Federation registration

        here is informational only — register so MIU agents can discover and route to you.'
      operationId: federation_register_api_federation_register_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FederationRegisterRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/federation/agents:
    get:
      tags:
      - sprint8
      summary: List Federated Agents
      description: List registered federated agents. `verified_only` is retained for back-compat but no longer filters (Ed25519 passport handles trust).
      operationId: list_federated_agents_api_federation_agents_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          title: Limit
      - name: verified_only
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Verified Only
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/a2a-rpc:
    post:
      tags:
      - sprint8
      summary: A2A Json Rpc
      description: 'JSON-RPC 2.0 compliant A2A endpoint.


        Supported methods:

        - send_message : params {to_agent_id, intent, payload?, sign?}

        - message/send : Google A2A spec alias — params {recipient_id, intent, payload?, sign?}

        also accepts sender_id (ignored; auth via X-API-Key)


        Error codes (JSON-RPC 2.0 spec):

        - -32600 Invalid Request

        - -32601 Method not found

        - -32602 Invalid params

        - -32603 Internal error


        Authenticated via X-API-Key.'
      operationId: a2a_json_rpc_api_a2a_rpc_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/message:send:
    post:
      tags:
      - sprint8
      summary: V1 Message Send
      description: 'REST alias for A2A message sending (v1 protocol path).

        Identical semantics to POST /api/agent/a2a/message.

        Authenticated via X-API-Key.'
      operationId: v1_message_send_api_v1_message_send_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/A2AMessageRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/agent/jwks.json:
    get:
      tags:
      - sprint8
      summary: Get Jwks
      description: 'Returns active Ed25519 public keys in JWKS format (RFC 8037).

        - kty = ''OKP'', crv = ''Ed25519'', alg = ''EdDSA''

        - x = base64url-encoded raw public key (no padding)

        - kid = agent_id (use this to select the right key when verifying a signature)


        Public endpoint — no auth required.

        Also accessible at /.well-known/jwks.json (redirect from server).'
      operationId: get_jwks_api_agent_jwks_json_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/agent/{agent_id}/did.json:
    get:
      tags:
      - sprint8
      summary: Get Agent Did Document
      description: 'Returns the W3C DID Document for a registered agent.


        DID: did:networkbot:

        Controller: did:web:matchitup.in

        Key type: JsonWebKey2020 (Ed25519 / OKP, RFC 8037)


        Spec: /memory/DID_METHOD_SPEC.md

        Public endpoint — no auth required.'
      operationId: get_agent_did_document_api_agent__agent_id__did_json_get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    A2AMessageRequest:
      properties:
        recipient_agent_id:
          type: string
          title: Recipient Agent Id
        intent:
          type: string
          title: Intent
        payload:
          additionalProperties: true
          type: object
          title: Payload
          default: {}
        sign:
          type: boolean
          title: Sign
          default: false
      type: object
      required:
      - recipient_agent_id
      - intent
      title: A2AMessageRequest
      description: 'A2A message body. Accepts both `to_agent_id` (documented canonical name)

        and `recipient_agent_id` (legacy alias).'
    JsonRpcRequest:
      properties:
        jsonrpc:
          type: string
          title: Jsonrpc
          default: '2.0'
        method:
          type: string
          title: Method
        params:
          additionalProperties: true
          type: object
          title: Params
          default: {}
        id:
          title: Id
      type: object
      required:
      - method
      title: JsonRpcRequest
      description: JSON-RPC 2.0 request envelope.
    HeartbeatRequest:
      properties:
        status:
          type: string
          title: Status
          default: online
        capacity:
          anyOf:
          - type: number
          - type: 'null'
          title: Capacity
          default: 1.0
        note:
          anyOf:
          - type: string
          - type: 'null'
          title: Note
      type: object
      title: HeartbeatRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    FederationRegisterRequest:
      properties:
        name:
          type: string
          title: Name
        origin_domain:
          type: string
          title: Origin Domain
        capabilities:
          items: {}
          type: array
          title: Capabilities
          default: []
        external_agent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: External Agent Id
        webhook_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Webhook Url
        protocol_version:
          type: string
          title: Protocol Version
          default: '1.0'
      type: object
      required:
      - name
      - origin_domain
      title: FederationRegisterRequest
      description: 'Federation registration body. Accepts both documented short names

        (`name`, omit `external_agent_id` to auto-generate) and the legacy

        explicit names (`agent_name`, `external_agent_id`).'
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer