As of 15.07.2026

SpecScout API Documentation

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.

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>

POST /api/v1/auth/validate_api_key Validate API key

Validate the API key sent in the x_api_key header and return its metadata. No request body — useful to test your integration.

Responses
  • 200 Successful Response, schema: #/components/schemas/ValidateAPIKeySuccessResponse
    • {
  "valid": true,
  "key_id": "uuid",
  "key_type": "user",
  "expires_at": null,
  "capabilities": {
    "search": true,
    "categories_read": true,
    "categories_write": true
  }
}

Users

GET /api/v1/users/me Get own account

Get your account information.

Responses
  • 200 Successful Response, schema: #/components/schemas/UserPublic
    • {
  "id": "uuid",
  "email": "jane.doe@example.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 own quota

Get the current user's quota limits and usage.

Responses
  • 200 Successful Response, schema: #/components/schemas/UserQuotaResponse
    • {
  "quota_key": "search",
  "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
}
GET /api/v1/quotas/monthly Get monthly usage history

Get your monthly search usage history, paginated.

Parameters

skip Optional integer. Default: 0.

limit Optional integer. Default: 12, max: 120.

sortDir Optional string. Default: desc. Allowed: asc, desc.

Responses
  • 200 Successful Response, schema: #/components/schemas/MonthlySearchUsageListResponse
    • {
  "items": [
    {
      "period_start": "2026-06-01T00:00:00Z",
      "period_end": "2026-07-01T00:00:00Z",
      "regular_count": 254,
      "demo_count": 0,
      "total_count": 254,
      "last_search_at": "2026-06-28T14:31:07Z"
    }
  ],
  "pagination": {"total": 6, "skip": 0, "limit": 12, "returned": 6, ...}
}
  • 422 Validation Error, schema: #/components/schemas/HTTPValidationError

Specifications

Best Practices

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: "list" (not allowed — use sub_values for multi-value specs)

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". Common aliases ("number", "double", "integer", "string", "text", "boolean") are accepted and normalized. There is no "list" instance — define sub_values when a spec has multiple values.
  • 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 spec

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"

  "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/SpecificationPublic
    • {
  "id": "uuid",
  "name": "Display Size",
  "description": "Diagonal of visible display area",
  "instance": "float",
  "unit": "inch",
  "tolerance": 0.05,
  "options": null,
  "sub_values": null,
  "user_id": "uuid",
  "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.

sortBy Optional string. Default: created_at. Allowed: created_at, name, unit, instance.

sortDir Optional string. Default: desc. Allowed: asc, desc.

exclude_category_id Optional UUID (nullable). Exclude specifications that are attached to this category.

instance Optional, repeatable. Only specifications with one of the given instance types, e.g. instance=float&instance=int. Invalid values are rejected with 422.

unit Optional string (nullable). Only specifications with exactly this unit.

has_options Optional boolean (nullable). true: only specifications with options; false: only ones without.

has_sub_values Optional boolean (nullable). true: only specifications with sub_values; false: only ones without.

no_category Optional boolean (nullable). true: only specifications not attached to any category; false: only attached ones.

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/SpecificationPublic
    • {
  "id": "uuid",
  "name": "Display Size",
  "description": "Diagonal of visible display area",
  "instance": "float",
  "unit": "inch",
  "tolerance": 0.05,
  "options": null,
  "sub_values": null,
  "user_id": "uuid",
  "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"}
  ]
}
PUT /api/v2/specifications/{spec_id} Update spec

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"
  "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.

Query Parameters

scope Optional string. Default: all_categories. Allowed: all_categories, this_category. With all_categories the specification is updated in place, affecting every category it is attached to. With this_category the change applies only to the category given in category_id: if the specification is attached to other categories as well, it is detached from that category and an edited copy is created and attached in its place — the original remains unchanged everywhere else.

category_id Optional UUID. Required when scope=this_category (otherwise 422).

Responses
  • 200 Successful Response, schema: #/components/schemas/SpecificationPublic
    • {
  "id": "uuid",
  "name": "Display Size",
  "description": "Diagonal of visible display area",
  "instance": "float",
  "unit": "inch",
  "tolerance": 0.05,
  "options": null,
  "sub_values": null,
  "user_id": "uuid",
  "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/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"}
  ]
}
POST /api/v2/specifications/bulk Bulk create specs

Create up to 100 specifications in one request. Use mode to control atomicity.

Request Body

{
  "mode": "partial",    // "partial" (default) or "atomic" — partial commits valid rows independently
  "items": [
    {
      "client_id": "my-ref-1",   // optional, echoed back in results
      "specification": {
        "name": "Display Size",
        "description": "Diagonal of visible display area",
        "instance": "float",
        "unit": "inch"
      }
    }
  ]
}
Responses
  • 201 Successful Response
    • {
  "mode": "partial",
  "summary": {"requested": 1, "created": 1, "attached": 0, "failed": 0},
  "results": [
    {
      "index": 0,
      "client_id": "my-ref-1",
      "status": "created",
      "specification": {"id": "uuid", "name": "Display Size", ...},
      "attached": null,
      "error": null
    }
  ]
}
  • 422 Validation Error
POST /api/v2/specifications/draft AI-draft a spec

Use AI to draft a specification from a natural-language prompt. Also returns similar existing specs to prevent duplicates before creating.

Request Body

