SpecScout API Documentation (v1)

Welcome to the SpecScout API. This documentation provides detailed information about endpoints, parameters, and responses to help you integrate automated product data extraction into your e-commerce platform.

Search

CORE SERVICE

Performs the core SpecScout service: searches the web for product specifications based on a query.

Jump to Request-Reply Example

GET /api/v1/search

Query Parameters

product_name Required string. E.g. "MacBook Pro 16 M3 Max".
brand Required string. E.g. "Apple".
required_specs Optional string (nullable). Use to pass additional specifications to look for.
category Optional string. Name of a predefined category (see category creation) to indicate which specifications to look for.

Success Response (200 OK)

{
  "status": "ok",
  "specs": [
    {
      "id": "3fa85f64-...",
      "name": "Processor",
      "instance": "str",
      "value": "Apple M3 Max",
      "unit": null
    }
  ],
  "not_found": [],
  "errors": []
}

Responses

200 Successful Response, schema: #/components/schemas/ServiceResponsePublic

{
  "specs": [{"id": "uuid", "name": "string", "value": "string", "unit": "string", "instance": "string"}],
  "status": "ok",
  "not_found": [{"name": "string", "description": "string", "instance": "string", "unit": "string"}],
  "errors": ["string"]
}

422 Validation Error, schema: #/components/schemas/HTTPValidationError

{
  "detail": [
    {"loc": ["query", "field_name"], "msg": "Field required", "type": "missing"}
  ]
}

Authentication

Authentication is handled via API keys. A client must provide a valid API key with each request to protected endpoints.

Header: x_api_key: <API_KEY>

Users

POST /api/v1/users/register

Register a new user.

Request Body

{
  "email": "user@example.com",      // required
  "password": "my_secure_password", // required (min 8 chars)
  "full_name": "John Doe"           // optional
}

Response (201 Created)

null

Responses

201 Successful Response (no JSON schema)
422 Validation Error, schema: #/components/schemas/HTTPValidationError

{
  "detail": [
    {"loc": ["query", "field_name"], "msg": "Field required", "type": "missing"}
  ]
}

GET /api/v1/users/me

Get your account information.

Responses

200 Successful Response, schema: #/components/schemas/UserPublic

