{
  "openapi": "3.1.0",
  "info": {
    "title": "SoldFetch eBay API",
    "version": "1.0.0",
    "description": "SoldComps-compatible core paths with documented limitations. Verified sale-date filters, accepted-offer hydration, and emailed exports are unavailable. All REST aliases require a SoldFetch API key."
  },
  "servers": [
    {
      "url": "https://soldfetch.com"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/v1/scrape": {
      "get": {
        "operationId": "search",
        "summary": "Sold listings",
        "description": "One upstream call per request. Up to 200 results. Unverified sale dates and displayed listing prices are explicitly marked. Successful responses consume one request; failed responses do not.",
        "parameters": [
          {
            "name": "keyword",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "sony wh-1000xm5"
            }
          },
          {
            "name": "ebaySite",
            "in": "query",
            "description": "Regional eBay site; availability is listed in capabilities.",
            "schema": {
              "type": "string",
              "enum": [
                "ebay.com",
                "ebay.co.uk",
                "ebay.de",
                "ebay.fr",
                "ebay.it",
                "ebay.es",
                "ebay.ca",
                "ebay.com.au"
              ],
              "default": "ebay.com"
            }
          },
          {
            "name": "categoryId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "0"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 1
            }
          },
          {
            "name": "count",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 60
            }
          },
          {
            "name": "sold",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "name": "itemCondition",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "any",
                "new",
                "used"
              ],
              "default": "any"
            }
          },
          {
            "name": "sortOrder",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "endedRecently",
                "timeNewlyListed",
                "pricePlusPostageLowest",
                "pricePlusPostageHighest"
              ],
              "default": "endedRecently"
            }
          },
          {
            "name": "minPrice",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "maxPrice",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "buyingFormat",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "auction",
                "buyItNow",
                "acceptsOffers"
              ],
              "default": "all"
            }
          },
          {
            "name": "exactMatch",
            "in": "query",
            "description": "Exclude explicitly marked loose matches. Does not guarantee product identity.",
            "schema": {
              "type": "boolean",
              "default": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized eBay response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          },
          "504": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/scrape/category": {
      "get": {
        "operationId": "category",
        "summary": "Category sold listings",
        "description": "One upstream call per request. Up to 200 results. Unverified sale dates and displayed listing prices are explicitly marked. Successful responses consume one request; failed responses do not.",
        "parameters": [
          {
            "name": "ebaySite",
            "in": "query",
            "description": "Regional eBay site; availability is listed in capabilities.",
            "schema": {
              "type": "string",
              "enum": [
                "ebay.com",
                "ebay.co.uk",
                "ebay.de",
                "ebay.fr",
                "ebay.it",
                "ebay.es",
                "ebay.ca",
                "ebay.com.au"
              ],
              "default": "ebay.com"
            }
          },
          {
            "name": "categoryId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "default": "0"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 1
            }
          },
          {
            "name": "count",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 60
            }
          },
          {
            "name": "sold",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "name": "itemCondition",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "any",
                "new",
                "used"
              ],
              "default": "any"
            }
          },
          {
            "name": "sortOrder",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "endedRecently",
                "timeNewlyListed",
                "pricePlusPostageLowest",
                "pricePlusPostageHighest"
              ],
              "default": "endedRecently"
            }
          },
          {
            "name": "minPrice",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "maxPrice",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "buyingFormat",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "auction",
                "buyItNow",
                "acceptsOffers"
              ],
              "default": "all"
            }
          },
          {
            "name": "exactMatch",
            "in": "query",
            "description": "Exclude explicitly marked loose matches. Does not guarantee product identity.",
            "schema": {
              "type": "boolean",
              "default": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized eBay response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          },
          "504": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/item/{itemId}": {
      "get": {
        "operationId": "product",
        "summary": "Item details",
        "description": "One upstream call per request. Up to 200 results. Unverified sale dates and displayed listing prices are explicitly marked. Successful responses consume one request; failed responses do not.",
        "parameters": [
          {
            "name": "itemId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{9,15}$",
              "example": "377534750427"
            }
          },
          {
            "name": "ebaySite",
            "in": "query",
            "description": "Regional eBay site; availability is listed in capabilities.",
            "schema": {
              "type": "string",
              "enum": [
                "ebay.com",
                "ebay.co.uk",
                "ebay.de",
                "ebay.fr",
                "ebay.it",
                "ebay.es",
                "ebay.ca",
                "ebay.com.au"
              ],
              "default": "ebay.com"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized eBay response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          },
          "504": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/public/scrape": {
      "get": {
        "operationId": "searchAlias0",
        "summary": "Sold listings",
        "description": "Compatibility path using a SoldFetch bearer token; RapidAPI gateway authentication is unavailable.",
        "parameters": [
          {
            "name": "keyword",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "sony wh-1000xm5"
            }
          },
          {
            "name": "ebaySite",
            "in": "query",
            "description": "Regional eBay site; availability is listed in capabilities.",
            "schema": {
              "type": "string",
              "enum": [
                "ebay.com",
                "ebay.co.uk",
                "ebay.de",
                "ebay.fr",
                "ebay.it",
                "ebay.es",
                "ebay.ca",
                "ebay.com.au"
              ],
              "default": "ebay.com"
            }
          },
          {
            "name": "categoryId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "0"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 1
            }
          },
          {
            "name": "count",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 60
            }
          },
          {
            "name": "sold",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "name": "itemCondition",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "any",
                "new",
                "used"
              ],
              "default": "any"
            }
          },
          {
            "name": "sortOrder",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "endedRecently",
                "timeNewlyListed",
                "pricePlusPostageLowest",
                "pricePlusPostageHighest"
              ],
              "default": "endedRecently"
            }
          },
          {
            "name": "minPrice",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "maxPrice",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "buyingFormat",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "auction",
                "buyItNow",
                "acceptsOffers"
              ],
              "default": "all"
            }
          },
          {
            "name": "exactMatch",
            "in": "query",
            "description": "Exclude explicitly marked loose matches. Does not guarantee product identity.",
            "schema": {
              "type": "boolean",
              "default": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized eBay response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          },
          "504": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/rapidapi/scrape-ebay": {
      "get": {
        "operationId": "searchAlias1",
        "summary": "Sold listings",
        "description": "Compatibility path using a SoldFetch bearer token; RapidAPI gateway authentication is unavailable.",
        "parameters": [
          {
            "name": "keyword",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "sony wh-1000xm5"
            }
          },
          {
            "name": "ebaySite",
            "in": "query",
            "description": "Regional eBay site; availability is listed in capabilities.",
            "schema": {
              "type": "string",
              "enum": [
                "ebay.com",
                "ebay.co.uk",
                "ebay.de",
                "ebay.fr",
                "ebay.it",
                "ebay.es",
                "ebay.ca",
                "ebay.com.au"
              ],
              "default": "ebay.com"
            }
          },
          {
            "name": "categoryId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "0"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 1
            }
          },
          {
            "name": "count",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 60
            }
          },
          {
            "name": "sold",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "name": "itemCondition",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "any",
                "new",
                "used"
              ],
              "default": "any"
            }
          },
          {
            "name": "sortOrder",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "endedRecently",
                "timeNewlyListed",
                "pricePlusPostageLowest",
                "pricePlusPostageHighest"
              ],
              "default": "endedRecently"
            }
          },
          {
            "name": "minPrice",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "maxPrice",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "buyingFormat",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "auction",
                "buyItNow",
                "acceptsOffers"
              ],
              "default": "all"
            }
          },
          {
            "name": "exactMatch",
            "in": "query",
            "description": "Exclude explicitly marked loose matches. Does not guarantee product identity.",
            "schema": {
              "type": "boolean",
              "default": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized eBay response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          },
          "504": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/capabilities": {
      "get": {
        "summary": "Current data gate, enabled sites, limits, and unsupported capabilities",
        "security": [],
        "responses": {
          "200": {
            "description": "Normalized eBay response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          },
          "504": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/usage": {
      "get": {
        "summary": "Current plan and quota; free account request",
        "responses": {
          "200": {
            "description": "Normalized eBay response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          },
          "504": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/requests": {
      "get": {
        "summary": "Request history, with search text redacted; 30-day retention",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized eBay response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          },
          "504": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/scrape/max": {
      "post": {
        "summary": "Start a bounded search job; one charged request per successful page",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "keyword"
                ],
                "properties": {
                  "keyword": {
                    "type": "string"
                  },
                  "ebaySite": {
                    "type": "string",
                    "default": "ebay.com"
                  },
                  "maxPages": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100,
                    "default": 50
                  },
                  "count": {
                    "type": "integer",
                    "maximum": 200,
                    "default": 200
                  },
                  "resultType": {
                    "type": "string",
                    "enum": [
                      "inline",
                      "download"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Normalized eBay response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "202": {
            "description": "Queued job with jobId and resultsUrl"
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          },
          "504": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/scrape/max/results/{jobId}": {
      "get": {
        "summary": "Read owned job status and partial results",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized eBay response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          },
          "504": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/scrape/max/{jobId}": {
      "delete": {
        "summary": "Cancel an owned job; an in-flight page may finish",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized eBay response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          },
          "504": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/scrape/max/{jobId}/download.csv": {
      "get": {
        "summary": "Download owned job as CSV using Bearer authentication",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "CSV",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/bulk-search": {
      "post": {
        "summary": "Stream 1–20 bounded keyword searches as SSE; each success costs one request",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "keywords"
                ],
                "properties": {
                  "keywords": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 20,
                    "items": {
                      "type": "string"
                    }
                  },
                  "count": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 200
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SSE progress, result, error and complete events"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "responses": {
      "Error": {
        "description": "Structured error. Workspace rate or concurrency limits return 429. Shared upstream capacity returns 503 with code upstream_rate_limited and Retry-After; failures consume zero units.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying a throttled request",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "error",
                "code",
                "requestId"
              ],
              "properties": {
                "error": {
                  "type": "string"
                },
                "code": {
                  "type": "string"
                },
                "requestId": {
                  "type": "string"
                },
                "retryAfter": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    }
  }
}