SpecScout API v1 Back to Home

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: Authorization: Bearer <API_KEY>

Health Check Public

GET /api/v1/ready

Checks the operational status of the API.

Response (200 OK)

{
  "status": "ready"
}

Users

POST /api/v1/users/register

Registers a new user. Does not require authentication.

Request Body

  • email (string, required)
  • password (string, required, min 8 chars)
  • full_name (string, optional)

Response (201 Created)

{
  "id": "550e84...",
  "email": "user@example.com",
  "full_name": "John Doe",
  "is_active": true,
  "created_at": "..."
}
PUT /api/v1/users/{user_id}

Updates a user's information.

Authorization: Same user or superuser.

Request Body

{
  "email": "new@example.com",
  "password": "new_password",
  "full_name": "Jane Doe"
}
DELETE /api/v1/users/{user_id}

Deletes a user. Returns 204 No Content.

API Keys

POST /api/v1/users/{user_id}/keys

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

Response (201 Created)

{
  "token": "sp_user_a1b2c3... (SAVE THIS!)",
  "key": {
    "key_id": "sp_user_...",
    "created_at": "...",
    "revoked": false
  }
}
GET /api/v1/users/{user_id}/keys

Lists all keys for a user (without secrets).

Specifications

Best Practices: Garbage In -> Garbage Out

Each specification must be defined precisely. Use options where possible to ensure data comparability. Set tolerance > 0.1 for string matching.

POST /api/v1/specifications

Request Object

{
  "name": "CPU Type",
  "description": "The processor type of the device",
  "instance": "str",       // "float", "int", "str", "bool", "list"
  "unit": "",              // e.g. "kg", "GB"
  "tolerance": 0.15,       // 0-1 (decimal)
  "options": null,         // Array of allowed strings
  "sub_values": []
}

Note: Use options for filters (e.g. material: ["aluminum", "plastic"]).

GET /api/v1/specifications List all specs
GET /api/v1/specifications/{id} Get single spec

Categories

Categories group specifications in a hierarchical structure.

POST /api/v1/categories 
{
  "name": "Electronics/IT-Devices/Laptops",
  "top_category": "IT-Devices"  // UUID of parent or null
}

Every category name must be unique.

POST /api/v1/categories/{cat_id}/specs/{spec_id}

Associates a specification with a category.

Example Request & Response

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

POST /api/v1/search REQUEST 
{
  "product_name": "iPhone 12 Pro",
  "brand": "Apple",
  "category": "Electronics/IT-Devices/Smartphones",
  "user_id": "03dcb9a1-4d71-40a7-a04a-9a4b93d2b62e",
  "api-key": "sp_user_c64e2c071c4135d5.iKTBaTZFW-QNKUO7NPuhM..."
}
200 OK RESPONSE 
{
  "specs": [
    {
      "name": "weight",
      "description": "weight of device",
      "instance": "float",
      "unit": "gram",
      "tolerance": 0.02,
      "options": null,
      "sub_values": [],

      "value": 189,
      "sources": [
        "https://support.apple.com/en-us/111875",
        "https://en.wikipedia.org/wiki/IPhone_12_Pro",
        "https://www.gsmarena.com/apple_iphone_12_pro..."
      ]
    },

    {
      "name": "dimensions",
      "description": "physical dimensions of the device",
      "instance": "float",
      "unit": "mm",
      "tolerance": 0,
      "options": null,
      "sub_values": [
        "height",
        "width",
        "depth"
      ],

      "value": [
        7.4,
        71.5,
        146.7
      ],
      "sources": [
        "https://support.apple.com/en-us/111875",
        "https://en.wikipedia.org/wiki/IPhone_12_Pro",
        "https://www.gsmarena.com/apple_iphone_12_pro..."
      ]
    },

    {
      "name": "display_size",
      "description": "display diagonal",
      "instance": "float",
      "unit": "inch",
      "tolerance": 0.02,

      "value": 6.1,
      "sources": [
        "https://support.apple.com/en-us/111875",
        "https://en.wikipedia.org/wiki/IPhone_12_Pro",
        "https://www.apple.com/newsroom/2020/10..."
      ]
    },

    {
      "name": "rear_camera_megapixels",
      "description": "rear camera megapixels per lens",
      "instance": "float",
      "unit": "MP",
      "sub_values": [
        "wide",
        "ultrawide",
        "telephoto"
      ],

      "value": [
        12,
        12,
        12
      ],
      "sources": [
        "https://www.gsmarena.com/apple_iphone_12_pro...",
        "https://en.wikipedia.org/wiki/IPhone_12_Pro"
      ]
    },

    {
      "name": "color",
      "description": "available colors",
      "instance": "str",
      "unit": "str",

      "value": [
        "silver",
        "graphite",
        "gold",
        "pacific blue"
      ],
      "sources": [
        "https://support.apple.com/en-us/111875",
        "https://en.wikipedia.org/wiki/IPhone_12_Pro"
      ]
    },
    {
      "name": "battery_capacity",
      "description": "battery capacity",
      "instance": "int",
      "unit": "mAh",

      "value": 2815,
      "sources": [
        "https://www.gsmarena.com/apple_iphone_12_pro..."
      ]
    },
    {
      "name": "ram",
      "description": "RAM size",
      "instance": "int",
      "unit": "GB",

      "value": 6,
      "sources": [
        "https://www.gsmarena.com/apple_iphone_12_pro..."
      ]
    },

    {
      "name": "display_resolution",
      "description": "display resolution",
      "instance": "int",
      "sub_values": "pixels horizontally and vertically",

      "value": [
        1170,
        2532
        ]
    },

    {
      "name": "storage",
      "description": "storage capacity",
      "instance": "int",
      "unit": "GB",

      "value": [
        128,
        256,
        512
        ]
    }
  ],


  "status": "ok",

  "not_found": [],

  "errors": []

}

Ready to get structured data?

Get API Key