{
  "id": "uuid",
  "email": "user.com",
  "full_name": "Jane Doe",
  "is_activated": false,
  "is_superuser": false,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Quotas

Check your quota limits and usage.

GET /api/v1/quotas/me

Get the current user's quota limits and usage.

Responses

200 Successful Response, schema: #/components/schemas/UserQuotaResponse

{
  "quota_key": "requests",
  "limit": 500,
  "used": 254,
  "remaining": 246,
  "period_start": "2026-04-01T00:00:00Z",
  "period_end": "2026-05-01T00:00:00Z",
  "period_type": "monthly",
  "period_tz": "UTC",
  "source": "plan",
  "is_exempt": false
}

Specifications

Best Practices: Garbage In -> Garbage Out

Open for concrete good/bad examples and validation rules.

The quality of extracted values depends directly on the quality of your specification definitions. Names and descriptions must be precise and unambiguous.

Good vs Bad Examples

Bad

name: "Size" (too vague)
description: "display size in inches" while unit: "inch" is already set
instance: "number" (not allowed)

Good

name: "Display Size"
description: "Diagonal length of the active display area"
instance: "float", unit: "inch"

Validation Rules

Allowed instance values only: "float", "int", "str", "bool", "list".
No duplicated semantics: if unit is set, avoid repeating it in the description.
Prefer specific names: e.g. Battery Capacity instead of Battery.
Use options for closed vocabularies: e.g. material, color class, connector type.
Set realistic tolerance: use low tolerance for exact numbers, higher only for fuzzy text matching.
Keep one meaning per spec: do not combine multiple attributes in one field.

POST /api/v2/specifications

Create a new specification for the current user.

Request Body

{
  "name": "Display Size",                     // required
  "description": "Diagonal of visible display area", // required
  "unit": "inch",                             // required
  "instance": "float",                        // required: "float", "int", "str", "bool", "list"

  "tolerance": 0.05,                          // optional fine-tuning
  "options": null,                            // optional fine-tuning (array of allowed values)
  "sub_values": []                            // optional fine-tuning (nested attributes)
}

Required for creation: name, description, unit, instance. All other fields are optional and used for fine-tuning.
Note: Use options for filters (e.g. material: ["aluminum", "plastic"]).

Responses

201 Successful Response, schema: #/components/schemas/Specification

{
  "id": "uuid",
  "name": "Display Size",
  "description": "Diagonal of visible display area",
  "instance": "float",
  "unit": "inch",
  "value": null,
  "tolerance": 0.05,
  "options": null,
  "sub_values": [],
  "potential_values": [],
  "sources": [],
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

422 Validation Error, schema: #/components/schemas/HTTPValidationError

{
  "detail": [
    {"loc": ["query", "field_name"], "msg": "Field required", "type": "missing"}
  ]
}

GET /api/v2/specifications List all specs

List all specifications visible to the current user.

Parameters

search Optional string. Default: "".

scope Optional string. Default: all. Allowed: all, owned, public.

user_id Optional UUID (nullable). Filter by owner.

skip Optional integer. Default: 0.

limit Optional integer. Default: 100, max: 1000.

Responses

200 Successful Response, schema: #/components/schemas/SpecificationListResponse

{
  "items": [
    {"id": "uuid", "name": "Display Size", "description": "...", "instance": "float", "unit": "inch"}
  ],
  "pagination": {
    "total": 128,
    "skip": 0,
    "limit": 100,
    "returned": 1,
    "has_prev": false,
    "has_next": true,
    "next_skip": 100,
    "prev_skip": null
  }
}

422 Validation Error, schema: #/components/schemas/HTTPValidationError

{
  "detail": [
    {"loc": ["query", "field_name"], "msg": "Field required", "type": "missing"}
  ]
}

GET /api/v2/specifications/{spec_id} Get single spec

Get a single specification by ID.

Responses

200 Successful Response, schema: #/components/schemas/Specification

{
  "id": "uuid",
  "name": "Display Size",
  "description": "Diagonal of visible display area",
  "instance": "float",
  "unit": "inch",
  "value": "6.1",
  "tolerance": 0.05,
  "options": null,
  "sub_values": [],
  "potential_values": [],
  "sources": []
}

422 Validation Error, schema: #/components/schemas/HTTPValidationError

{
  "detail": [
    {"loc": ["query", "field_name"], "msg": "Field required", "type": "missing"}
  ]
}

PUT /api/v2/specifications/{spec_id}

Update a specification.

Request Body

{
  "name": "Display Size",                     // required
  "description": "Diagonal of visible display area", // required
  "unit": "inch",                             // required
  "instance": "float",                        // required: "float", "int", "str", "bool", "list"
  "tolerance": 0.05,                          // optional fine-tuning
  "options": null,                            // optional fine-tuning
  "sub_values": []                            // optional fine-tuning
}

For updates, provide a full specification payload. name, description, unit, and instance are required.

Responses

200 Successful Response, schema: #/components/schemas/Specification

{
  "id": "uuid",
  "name": "Display Size",
  "description": "Diagonal of visible display area",
  "instance": "float",
  "unit": "inch",
  "value": "6.1",
  "tolerance": 0.05,
  "options": null,
  "sub_values": [],
  "potential_values": [],
  "sources": []
}

422 Validation Error, schema: #/components/schemas/HTTPValidationError

{
  "detail": [
    {"loc": ["query", "field_name"], "msg": "Field required", "type": "missing"}
  ]
}

DELETE /api/v2/specifications/{spec_id} Delete spec

Responses

204 Successful Response (no content)
422 Validation Error, schema: #/components/schemas/HTTPValidationError

{
  "detail": [
    {"loc": ["query", "field_name"], "msg": "Field required", "type": "missing"}
  ]
}

Categories

Categories group specifications in a hierarchical structure.

GET /api/v2/categories List categories

List categories visible to the current user.

Parameters

search Optional string. Default: "".

scope Optional string. Default: all. Allowed: all, owned, public.

user_id Optional UUID (nullable). Filter by owner.

skip Optional integer. Default: 0.

limit Optional integer. Default: 100, max: 1000.

Responses

200 Successful Response, schema: #/components/schemas/CategoryListResponse

{
  "items": [
    {
      "id": "uuid",
      "name": "Electronics/IT-Devices/Laptops",
      "user_id": "uuid",
      "top_category": null,
      "path": ["Electronics", "IT-Devices", "Laptops"],
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "total": 42,
    "skip": 0,
    "limit": 100,
    "returned": 1,
    "has_prev": false,
    "has_next": false,
    "next_skip": null,
    "prev_skip": null
  }
}

422 Validation Error, schema: #/components/schemas/HTTPValidationError

{
  "detail": [
    {"loc": ["query", "field_name"], "msg": "Field required", "type": "missing"}
  ]
}

GET /api/v2/categories/{category_id} Get category

Get a single category by ID.

Responses

200 Successful Response, schema: #/components/schemas/CategoryPublic

{
  "id": "uuid",
  "name": "Electronics/IT-Devices/Laptops",
  "user_id": "uuid",
  "top_category": null,
  "path": ["Electronics", "IT-Devices", "Laptops"],
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

422 Validation Error, schema: #/components/schemas/HTTPValidationError

{
  "detail": [
    {"loc": ["query", "field_name"], "msg": "Field required", "type": "missing"}
  ]
}

GET /api/v2/categories/{category_id}/specifications List category specifications

Get all specifications that are attached to the given category.

Parameters

category_id Path parameter, required UUID.

skip Query parameter, optional integer. Default: 0.

limit Query parameter, optional integer. Default: 100, max: 1000.

Responses

200 Successful Response, schema: #/components/schemas/SpecificationListResponse

{
  "items": [
    {
      "id": "uuid",
      "name": "Screen Size",
      "description": "Display diagonal size",
      "instance": "float",
      "unit": "inch",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "total": 12,
    "skip": 0,
    "limit": 100,
    "returned": 1,
    "has_prev": false,
    "has_next": false,
    "next_skip": null,
    "prev_skip": null
  }
}

422 Validation Error, schema: #/components/schemas/HTTPValidationError

{
  "detail": [
    {"loc": ["query", "field_name"], "msg": "Field required", "type": "missing"}
  ]
}

POST /api/v2/categories

Create a category. Every category name must be unique.

Request Body

{
  "name": "Electronics/IT-Devices/Laptops",
  "top_category": "f2a9c3f4-9113-4bc4-ac18-6d07fb3d8ba7"  // UUID of parent or don't include top_category
}

Responses

201 Successful Response, schema: #/components/schemas/CategoryPublic
422 Validation Error, schema: #/components/schemas/HTTPValidationError

{
  "detail": [
    {"loc": ["query", "field_name"], "msg": "Field required", "type": "missing"}
  ]
}

PUT /api/v2/categories/{category_id}

Update a category.

Request Body

{
  "name": "New Category Name",
  "top_category": "f2a9c3f4-9113-4bc4-ac18-6d07fb3d8ba7" // UUID of parent or don't include top_category
}

Responses

200 Successful Response, schema: #/components/schemas/CategoryPublic

{
  "id": "uuid",
  "name": "Electronics/IT-Devices/Laptops",
  "user_id": "uuid",
  "top_category": null,
  "path": ["Electronics", "IT-Devices", "Laptops"],
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

422 Validation Error, schema: #/components/schemas/HTTPValidationError

{
  "detail": [
    {"loc": ["query", "field_name"], "msg": "Field required", "type": "missing"}
  ]
}

DELETE /api/v2/categories/{category_id} Delete category

Responses

204 Successful Response (no content)
422 Validation Error, schema: #/components/schemas/HTTPValidationError

{
  "detail": [
    {"loc": ["query", "field_name"], "msg": "Field required", "type": "missing"}
  ]
}

POST /api/v2/categories/{category_id}/specs/{spec_id}

Associates a specification with a category.

Responses

201 Successful Response (no JSON schema)
422 Validation Error, schema: #/components/schemas/HTTPValidationError

{
  "detail": [
    {"loc": ["query", "field_name"], "msg": "Field required", "type": "missing"}
  ]
}

DELETE /api/v2/categories/{category_id}/specs/{spec_id}

Removes a specification from a category.

Responses

204 Successful Response (no content)
422 Validation Error, schema: #/components/schemas/HTTPValidationError

{
  "detail": [
    {"loc": ["query", "field_name"], "msg": "Field required", "type": "missing"}
  ]
}

Example Request & Response

This example demonstrates a standard request to the /api/v1/search endpoint and the corresponding structured JSON response.

GET /api/v1/search REQUEST

GET /api/v1/search?product_name=iPhone%2012%20Pro&brand=Apple&category=3fa85f64-5717-4562-b3fc-2c963f66afa6

Headers:
x_api_key: sp_user_c64e2c071c4135d5.iKTBaTZFW...

200 OK RESPONSE

{
  "specs": [
    {
      "id": "3fa85f64-...",
      "name": "weight",
      "instance": "float",
      "value": "189",
      "unit": "gram",
    },

    {
      "id": "4fa85f64-...",
      "name": "dimensions",
      "instance": "list",
      "value": "7.4 x 71.5 x 146.7",
      "unit": "mm",
    },

    {
      "id": "5fa85f64-...",
      "name": "display_size",
      "instance": "float",
      "value": "6.1",
      "unit": "inch",
    },

    {
      "id": "6fa85f64-...",
      "name": "color",
      "instance": "str",
      "value": "['silver', 'graphite', 'gold', 'pacific blue']",
      "unit": null,
    },
    {
      "id": "7fa85f64-...",
      "name": "battery_capacity",
      "instance": "int",
      "value": "2815",
      "unit": "mAh",
    },
    {
      "id": "8fa85f64-...",
      "name": "ram",
      "instance": "int",
      "value": "6",
      "unit": "GB",
    },
    {
      "id": "9fa85f64-...",
      "name": "storage",
      "instance": "list",
      "value": "128, 256, 512",
      "unit": "GB",
    }
  ],


  "status": "ok",

  "not_found": [],

  "errors": []

}

Ready to get structured data?

Get API Key