openapi: 3.2.0
info:
  title: fetch-price Service API
  version: 1.3.0
  summary: Live UK marketplace product and price search for AI agents and humans
  description: Live UK marketplace product search operated by POLICYANDPLAY LTD at https://api.fetch-price.com.
  contact:
    name: fetch-price (POLICYANDPLAY LTD)
    url: https://fetch-price.com/docs/
    email: contact@fetch-price.com
  license:
    name: MIT (SDKs and MCP server; the API itself carries no published licence or terms page)
    url: https://github.com/fusionx212/fetch-price
  x-generated-from: documentation
  x-authored-by: API Evangelist
servers:
- url: https://api.fetch-price.com
  description: Production (the only base the provider publishes)
security:
- {}
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Service
  description: Health and public statistics
paths:
  /health:
    get:
      operationId: getHealth
      summary: Service health and marketplace reachability
      description: Read-only health check returning API availability, the API version, the configured networks and whether live eBay data is currently reachable (ebay_live), so calling agents can degrade gracefully. This is the backing call for the MCP tool service_status and the A2A skill service_status. Observed live 2026-09-19.
      tags:
      - Service
      security:
      - {}
      responses:
        '200':
          description: Health payload
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
              examples:
                observed:
                  summary: Observed 2026-09-19
                  value:
                    ebay_live: true
                    networks:
                    - ebay_uk
                    - amazon_uk
                    status: ok
                    version: 1.3.0
  /api/stats:
    get:
      operationId: getStats
      summary: Public service statistics
      description: Public counters - active registered agents, available networks and the API version. Observed live 2026-09-19.
      tags:
      - Service
      security:
      - {}
      responses:
        '200':
          description: Stats payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Stats'
              examples:
                observed:
                  summary: Observed 2026-09-19
                  value:
                    agents_active: 1
                    networks_available:
                    - ebay_uk
                    - amazon_uk
                    version: 1.2.0
components:
  schemas:
    Health:
      type: object
      properties:
        status:
          type: string
          example: ok
        version:
          type: string
        networks:
          type: array
          items:
            $ref: '#/components/schemas/Network'
        ebay_live:
          type: boolean
    Stats:
      type: object
      properties:
        agents_active:
          type: integer
        networks_available:
          type: array
          items:
            $ref: '#/components/schemas/Network'
        version:
          type: string
    Network:
      type: string
      description: Marketplace identifier. ebay_uk is live; amazon_uk is rolling out and returns a search_link result.
      enum:
      - ebay_uk
      - amazon_uk
  headers:
    X-RateLimit-Remaining:
      description: Requests remaining in the current minute window
      schema:
        type: integer
    X-RateLimit-Limit:
      description: Requests allowed per minute for this key or IP (observed value 30)
      schema:
        type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: fp_-prefixed key issued by POST /api/agents/register. Optional on the free tier (keyless requests are counted per IP); required to use a registered agent's plan quota and BYOK routing. The first-party SDKs send this header.
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: fp_-prefixed API key
      description: The same key sent as Authorization Bearer, which is how the stdio MCP server and the provider's SKILL.md send it.
x-provenance:
  method: generated
  generated: '2026-09-19'
  authored_by: API Evangelist
  publisher_openapi: none
  sources:
  - https://fetch-price.com/docs/
  - https://fetch-price.com/llms.txt
  - https://raw.githubusercontent.com/fusionx212/fetch-price/master/mcp/fetch_price_mcp.py
  - https://raw.githubusercontent.com/fusionx212/fetch-price/master/js/index.js
  - https://raw.githubusercontent.com/fusionx212/fetch-price/master/python/fetch_price/__init__.py
  exercised: true
  live_checks:
  - request: GET https://api.fetch-price.com/health
    http_status: 200
    body: '{"ebay_live":true,"networks":["ebay_uk","amazon_uk"],"status":"ok","version":"1.3.0"}'
  - request: GET https://api.fetch-price.com/api/stats
    http_status: 200
    body: '{"agents_active":1,"networks_available":["ebay_uk","amazon_uk"],"version":"1.2.0"}'
  - request: POST https://api.fetch-price.com/api/query with body {}
    http_status: 400
    body: '{"error":"query required","results":[]}'
    headers: x-ratelimit-limit 30, x-ratelimit-remaining 27, access-control-allow-origin *
  - request: GET https://api.fetch-price.com/api/query
    http_status: 405
  - request: GET https://api.fetch-price.com/
    http_status: 200
    body: '{"a2a":"POST / or /a2a (JSON-RPC 2.0, message/send)","agent_card":"/.well-known/agent-card.json","docs":"https://fetch-price.com/docs","health":"/health","query":"POST /api/query","service":"fetch-price API"}'
  not_exercised:
  - POST /api/agents/register creates an account and issues a key, so it was described from the docs only.
  - A successful POST /api/query consumes a free-tier lookup and runs a live eBay search; the 200 shape is the provider's captured live response of 27 Jul 2026 reproduced verbatim from the docs.
  openapi_probes_that_missed:
  - https://api.fetch-price.com/openapi.json (404)
  - https://api.fetch-price.com/openapi.yaml (404)
  - https://api.fetch-price.com/swagger.json (404)
  - https://api.fetch-price.com/docs (404)
  - https://fetch-price.com/openapi.json (404)