openapi: 3.0.3
info:
  title: ZapAds Discovery API (read-only subset)
  version: "1"
  description: |
    **Read-only subset retained for backward compatibility.** The canonical, full v1 spec —
    including provider/agent registration, key rotation, balance, invocations, and service
    writes — is at `/api/v1/openapi.yaml` (or `/openapi/v1.yaml` as a static asset).

    This file only documents the anonymous discovery endpoints. Responses include header
    `X-ZapAds-Version: 1`. Rate limits: anonymous 60 req/min per IP; with Bearer
    `zap_agent_...` minted via `POST /api/v1/agents/register`, 600 req/min.
servers:
  - url: /api/v1
paths:
  /services:
    get:
      summary: List services
      operationId: listServices
      parameters:
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
        - { name: offset, in: query, schema: { type: integer, minimum: 0, default: 0 } }
        - { name: tag, in: query, schema: { type: string } }
        - { name: category, in: query, schema: { type: string } }
        - { name: max_price, in: query, schema: { type: integer } }
        - { name: min_reputation, in: query, schema: { type: number } }
        - { name: q, in: query, schema: { type: string }, description: Full-text search }
        - name: sort
          in: query
          schema:
            type: string
            enum: [recent, price_asc, price_desc, reputation]
      responses:
        "200":
          description: OK
        "429":
          description: Rate limited — Retry-After header present
  /services/search:
    get:
      summary: Search services (same filters as /services)
      operationId: searchServices
      responses:
        "200":
          description: OK — meta may document filters
  /services/{id}:
    get:
      summary: Get one service by UUID
      operationId: getServiceById
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        "200":
          description: Single service
  /categories:
    get:
      summary: Categories with counts
      operationId: listCategories
      responses:
        "200":
          description: OK
  /providers/{id}:
    get:
      summary: Provider summary
      operationId: getProvider
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        "200":
          description: OK