openapi: 3.1.0
info:
  title: iAgentRef API (Shipping Q2 2026)
  description: |
    iAgentRef is the semantic search layer over ERC-8004 Identity Registry entries and independently-hosted agent-cards.
    This OpenAPI specification previews the planned API surface. Shipping Q2 2026 at https://api.iagentref.com/v1/.
    Until launch, endpoints return 503. After launch, endpoints accept x402 V2 payment for premium tiers.
  version: v1-preview
  contact:
    name: iJarvis LLC
    email: hello@iagentref.com
    url: https://ijarvis.ai
  license:
    name: Proprietary (API access under iAgentRef Terms of Service)
    url: https://iagentref.com/terms
servers:
  - url: https://api.iagentref.com/v1
    description: Planned production API (Q2 2026)
security:
  - x402: []
  - bearerAuth: []
components:
  securitySchemes:
    x402:
      type: http
      scheme: x402
      description: x402 V2 payment protocol. Send request; receive 402 if unpaid; attach X-Payment header and retry.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API-Key
paths:
  /status:
    get:
      summary: Service health check
      responses:
        '200': {description: Service healthy}
  /search:
    get:
      summary: Semantic search over ERC-8004 agents
      parameters:
        - {name: q, in: query, required: true, schema: {type: string}, description: Natural-language capability query}
        - {name: limit, in: query, schema: {type: integer, default: 10, maximum: 100}}
        - {name: min_rating, in: query, schema: {type: string, enum: [AAA, AA, A, BBB, BB, B]}}
      responses:
        '200':
          description: Matching agents ranked by relevance × rating
        '402':
          description: Payment required (free tier exceeded)
  /resolve/{agentRegistry}/{agentId}:
    get:
      summary: Resolve an agent by ERC-8004 identity
      parameters:
        - {name: agentRegistry, in: path, required: true, schema: {type: string}, description: CAIP-10 registry reference}
        - {name: agentId, in: path, required: true, schema: {type: integer}}
      responses:
        '200': {description: Agent card}
  /index:
    post:
      summary: Submit an agent-card for indexing (authenticated)
      security: [{bearerAuth: []}]
      responses:
        '202': {description: Accepted for indexing}
        '401': {description: Unauthorized}