{
  "prompt": "battery capacity in milliampere-hours",   // required, max length 200 characters
  "category_id": "uuid",                               // optional — for context
  "language": "en",                                    // optional, default "en"
  "existing_spec_ids": ["uuid", ...]                   // optional — for context
}
Responses
  • 200 Successful Response
    • {
  "draft": {
    "name": "Battery Capacity",
    "description": "Rated capacity of the battery cell",
    "instance": "int",
    "unit": "mAh",
    "tolerance": null,
    "options": null,
    "sub_values": null
  },
  "duplicate_candidates": [
    {"id": "uuid", "name": "Battery Capacity", "description": "...", "instance": "int", "unit": "mAh"}
  ],
  "warnings": []
}
  • 400 Invalid prompt
  • 403 Forbidden category access
  • 404 Category not found
  • 502 AI draft generation failed
  • 422 Validation Error
GET /api/v2/specifications/{spec_id}/categories List spec's categories

List all categories the specification is attached to.

Responses
  • 200 Successful Response — array of 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

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.

sortBy Optional string. Default: created_at. Allowed: created_at, updated_at, name.

sortDir Optional string. Default: desc. Allowed: asc, desc.

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.

sortBy Optional string. Default: created_at. Allowed: created_at, name, unit, instance.

sortDir Optional string. Default: desc. Allowed: asc, desc.

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 category

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 category

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} Attach spec

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} Detach spec

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"}
  ]
}
POST /api/v2/categories/{category_id}/duplicate Duplicate category

Creates a copy of the category and all its attached specifications. No request body required.

Responses
  • 201 Successful Response — returns CategoryPublic of the new category
  • 422 Validation Error
POST /api/v2/categories/{category_id}/specifications/bulk Bulk create & attach specs

Bulk-creates specifications and attaches them to the category in one request. Same request schema as POST /api/v2/specifications/bulk. The attached field in each result indicates whether the attachment succeeded.

Responses
  • 201 Successful Response — same BulkSpecificationResponse schema; attached: true/false per result row
  • 422 Validation Error

Search Settings

Manage the domain blacklist — domains excluded from web searches during extraction. The blacklist_mode parameter on Search controls whether the stored list is applied.

GET /api/v1/users/search-settings/blacklist List blacklisted domains

List blacklisted domains for the current user.

Parameters

search Optional string.

is_active Optional boolean. Filter by active state.

skip Optional integer. Default: 0.

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

sortBy Optional string. Default: created_at. Allowed: created_at, updated_at, domain, is_active.

sortDir Optional string. Default: desc. Allowed: asc, desc.

Responses
  • 200 Successful Response
    • {
  "items": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "domain": "example.com",
      "is_active": true,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "pagination": {"total": 5, "skip": 0, "limit": 100, "returned": 1, ...}
}
  • 422 Validation Error
POST /api/v1/users/search-settings/blacklist Add domain

Add a domain to the blacklist.

Request Body

{"domain": "example.com"}  // required, max 2048 chars
Responses
  • 201 Successful Response — returns DomainBlacklistItemPublic
  • 422 Validation Error
PATCH /api/v1/users/search-settings/blacklist/{item_id} Enable / disable item

Enable or disable a blacklist entry without deleting it.

Request Body

{"is_active": false}  // required boolean
Responses
  • 200 Successful Response — returns updated DomainBlacklistItemPublic
  • 422 Validation Error
DELETE /api/v1/users/search-settings/blacklist/{item_id} Remove domain
Responses
  • 204 Successful Response (no content)
  • 422 Validation Error

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",
      "value": [
        {
          "value": 189.0,
          "unit": "gram",
          "sources": ["https://www.apple.com/iphone-12-pro/specs/", "https://www.gsmarena.com/apple_iphone_12_pro-10508.php"],
          "confidence": 1.0
        }
      ],
      "unit": "gram",
      "instance": "float"
    },

    {
      "id": "4fa85f64-...",
      "name": "dimensions",
      "value": [
        {
          "value": [7.4, 71.5, 146.7],
          "unit": "mm",
          "sources": ["https://www.gsmarena.com/apple_iphone_12_pro-10508.php"],
          "confidence": 0.95
        }
      ],
      "unit": "mm",
      "instance": "float"
    },

    {
      "id": "5fa85f64-...",
      "name": "display_size",
      "value": [
        {
          "value": 6.1,
          "unit": "inch",
          "sources": ["https://www.apple.com/iphone-12-pro/specs/"],
          "confidence": 1.0
        }
      ],
      "unit": "inch",
      "instance": "float"
    },

    {
      "id": "6fa85f64-...",
      "name": "color",
      "value": [
        {
          "value": ["silver", "graphite", "gold", "pacific blue"],
          "unit": null,
          "sources": ["https://www.apple.com/iphone-12-pro/specs/"],
          "confidence": 0.9
        }
      ],
      "unit": "",
      "instance": "str"
    },

    {
      "id": "7fa85f64-...",
      "name": "battery_capacity",
      "value": [
        {
          "value": 2815,
          "unit": "mAh",
          "sources": ["https://www.gsmarena.com/apple_iphone_12_pro-10508.php"],
          "confidence": 0.9
        }
      ],
      "unit": "mAh",
      "instance": "int"
    },

    {
      "id": "8fa85f64-...",
      "name": "ram",
      "value": [
        {
          "value": 6,
          "unit": "GB",
          "sources": ["https://www.gsmarena.com/apple_iphone_12_pro-10508.php"],
          "confidence": 0.9
        }
      ],
      "unit": "GB",
      "instance": "int"
    },

    {
      "id": "9fa85f64-...",
      "name": "storage",
      "value": [
        {
          "value": [128, 256, 512],
          "unit": "GB",
          "sources": ["https://www.apple.com/iphone-12-pro/specs/"],
          "confidence": 0.95
        }
      ],
      "unit": "GB",
      "instance": "int"
    }
  ],

  "status": "success",

  "not_found": [],

  "errors": [],

  "image_links": null

}

Ready to get structured data?

Get API Key