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. E.g. "MacBook Pro 16 M3 Max"
brand Optional but use highly recommended. E.g. "Apple".
category Name of a predefined category (see category creation) to indicate which specifications to look for.
required_specs Optional. JSON array of spec objects. Use to add additional 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

Registers a new user. Does not require authentication.

Request Body

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

Response (201 Created)

{
  "id": "550e84...",
  "email": "user@example.com",
  "full_name": "John Doe",
  "is_active": true,
  "created_at": "..."
}

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

PUT /api/v1/users/me

Update your profile.

Request Body

{
  "full_name": "Jane Doe",
  "email": "new@example.com"
}

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

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

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

PUT /api/v1/users/me/password

Update your password.

Request Body

{
  "current_password": "old_password",
  "new_password": "new_secure_password"
}

Responses

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

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

DELETE /api/v1/users/me

Delete your account. Returns 204 No Content.

Responses

204 Successful Response (no content)

API Keys

POST /api/v1/users/keys

Creates a new API key. Important: The raw token is returned only once.

Query Parameters: user_id (required), valid_until, scope.

Response (201 Created)

{
  "token": "sp_user_a1b2c3... (SAVE THIS!)",
  "key": {
    "key_id": "sp_user_...",
    "created_at": "...",
    "revoked": false
  }
}

Responses

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

{
  "token": "sp_user_...",
  "key": {
    "key_id": "sp_user_...",
    "scope": "default",
    "revoked": false,
    "valid_until": null,
    "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/v1/users/keys

Lists all keys for a user (without secrets).

Responses

200 Successful Response, schema: array of #/components/schemas/APIKeyPublic

[
  {
    "key_id": "sp_user_...",
    "scope": "default",
    "revoked": false,
    "valid_until": null,
    "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/v1/users/keys/{key_id}

Revoke an API key.

Responses

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

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

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/v1/specifications

Specification Object

{
  "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/v1/specifications List all specs

Responses

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

[
  {"id": "uuid", "name": "Display Size", "description": "...", "instance": "float", "unit": "inch"}
]

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

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

GET /api/v1/specifications/{id} Get single spec

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/v1/specifications/{id}

Update a specification.

Request Body

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

For updates, all fields are optional. Send only the fields you want to change. For creation, 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/v1/specifications/{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/v1/categories List categories

Responses

200 Successful Response, schema: array of #/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/v1/categories/{id} Get 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"}
  ]
}

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

Get all specifications that are attached to the given category.

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: array of #/components/schemas/Specification

[
  {
    "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"
  }
]

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

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

POST /api/v1/categories

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

Every category name must be unique.

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/v1/categories/{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/v1/categories/{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/v1/categories/{cat_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/v1/categories/{cat_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=Electronics/IT-Devices/Smartphones

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