openapi: 3.2.0
info:
  title: fetch-price Products 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: Products
  description: Live UK marketplace product and price search
paths:
  /api/query:
    post:
      operationId: queryProducts
      summary: Search live UK marketplace listings
      description: 'Plain-language product search across the supported UK marketplaces. Returns normalised results with live GBP prices, condition, marketplace, image and a direct affiliate-tracked purchase URL. Every result declares result_type: "item" is a real listing with a live price; "search_link" is a tracked marketplace search URL with price 0, served for networks not yet live (Amazon UK) or when an upstream API is briefly unavailable. Works without a key on the free tier (50 lookups/month, counted per IP); send X-API-Key or a Bearer token to use a registered agent''s quota and BYOK affiliate routing. GET on this path returns 405.'
      tags:
      - Products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
            examples:
              docs-quickstart:
                summary: The quick-start request from the provider's docs
                value:
                  query: portable air conditioner
                  max_results: 3
                  max_price: 300
                  networks:
                  - ebay_uk
      responses:
        '200':
          description: Search results
          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/QueryResponse'
              examples:
                docs-live-response:
                  summary: Live response captured by the provider on 27 Jul 2026 (from the docs)
                  value:
                    results:
                    - product: Air Conditioning 5460BTU Remote Control Portable Air Conditioner Smart AC
                      price: 275.99
                      currency: GBP
                      condition: New
                      network: ebay_uk
                      result_type: item
                      item_id: v1|358845422976|0
                      image: https://i.ebayimg.com/images/g/.../s-l225.jpg
                      url: https://www.ebay.co.uk/itm/358845422976?...&campid=...
                    meta:
                      query: portable air conditioner
                      networks_searched:
                      - ebay_uk
                      returned: 3
        '400':
          description: Validation error (observed live with an empty body)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                query-required:
                  summary: Observed 2026-09-19 for POST /api/query with body {}
                  value:
                    error: query required
                    results: []
        '401':
          description: Key rejected. The MCP server maps this to "unauthorised - set FETCH_PRICE_API_KEY or register for a free key at fetch-price.com".
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method not allowed (observed for GET)
        '429':
          description: Rate limit exceeded - 30 requests/minute per key or per IP, or the plan's monthly lookup quota
          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/Error'
components:
  schemas:
    QueryRequest:
      type: object
      required:
      - query
      properties:
        query:
          type: string
          maxLength: 200
          description: Plain-language product search, max 200 chars
        max_results:
          type: integer
          minimum: 1
          maximum: 20
          default: 5
          description: Items per network. Default 5, max 20
        max_price:
          type: number
          description: Upper price bound in GBP, applied at source
        networks:
          type: array
          description: 'Marketplaces to search. Default: both. Send only when choosing - an empty array is rejected as "no valid networks" (per the first-party SDK).'
          items:
            $ref: '#/components/schemas/Network'
        min_price:
          type: number
          description: Lower price bound in GBP. Sent by the first-party JavaScript and Python SDKs; not in the docs field table.
        currency:
          type: string
          default: GBP
          description: Sent by the first-party SDKs (always GBP); not in the docs field table.
    QueryResponse:
      type: object
      required:
      - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Result'
        meta:
          $ref: '#/components/schemas/QueryMeta'
    QueryMeta:
      type: object
      properties:
        query:
          type: string
        networks_searched:
          type: array
          items:
            $ref: '#/components/schemas/Network'
        returned:
          type: integer
    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
    Error:
      type: object
      description: 'Plain JSON error envelope (not RFC 9457): a human-readable error string; /api/query also returns an empty results array.'
      required:
      - error
      properties:
        error:
          type: string
        results:
          type: array
          items: {}
    Result:
      type: object
      description: One normalised listing. Item results include product, price, currency, condition, network, url, image and item_id.
      required:
      - product
      - price
      - currency
      - network
      - result_type
      - url
      properties:
        product:
          type: string
        price:
          type: number
          description: Live price in GBP; 0 for a search_link result
        currency:
          type: string
          example: GBP
        condition:
          type: string
          example: New
        network:
          $ref: '#/components/schemas/Network'
        result_type:
          type: string
          description: item = a real listing with a live price and item-level affiliate-tracked buy link; search_link = a tracked marketplace search URL with price 0, served for networks not yet live or if the upstream API is briefly unavailable. Never present a search_link to a user as though it were a product.
          enum:
          - item
          - search_link
        item_id:
          type: string
          description: Marketplace item identifier (eBay Browse API form, e.g. v1|358845422976|0)
        image:
          type:
          - string
          - 'null'
          format: uri
        url:
          type: string
          format: uri
          description: Direct purchase URL, affiliate-tracked by the marketplace. Present to the user unchanged.
  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)