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.

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