fetch-price API

openapi: 3.1.0
info:
  title: fetch-price 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.
    One POST returns real listings with live GBP prices, condition, marketplace and an affiliate-tracked
    purchase URL, normalised to one JSON shape. eBay UK is live via the official eBay Browse API; Amazon
    UK is rolling out and currently returns a tracked search link (result_type search_link) rather than
    items. The free tier needs no API key (50 lookups/month); registering an agent issues an fp_-prefixed
    key that raises limits and enables bring-your-own affiliate tracking (BYOK) on paid plans. Every
    response carries X-RateLimit-Limit and X-RateLimit-Remaining; the fixed limit is 30 requests per
    minute per key or per IP. Purchase links are affiliate-tracked and the provider asks agents to pass
    that disclosure on to the human (https://fetch-price.com/privacy).
    PROVENANCE - the provider publishes no OpenAPI. This document was written by API Evangelist from the
    provider's own API reference at https://fetch-price.com/docs/ (the endpoint tables, field tables and
    captured live responses), the first-party SDK sources and the stdio MCP server source in
    https://github.com/fusionx212/fetch-price, and was checked against live unauthenticated responses
    from api.fetch-price.com on 2026-09-19 (see x-provenance). It is a description of a real, exercised
    API, not a first-party contract; treat the provider's docs as authoritative where they differ.
  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
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)
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
- name: Agents
  description: Agent registration and API key issuance
- name: Service
  description: Health and public statistics
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'
  /api/agents/register:
    post:
      operationId: registerAgent
      summary: Register an agent and receive an API key
      description: >-
        Creates an agent record and returns an fp_-prefixed API key on the free tier (50 lookups/month).
        name, owner, networks and endpoint are all required; commission_split is optional. On a paid plan
        the networks object carries your own affiliate identifiers (an eBay Partner Network campaign_id;
        an Amazon Associates tag) so returned links carry your tracking (BYOK). The key is emailed to the
        registering address and is never shown in a public response after issuance; account deletion and
        key revocation are by email to the provider (https://fetch-price.com/privacy). Not exercised by
        API Evangelist because it creates an account.
      tags:
      - Agents
      security:
      - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterAgentRequest'
            examples:
              docs-register:
                summary: The registration example from the provider's docs (placeholders as published)
                value:
                  name: MyShoppingAgent
                  owner: you@example.com
                  networks:
                    ebay_uk:
                      campaign_id: YOUR_EPN_CAMPAIGN_ID
                  endpoint: https://your-agent.example.com
      responses:
        '200':
          description: Agent created; the response shape as published in the docs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterAgentResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /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:
  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.
  headers:
    X-RateLimit-Limit:
      description: Requests allowed per minute for this key or IP (observed value 30)
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests remaining in the current minute window
      schema:
        type: integer
  schemas:
    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
    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.
    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.
    QueryMeta:
      type: object
      properties:
        query:
          type: string
        networks_searched:
          type: array
          items:
            $ref: '#/components/schemas/Network'
        returned:
          type: integer
    QueryResponse:
      type: object
      required:
      - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Result'
        meta:
          $ref: '#/components/schemas/QueryMeta'
    RegisterAgentRequest:
      type: object
      required:
      - name
      - owner
      - networks
      - endpoint
      properties:
        name:
          type: string
          description: Agent name
        owner:
          type: string
          format: email
          description: Contact email; the API key is emailed here
        networks:
          type: object
          description: Per-network affiliate configuration keyed by network id. The docs show ebay_uk with a campaign_id (eBay Partner Network) and the home page shows amazon_uk with a tag (Amazon Associates). BYOK routing applies on paid plans only.
          additionalProperties:
            type: object
            properties:
              campaign_id:
                type: string
                description: eBay Partner Network campaign id (ebay_uk)
              tag:
                type: string
                description: Amazon Associates tag (amazon_uk)
        endpoint:
          type: string
          format: uri
          description: The agent's own endpoint URL
        commission_split:
          description: Optional; type not published
    RegisterAgentResponse:
      type: object
      properties:
        agent_id:
          type: string
          description: Prefixed agent-
        api_key:
          type: string
          description: Prefixed fp_
        tier:
          type: string
          example: free
        query_limit:
          type: integer
          example: 50
    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
    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: {}