As of 23.10.2026 · Changelog

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.

Quickstart

Your first search in five minutes. All you need is a free account, and there are two ways to start.

Without code: the web app

Sign up with Start free and search in your browser at specscout.anora-systems.com. You see every value with its sources and confidence score, which is the quickest way to try SpecScout before you connect your own system.

With the API: an API key

Create an API key and send searches from your own system. The steps below take you from the key to your first result.

  1. 1. Get an API key

    Create a free account in the dashboard and confirm your email address; the free plan has 20 searches a month. Then create a key under API keys. If you already have an account, for example from the web app, log in with it instead. The key is shown only once, so store it right away, for example as SPECSCOUT_KEY in your environment.

  2. 2. Check the key

    curl -X POST https://api.anora-systems.com/api/v1/auth/validate_api_key \
      -H "x_api_key: $SPECSCOUT_KEY"
    
    # {"valid": true, "key_type": "default", "access_level": "free", ...}
  3. 3. Run a search

    Name the product and its brand, and say which specifications you want: inline as required_specs, or later as a saved category. A search takes about 10 to 40 seconds, so allow a long timeout.

    curl -G https://api.anora-systems.com/api/v1/search \
      -H "x_api_key: $SPECSCOUT_KEY" --max-time 180 \
      --data-urlencode "product_name=Galaxy S25 Ultra" \
      --data-urlencode "brand=Samsung" \
      --data-urlencode 'required_specs=[
        {"name": "Display size", "description": "Diagonal of the main display", "instance": "float", "unit": "inch"},
        {"name": "RAM", "description": "Working memory", "instance": "float", "unit": "GB"}
      ]'

    The same in Python:

    import json, os, requests
    
    specs = [
        {"name": "Display size", "description": "Diagonal of the main display", "instance": "float", "unit": "inch"},
        {"name": "RAM", "description": "Working memory", "instance": "float", "unit": "GB"},
    ]
    response = requests.get(
        "https://api.anora-systems.com/api/v1/search",
        headers={"x_api_key": os.environ["SPECSCOUT_KEY"]},
        params={"product_name": "Galaxy S25 Ultra", "brand": "Samsung", "required_specs": json.dumps(specs)},
        timeout=180,
    )
    response.raise_for_status()
    for spec in response.json()["specs"]:
        for value in spec["value"]:
            print(spec["name"], value["value"], value["unit"], value["confidence"], value["sources"])
  4. 4. Read the result

    Each entry in specs holds one or more values, each with its unit, the pages it came from (sources) and a confidence score. Specifications that could not be confirmed by at least two independent sources, or by one authoritative source such as the manufacturer, are listed in not_found, never guessed.

  5. 5. Next steps

    • Save your specifications once as a category and search with category=<id> instead of sending them every time.
    • Use units, options and tolerances so the values fit your shop's filters.
    • Block or trust sources with domain rules, for example from a button in your own system (ensure).

Confidence scores

Every value comes with a confidence between 0 and 0.99. It sums up how many independent pages state the value and how reliable those sites are. It is not a measured probability that the value is correct; use it to decide which values to accept and which to check.

  • Only confirmed values are returned. A value needs at least two independent pages; yes/no values need a clear majority of the sources. The one exception is an authoritative page: the manufacturer's own site, which SpecScout recognises when the brand is part of the domain name (bosch.com, shop.bosch.de), or a site you marked authoritative in your domain rules. It is read by two different AI models, which counts as two sources. Everything else ends up in not_found.
  • More and better sources raise it. Each page adds to the score according to how reliable its site is: manufacturer pages and specification databases count more than retailers, marketplaces or forums. Sites you mark trusted or authoritative count more.
  • Each value has its own score. When a spec has several values (256 GB and 512 GB), each is scored on its own sources; the other values do not lower it.
ConfidenceTypically means
around 0.5two pages from sites with little track record
around 0.75two good sources, for example a specification database and a review
0.85 to 0.9three or four good sources
0.95 and abovefour or more strong sources

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.

Rate limit: 100 requests per minute.

Responses
  • 200 Successful Response, schema: #/components/schemas/ValidateAPIKeySuccessResponse
  • {
      "valid": true,
      "key_id": "uuid",
      "key_type": "default",            // customer keys are always "default"
      "access_level": "free",           // "trial" | "free" | "full"
      "expires_at": null,
      "capabilities": {
        "search": true,
        "categories_read": true,
        "categories_write": true
      }
    }
  • 401 invalid_or_missing_api_key, invalid_api_key (also expired or revoked), email_not_verified, account_blocked, trial_key_ended

Making Requests

Every request that carries a body must send a JSON Content-Type. The API rejects a JSON body sent under any other media type — including a missing header — with 422 Unprocessable Entity, before the endpoint runs.

Header: Content-Type: application/json

A charset parameter is accepted, so application/json; charset=utf-8 is fine. Requests without a body — most DELETEs, and POSTs that take their input from the path or query string — do not need the header.

Common mistake

Browser fetch() sends text/plain;charset=UTF-8 when given a JSON string body without an explicit header, which this API refuses. Set the header explicitly.

Accepted

POST /api/v2/specifications
Content-Type: application/json

{"name": "Weight", "description": "...", "instance": "float"}

Rejected — 422

POST /api/v2/specifications
Content-Type: text/plain

{"name": "Weight", "description": "...", "instance": "float"}

Errors & Status Codes

Errors raised by the API's own validation and business rules return a human-readable detail plus a stable, machine-readable code. Branch on code, not on the text. Request-schema violations caught before the endpoint runs (missing required field, wrong type, unknown enum value) use FastAPI's standard {"detail": [...]} list shape without a code.

Business / validation error

{
  "detail": "a specification named 'Weight' is already attached to category ...",
  "code": "specification_name_conflict_in_category",
  "correlation_id": "3f9c..."
}

Internal error (500)

{
  "detail": "internal server error",
  "code": "internal_server_error",
  "correlation_id": "3f9c..."
}

Every error with a code also carries a correlation_id, in the body and in the X-Correlation-ID header. Quote it when you report a problem to us. The OpenAPI schema lists the possible codes for every route.

StatusMeaningTypical codes
400The request cannot be carried out as askedno_specifications_to_search, invalid_prompt, category_hierarchy_cycle
401Missing, invalid, expired or revoked API key; email not confirmed; account blocked; trial endednot_authenticated, invalid_or_missing_api_key, invalid_api_key (validate_api_key), email_not_verified, account_blocked, trial_key_ended
403Key valid but not allowed: access level or key scope too low, someone else's private resourceaccess_level_insufficient, api_key_scope_insufficient, forbidden_category, forbidden_specification, forbidden_parent_category, public_category_accepts_only_own_specifications, superuser_access_required, domain_blacklist_item_forbidden, domain_whitelist_item_forbidden
404Resource does not exist or is not visible to youcategory_not_found, specification_not_found, specification_not_attached_to_category, parent_category_not_found, domain_blacklist_item_not_found, scope_term_not_found, ...
409Conflict with existing data or a capspecification_name_conflict_in_category, domain_whitelist_item_duplicate, scope_term_duplicate, scope_term_limit_exceeded, scope_term_last_undeletable
422Request understood but invalid, including malformed JSON in a query parameter and a category that is not a UUIDvalidation_error, invalid_scope_term, invalid_brand, or FastAPI's {"detail": [...]}
429Rate limit, monthly search quota, or too many searches running on the server (wait for Retry-After)rate_limit_exceeded, search_quota_exceeded, search_concurrency_limit_reached
500Unexpected failure; nothing about the cause is exposedinternal_server_error, search_processing_failed
502The AI model behind the specification assistant faileddraft_generation_failed, draft_normalization_failed, review_generation_failed, review_normalization_failed
503Temporarily unavailable; retry laterbrowser_unavailable

Users

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

Get your account information.

Rate limit: 20 requests per minute.

Responses
  • 200 Successful Response, schema: #/components/schemas/UserPublic
  • {
      "id": "uuid",
      "email": "jane.doe@example.com",
      "access_level": "free",           // "trial" | "free" | "full"
      "is_superuser": false,
      "full_name": "Jane Doe",
      "pending_email": null,            // the new address while an email change waits for confirmation
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  • 403 api_key_scope_insufficient (trial keys)

Quotas

Check your quota limits and usage.

GET /api/v1/quotas/me Get own quota

Get the current user's quota limits and usage. Allowances renew on the first day of each month (UTC); only completed searches count.

Rate limit: 20 requests per minute.

Responses
  • 200 Successful Response, schema: #/components/schemas/UserQuotaResponse
  • {
      "quota_key": "search",            // "search" (Enterprise), "search_free" (Free), "search_trial" (trial)
      "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",                 // "plan" | "override" | "exempt"
      "is_exempt": false,
      "free_limit": null                // trial accounts: the allowance after confirming the email
    }
GET /api/v1/quotas/monthly Get monthly usage history

Get your monthly search usage history, paginated.

Rate limit: 20 requests per minute.

Parameters

skip Optional integer, 0 or more. Default: 0.

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

sortBy Optional string. Default: period_start. Allowed: period_start, search_count, last_search_at.

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,         // searches on the Enterprise allowance
          "free_count": 0,
          "trial_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.
  • Use int only for counts (cores, gears). Physical quantities (weight, size, clock speed) are float, even if they are usually listed as whole numbers.
  • unit is optional. Leave it out for values without a unit; it reads back as null. Unit conversion only happens for int/float; on a str spec a unit acts as a format hint, on bool it does nothing.
  • No duplicated semantics: if unit is set, do not repeat it in the description. Avoid plausible example values in the description; they bias the extraction.
  • Multi-part values use sub_values: either an array of at least two per-element descriptions (e.g. ["width", "height", "depth"]; subvalue_elements is derived from the length), or a string describing the whole collection when the elements cannot be enumerated (e.g. "the materials of the fabric with their share"; subvalue_elements stays null for a variable count or states a fixed count ≥ 2). subvalues_ordered says whether each position has a fixed meaning; it defaults to true for the array form and false for the string form, and true with a string is rejected. All elements share one instance, unit, tolerance and options. Sub-values are verified as a unit: sources must agree on every element.
  • Tolerance defaults by instance: float 0.02, int 0, str 0.15 (recommended to keep near that), bool ignored. Value is a fraction (0.05 = 5%).
  • Use options for closed vocabularies: e.g. material, connector type. Keep them on one abstraction level, exhaustive for the domain, in one language.
  • Prefer specific names and keep one meaning per spec: e.g. Battery Capacity instead of Battery; do not combine multiple attributes in one field. Two specs that overlap should each exclude the other's domain in their description.
  • Names are unique per category (case-insensitive). Attaching or renaming a spec so that two specs in one category share a name is rejected with 409 specification_name_conflict_in_category.
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
  "instance": "float",                        // required: "float", "int", "str", "bool"
  "unit": "inch",                             // optional; omit for values without a unit

  "tolerance": 0.05,                          // optional; default depends on instance (float 0.02, int 0, str 0.15)
  "options": null,                            // optional: array of allowed values (closed vocabulary)
  "sub_values": null,                         // optional: array of >= 2 element descriptions, or a string describing the collection
  "subvalue_elements": null,                  // optional: expected element count (derived from an array sub_values)
  "subvalues_ordered": true                   // optional: whether positions have a fixed meaning (default: true for array, false for string)
}

Required for creation: name, description, instance. All other fields are optional and used for fine-tuning; see the best practices above for the sub_values contract.
Note: Use options for filters (e.g. material: ["aluminum", "plastic"]).

Rate limit: 50 requests per minute.

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,
      "subvalue_elements": null,
      "subvalues_ordered": true,
      "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.

Rate limit: 100 requests per minute.

Parameters

search Optional string. Default: "".

scope Optional string. Default: all. Allowed: all (own + public), owned, public, mine.

skip Optional integer, 0 or more. Default: 0.

limit Optional integer, 0 to 1000. Default: 100. limit=0 returns no rows, only the pagination block with the total.

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.

subvalues_ordered Optional boolean (nullable). Among sub-value specs only: filter by whether element order carries meaning. Plain specs never match either value.

has_subvalue_elements Optional boolean (nullable). Among sub-value specs only: true = element count is declared, false = count varies per product.

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.

Rate limit: 50 requests per minute. 403 forbidden_specification for someone else's private specification, 404 specification_not_found if it does not exist.

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,
      "subvalue_elements": null,
      "subvalues_ordered": true,
      "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
  "instance": "float",                        // required: "float", "int", "str", "bool"
  "unit": "inch",                             // optional
  "tolerance": 0.05,                          // optional
  "options": null,                            // optional
  "sub_values": null,                         // optional (array or string, see best practices)
  "subvalue_elements": null,                  // optional
  "subvalues_ordered": true                   // optional
}

For updates, provide a full specification payload. name, description and instance are required; omitted optional fields are reset to their defaults.

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

Rate limit: 50 requests per minute. You can only change your own specifications (403 forbidden_specification, also for public ones); 404 specification_not_found; with scope=this_category also 404 category_not_found or specification_not_attached_to_category.

Conflicts: renaming a spec to a name another spec in one of its categories already carries is 409 specification_name_conflict_in_category. With scope=this_category, forking inside a public category is refused with 409 specification_fork_into_public_category (duplicate the category first).

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,
      "subvalue_elements": null,
      "subvalues_ordered": true,
      "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)
  • 403 forbidden_specification (not your own); 404 specification_not_found
  • 422 Validation Error, schema: #/components/schemas/HTTPValidationError

Rate limit: 100 requests per minute.

POST /api/v2/specifications/draft AI-draft a spec

Let the AI assistant draft a specification from a short description, or rewrite an existing one. The draft is reviewed against our definition rules before it is returned, and similar existing specifications are listed so you do not create duplicates. Nothing is saved; create the specification yourself once you are happy with it.

Enterprise only (access level full); other accounts get 403 access_level_insufficient. Rate limit: 20 requests per minute. A call takes about 5 to 15 seconds.

Request Body

{
  "prompt": "battery capacity in milliampere-hours",   // required, at most 500 characters
  "name": "Battery Capacity",                          // optional, at most 100 characters
  "specification_id": "uuid",                          // optional: rewrite this saved specification
  "specification": {...},                              // optional: rewrite this unsaved definition (description at most 5000 characters, options at most 200)
  "category_id": "uuid",                               // optional, for context
  "language": "en",                                    // optional; default "en", or the definition's own language when rewriting
  "existing_spec_ids": ["uuid", ...]                   // optional, at most 20, for context
}
Responses
  • 200 Successful Response
  • {
      "draft": {
        "name": "Battery Capacity",
        "description": "Rated capacity of the battery cell",
        "instance": "integer",          // draft labels: "float" | "integer" | "string" | "boolean"
        "unit": "mAh",
        "tolerance": null,
        "options": null,
        "sub_values": null,
        "subvalue_elements": null,
        "subvalues_ordered": true,
        "user_id": "uuid"
      },
      "suggested_name": "Battery Capacity",   // a proposal only; the draft never renames on its own
      "findings": [                           // what the review step flagged
        {"check": "string", "field": "description", "message": "string", "evidence": "string"}
      ],
      "changed_fields": ["description"],
      "duplicate_candidates": [
        {"id": "uuid", "name": "Battery Capacity", "description": "...", "instance": "integer", "unit": "mAh"}
      ],
      "warnings": []   // advisory codes, e.g. needs_manual_review, high_similarity_existing_spec, missing_unit_guess,
                       // unit_on_non_numeric_spec, subvalues_order_dropped, unit_in_description, options_list_long, review_unavailable
    }
  • 400 invalid_prompt
  • 403 access_level_insufficient, forbidden_category, forbidden_specification
  • 404 category_not_found, specification_not_found
  • 422 Validation Error
  • 502 draft_generation_failed, draft_normalization_failed: the AI model failed; try again
POST /api/v2/specifications/review AI-review a spec

Check a specification against our definition rules and get a revised copy. Send a saved specification (specification_id), an unsaved one (specification), or both to review unsaved edits of a saved specification. Nothing is saved.

Enterprise only (access level full). Rate limit: 20 requests per minute.

Request Body

{
  "specification_id": "uuid",          // and/or
  "specification": {...},              // an unsaved definition, same fields as create
  "category_id": "uuid",               // optional, for context
  "language": "en",                    // optional
  "existing_spec_ids": ["uuid", ...]   // optional, for context
}
Responses
  • 200 Successful Response
  • {
      "findings": [
        {"check": "string", "field": "description", "message": "string", "evidence": "string"}
      ],
      "revised": {...},                 // the specification with the findings fixed
      "changed_fields": ["description"],
      "suggested_name": null,
      "warnings": []
    }
  • 403 access_level_insufficient, forbidden_category, forbidden_specification
  • 404 category_not_found, specification_not_found
  • 422 Validation Error
  • 502 review_generation_failed, review_normalization_failed
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": "Laptops",
        "user_id": "uuid",
        "created_at": "2026-01-01T00:00:00Z",
        "updated_at": "2026-01-01T00:00:00Z"
      }
    ]
  • 422 Validation Error

Categories

Categories group related specifications.

GET /api/v2/categories List categories

List categories visible to the current user.

Rate limit: 50 requests per minute.

Parameters

search Optional string. Default: "".

scope Optional string. Default: all. Allowed: all (own + public), owned, public, mine.

skip Optional integer, 0 or more. Default: 0.

limit Optional integer. 0 to 1000. Default: 100; 0 returns only the pagination block.

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": "Laptops",
          "user_id": "uuid",
          "top_category": null,
          "path": [],
          "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.

Rate limit: 100 requests per minute. 403 forbidden_category for someone else's private category, 404 category_not_found.

Responses
  • 200 Successful Response, schema: #/components/schemas/CategoryPublic
  • {
      "id": "uuid",
      "name": "Laptops",
      "user_id": "uuid",
      "top_category": null,           // ID of the parent category, or null
      "path": [],                     // IDs of the parent categories
      "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.

Rate limit: 100 requests per minute.

Parameters

category_id Path parameter, required UUID.

skip Query parameter, optional integer, 0 or more. Default: 0.

limit Query parameter, optional integer. 0 to 1000. Default: 100; 0 returns only the pagination block.

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, optionally below a parent category. Keep category names unique; the API does not enforce this, but duplicate names make categories hard to tell apart.

Rate limit: 200 requests per minute.

Request Body

{
  "name": "Laptops",              // required
  "top_category": "uuid"          // optional: the parent category
}
Responses
  • 201 Successful Response, schema: #/components/schemas/CategoryPublic
  • 403 forbidden_parent_category; 404 parent_category_not_found
  • 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. The body replaces the category: leaving out top_category moves it to the top level.

Rate limit: 100 requests per minute. 400 category_hierarchy_cycle if the new parent is the category itself or one of its sub-categories; 403 forbidden_category / forbidden_parent_category; 404 category_not_found / parent_category_not_found.

Request Body

{
  "name": "New Category Name",
  "top_category": "uuid"          // optional; omitted = top level
}
Responses
  • 200 Successful Response, schema: #/components/schemas/CategoryPublic
  • {
      "id": "uuid",
      "name": "Laptops",
      "user_id": "uuid",
      "top_category": null,           // ID of the parent category, or null
      "path": [],                     // IDs of the parent categories
      "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

Deletes the category and its sub-categories. Domain rules whose only scope was this category are switched off. Specifications stay; they are only detached.

Rate limit: 100 requests per minute. 403 forbidden_category; 404 category_not_found.

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. Specification names must be unique within a category (case-insensitive). Attaching an already attached specification changes nothing and returns 201 {"detail": "already attached"}. You can attach your own specifications to a public category, but not public or other users' ones.

Rate limit: 100 requests per minute.

Responses
  • 201 Successful Response: {"detail": "attached"}
  • 403 forbidden_category, forbidden_specification, public_category_accepts_only_own_specifications
  • 404 category_not_found, specification_not_found
  • 409 specification_name_conflict_in_category: another spec with the same name is already attached
  • 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.

Rate limit: 100 requests per minute. 403 forbidden_category / forbidden_specification; 404 category_not_found / specification_not_attached_to_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 new category with the same specifications attached. The specifications are shared, not copied: editing one with scope=all_categories changes it in both categories, while scope=this_category forks it for one of them. Other users' private specifications are left out, and the copy starts at the top level. No request body required.

Rate limit: 50 requests per minute.

Responses
  • 201 Successful Response - returns CategoryPublic of the new category
  • 422 Validation Error

Domain Rules (Blacklist & Whitelist)

Saved domain rules steer which websites a search uses. The blacklist excludes domains from web searches and scraping; the whitelist adds domains as sources and can declare how much to trust them. Each user holds at most one rule per domain per list. Every route below exists for both lists; {list} stands for blacklist or whitelist.

Rate limits: creating a rule 50 requests per minute, every other domain-rule route 100.

Global vs. scoped rules

  • A rule with no scope terms is global and applies to every search (source stored).
  • A scope term is one situation the rule applies in: {"category_id": ..., "brand": ...} with at least one part set. The parts of one term AND together; a rule's terms OR together.
  • A search activates a term only if its category / brand parameters match the term's parts. A missing part is never a wildcard.
  • Brands are normalized (trim, collapse whitespace, lowercase, max 128 chars). Responses carry both brand (identity) and brand_display (as entered).
  • Max 100 scope terms per rule.

Trust ladder (whitelist only)

  • normal - include the domain as a source, no further claim.
  • trusted - strong prior: values from this domain get a high per-value confidence and the domain is ranked higher. Values are still cross-source verified.
  • authoritative - the product's own source (e.g. the manufacturer). SpecScout already recognises a manufacturer site when the brand is part of its domain name; mark it here when the domain differs, for example a sub-brand on the parent company's domain. Everything trusted does, plus its pages get a second, independent extraction so specs only this source publishes can still be confirmed.

A rule has a base trust; a scope term may override it for its own situation (effective_trust). globally_active: true puts a scoped whitelist rule into the stored pool at its base trust while its terms keep acting as overrides.

source_kind (manufacturer | comparison_portal) is a purely descriptive label available on both lists.

How a search picks rules up is controlled per request by blacklist_sources / whitelist_sources on Search. Error responses from this family carry a machine-readable code (see Errors).

GET /api/v1/users/search-settings/{list} List rules

List the current user's saved rules for one list. Without sources this is a plain listing. With sources it becomes the effective-set view: only rules that a search with the given category_id / brand context would pick up from those pools, each with its activation reason in source and a probe. Add is_active=true to preview exactly what a search would use.

Parameters

search Optional string. Substring match on the domain.

is_active Optional boolean. Filter by active state.

category_id Optional UUID. Rules with a scope term naming this category. Also the category context for the effective-set view.

brand Optional string. Rules with a scope term naming this brand (normalized server-side). Also the brand context for the effective-set view.

sources Optional, repeatable. Turns on the effective-set view. Allowed: stored, category, brand (e.g. ?sources=stored&sources=category&sources=brand). provided and none are rejected with 422. Requesting only scoped sources with no category_id/brand context is a 422 (guaranteed-empty view).

source_kind Optional string. Allowed: manufacturer, comparison_portal, unset (rules without a classification).

trust Optional string, whitelist only. Exact match on the rule's base trust: normal, trusted, authoritative.

skip Optional integer, 0 or more. Default: 0.

limit Optional integer. 0 to 1000. Default: 100; 0 returns only the pagination block.

sortBy Optional string. Default: created_at. Allowed: created_at, updated_at, domain, is_active; whitelist additionally trust (ordered by ladder rank, not alphabetically).

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

Responses
  • 200 Successful Response, schema: DomainBlacklistItemListResponse / DomainWhitelistItemListResponse
  • {
      "items": [
        {
          "id": "uuid",
          "user_id": "uuid",
          "domain": "bosch.com",
          "trust": "trusted",                 // whitelist only: "normal" | "trusted" | "authoritative"
          "source_kind": "manufacturer",      // both lists: "manufacturer" | "comparison_portal" | null
          "globally_active": false,           // whitelist only
          "is_active": true,
          "created_at": "2026-01-01T00:00:00Z",
          "updated_at": "2026-01-01T00:00:00Z",
          "category_count": 1,                // distinct categories across the rule's scope terms
          "brand_count": 1,                   // distinct brands across the rule's scope terms
          "scope_term_count": 2,              // number of scope terms; 0 = global rule
          "source": null,                     // only set in the sources= view: "stored" | "category" | "brand" | "category_and_brand"
          "probe": null                       // only set when probing (see single-rule detail)
        }
      ],
      "pagination": {"total": 5, "skip": 0, "limit": 100, "returned": 1, "has_prev": false, "has_next": false, "next_skip": null, "prev_skip": null}
    }
  • 422 Validation Error
POST /api/v1/users/search-settings/{list} Create rule

Create a rule for a domain. Without scopes the rule is global; each scopes entry becomes one scope term. Creating a domain that already has a rule on this list is always a 409. There is no upsert; use ensure for an idempotent "make sure this domain is covered" call.

Request Body

{
  "domain": "bosch.com",                       // required, 1-2048 chars
  "source_kind": "manufacturer",               // optional, both lists: "manufacturer" | "comparison_portal"
  "trust": "trusted",                          // whitelist only, optional, default "normal"
  "globally_active": false,                    // whitelist only, optional; true requires at least one scope entry
  "scopes": [                                  // optional, max 100 entries; omit or [] for a global rule
    {"category_id": "uuid"},                   // applies to searches in this category
    {"brand": "Bosch", "trust": "authoritative"},  // applies to searches for this brand; per-term trust is whitelist only
    {"category_id": "uuid", "brand": "Bosch"}  // both parts must match (AND)
  ]
}

Sending trust inside a scope entry or globally_active on a blacklist rule is rejected with 422.

Responses
  • 201 Successful Response, schema: DomainBlacklistItemPublic / DomainWhitelistItemPublic (see list example above)
  • 404 category_not_found for an unknown category_id in scopes
  • 409 domain_blacklist_item_duplicate / domain_whitelist_item_duplicate if the domain already has a rule; domain_blacklist_limit_exceeded / domain_whitelist_limit_exceeded at the per-user rule cap
  • 422 invalid_scope_term for an empty scope entry; validation_error for a blacklist globally_active or globally_active: true without scopes; invalid_domain_blacklist_entry / invalid_domain_whitelist_entry for an invalid domain
GET /api/v1/users/search-settings/{list}/{item_id} Get rule (with scope terms)

Single rule with its scope terms embedded. scopes is the authoritative list; categories and brands are derived per-dimension views of the same terms. Pass sources to additionally probe the rule: "would a search with this context see this rule, and at which trust?" (computed with the same logic the search uses).

Parameters

item_id Path parameter, required UUID.

sources Optional, repeatable. Same values as on the list route. Turns probing on; without it probe is null.

category_id Optional UUID. Probe context. Only allowed together with sources (422 otherwise); unknown category is 404.

brand Optional string. Probe context. Only allowed together with sources.

Responses
  • 200 Successful Response, schema: DomainBlacklistItemDetail / DomainWhitelistItemDetail. Blacklist responses carry no trust fields at all.
  • {
      "id": "uuid", "user_id": "uuid", "domain": "bosch.com",
      "trust": "trusted", "source_kind": "manufacturer", "globally_active": false, "is_active": true,
      "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z",
      "category_count": 1, "brand_count": 1, "scope_term_count": 2, "source": null,
      "scopes": [                          // authoritative list of scope terms; "id" is what DELETE .../scopes/{term_id} takes
        {"id": "uuid", "category_id": "uuid", "category_name": "Power Tools", "brand": null, "brand_display": null,
         "trust": null, "effective_trust": "trusted", "attached_at": "2026-01-01T00:00:00Z"},
        {"id": "uuid", "category_id": null, "category_name": null, "brand": "bosch", "brand_display": "Bosch",
         "trust": "authoritative", "effective_trust": "authoritative", "attached_at": "2026-01-01T00:00:00Z"}
      ],
      "categories": [{"category_id": "uuid", "category_name": "Power Tools", "attached_at": "2026-01-01T00:00:00Z"}],
      "brands": [{"brand": "bosch", "brand_display": "Bosch", "attached_at": "2026-01-01T00:00:00Z"}],
      "probe": {                           // only when ?sources=... was given, otherwise null
        "activated": true,
        "effective_trust": "authoritative", // whitelist only; null when not activated
        "matched_term_ids": ["uuid"],
        "deciding_term_id": "uuid"          // whitelist only
      }
    }
  • 404 domain_blacklist_item_not_found / domain_whitelist_item_not_found
  • 422 Validation Error
PATCH /api/v1/users/search-settings/{list}/{item_id} Update rule

Partial update: an omitted key leaves the stored value untouched. Scope terms are managed through the term routes below, not here.

Request Body

{
  "is_active": false,           // optional: disable/enable without deleting
  "trust": "authoritative",     // whitelist only, optional: raises or lowers the rule's base trust (null = no-op)
  "source_kind": null,          // optional, both lists; explicit null clears the classification
  "globally_active": true       // whitelist only, optional; true requires at least one stored scope term
}
Responses
  • 200 Successful Response, returns the updated DomainBlacklistItemPublic / DomainWhitelistItemPublic
  • 404 domain_blacklist_item_not_found / domain_whitelist_item_not_found
  • 422 validation_error for globally_active on a blacklist rule or on a rule without scope terms
DELETE /api/v1/users/search-settings/{list}/{item_id} Delete rule

Deletes the rule together with all its scope terms.

Responses
  • 204 Successful Response (no content)
  • 404 domain_blacklist_item_not_found / domain_whitelist_item_not_found
  • 422 Validation Error
POST /api/v1/users/search-settings/{list}/ensure Ensure rule covers a scope (idempotent)

Guide: a "block this source" button in your own system

  1. Show the sources of each value next to it in your PIM or review tool.
  2. Next to each source, offer "Block for this brand" (blacklist) and "Trust for this brand" (whitelist). On click, take the domain from the source URL and call ensure with the product's brand or your category_id.
  3. Because ensure only ever widens a rule and is safe to repeat, you can call it on every click without reading the list first. Show the outcome as a short confirmation ("blocked", "was already blocked").
  4. The next search for that brand or category leaves the domain out (blacklist) or ranks it higher (whitelist).
POST /api/v1/users/search-settings/blacklist/ensure
x_api_key: <API_KEY>
Content-Type: application/json

{"domain": "annoying-shop.de", "brand": "Samsung"}

// 200: {"outcome": "created", "reactivated": false, ...}

Goal-directed "block this source" / "trust this source" call. After it returns, a rule for the domain exists, is active, and covers at least the requested scope (or the whole domain if no scope is given). It never narrows an existing rule and never lowers trust. At most one scope per call.

Request Body

{"domain": "annoying-shop.de", "category_id": "uuid"}                 // scope: one category
{"domain": "annoying-shop.de", "brand": "Sony"}                       // scope: one brand
{"domain": "annoying-shop.de", "category_id": "uuid", "brand": "Sony"} // scope: category AND brand
{"domain": "annoying-shop.de"}                                        // global: covers every search

{"domain": "good-source.de", "brand": "Sony"}                         // whitelist: trust omitted => "trusted"
{"domain": "good-source.de", "brand": "Sony", "trust": "normal"}      // whitelist: include only, no confidence boost

Whitelist only: trust is optional and defaults to trusted here (unlike create, where the default is normal). Ensure raises the covering term's or the rule's trust to the requested rung if it is lower. The blacklist request body has no trust field; sending one is 422.

Outcomes

Rule beforeRequestEffectoutcome
missingglobal or scopedrule createdcreated
globalanythingno scope change (already covers everything)already_global
scopedscope already covered by an existing termno scope changealready_covered
scopednew scopeterm appendedscope_added
scopedglobalall terms deleted, returned in removed_scopespromoted_to_global

An inactive rule is reactivated by any ensure call (reactivated: true). A 409 scope_term_limit_exceeded can therefore still have reactivated the rule; re-read the rule after a 409.

Responses
  • 200 Successful Response, schema: DomainBlacklistEnsureResponse / DomainWhitelistEnsureResponse
  • {
      ...single-rule detail fields (see GET /{list}/{item_id})...,
      "outcome": "scope_added",     // "created" | "scope_added" | "already_covered" | "already_global" | "promoted_to_global"
      "reactivated": false,         // true if the rule was inactive and this call switched it back on
      "trust_raised": false,        // whitelist only: true if this call raised a term's or the rule's trust
      "removed_scopes": []          // only on "promoted_to_global": the scope terms that were deleted
    }
  • 404 category_not_found
  • 409 scope_term_limit_exceeded (100 terms per rule); domain_blacklist_limit_exceeded / domain_whitelist_limit_exceeded on create
  • 422 invalid_scope_term; Validation Error
POST /api/v1/users/search-settings/{list}/{item_id}/scopes Add scope term

Add one scope term to a rule. At least one of category_id / brand is required. Adding a term to a global rule scopes it down (explicit narrowing).

Request Body

{
  "category_id": "uuid",     // optional
  "brand": "Bosch",          // optional; normalized (trim, collapse whitespace, lowercase, max 128 chars)
  "trust": "authoritative"   // whitelist only, optional: overrides the rule's trust when this term matches
}
Responses
  • 201 Successful Response, schema: RuleScopeTermPublic (whitelist) / BlacklistRuleScopeTermPublic (blacklist, without the two trust fields)
  • {
      "id": "uuid",
      "category_id": "uuid",
      "category_name": "Power Tools",
      "brand": "bosch",                 // normalized identity
      "brand_display": "Bosch",         // as entered
      "trust": null,                    // whitelist only: this term's own override, null = inherits the rule's trust
      "effective_trust": "trusted",     // whitelist only
      "attached_at": "2026-01-01T00:00:00Z"
    }
  • 404 domain_blacklist_item_not_found / domain_whitelist_item_not_found; category_not_found
  • 409 scope_term_duplicate; scope_term_limit_exceeded (100 terms per rule)
  • 422 invalid_scope_term (empty term, or trust on a blacklist term); invalid_brand
GET /api/v1/users/search-settings/{list}/{item_id}/scopes List scope terms

Paginated list of the rule's scope terms, newest first.

Parameters

skip Optional integer, 0 or more. Default: 0.

limit Optional integer. 0 to 1000. Default: 100; 0 returns only the pagination block.

Responses
  • 200 Successful Response: {"items": [...scope terms...], "pagination": {...}}
  • 404 domain_blacklist_item_not_found / domain_whitelist_item_not_found
DELETE /api/v1/users/search-settings/{list}/{item_id}/scopes/{term_id} Remove scope term

Remove one scope term. A rule's last term cannot be deleted (that would silently turn a scoped rule into a global one); use ensure without a scope to promote the rule to global explicitly, or delete the rule.

Responses
  • 204 Successful Response (no content)
  • 404 scope_term_not_found; domain_blacklist_item_not_found / domain_whitelist_item_not_found
  • 409 scope_term_last_undeletable (exception: the last term of a whitelist rule flagged globally_active may be deleted; the flag is cleared)
SHORTCUTS /api/v1/users/search-settings/{list}/{item_id}/categories | /brands Single-part scope terms

Convenience routes for scope terms that name only a category or only a brand. They map onto the term routes above and return the same error codes. A two-part term (category AND brand) can only be added via POST .../scopes.

POST .../categories/{category_id} - add the term (category, -). 201 {"detail": "attached"}; 409 scope_term_duplicate.

DELETE .../categories/{category_id} - remove only the term (category, -). 204; 404 scope_term_not_found if the category is referenced only inside a two-part term; 409 scope_term_last_undeletable.

GET .../categories?skip=&limit= - distinct categories across all of the rule's terms: {"items": [{"category_id", "category_name", "attached_at"}], "pagination": {...}}.

POST .../brands/{brand} - add the term (-, brand). The path segment is URL-encoded and normalized server-side. 201 {"detail": "attached"}; 409 scope_term_duplicate; 422 invalid_brand (empty or longer than 128 characters).

DELETE .../brands/{brand} - remove only the term (-, brand). Same errors as the category variant.

GET .../brands?skip=&limit= - distinct brands across all of the rule's terms: {"items": [{"brand", "brand_display", "attached_at"}], "pagination": {...}}.

GET /api/v1/users/search-settings/brands Brand autocomplete

Distinct brands the current user has attached to any rule on either list, in display form, for autocomplete inputs.

Parameters

search Optional string. Case-insensitive substring filter.

limit Optional integer. Default: 50, range 1-200.

Responses
  • 200 Successful Response, schema: BrandSuggestResponse
  • {"items": ["Bosch", "Bosch Professional", "Sony"]}
  • 422 Validation Error

Changelog

Changes you may notice as an API user, newest first.

  • 2026-10-19
    • limit=0 on list routes returns only the pagination block.
  • 2026-10-15
    • Negative skip is rejected with 422 on every list; limit is 0 to 1000.
    • GET /users/me shows pending_email while an email change waits for confirmation.
  • 2026-10-08
    • Every error response has a stable code; the OpenAPI schema lists the codes per route.
    • Rate limits answer 429 rate_limit_exceeded with the standard error body.
    • Search: a processing failure is now 500 search_processing_failed (was 400), an unavailable browser 503 browser_unavailable (was 400), a category that is not a UUID 422 (was 400).
    • Attaching a specification reports a missing category and a missing specification separately.
  • 2026-10-07
    • Every error with a code carries a correlation_id and the X-Correlation-ID header.
    • Malformed JSON in search parameters is 422 validation_error (was 400).
  • 2026-10-04
    • Specification draft: prompt up to 500 characters (was 200); rewrite an existing definition with specification_id or specification; optional name; suggested_name in the response, never an automatic rename; new warning options_list_long.
  • 2026-09-28
    • GET /quotas/me returns free_limit for trial accounts.
  • 2026-09-27
    • Demo keys removed; demo_count removed from the monthly usage.
  • 2026-09-26
    • is_activated removed from user responses and the error account_not_activated removed.
    • validate_api_key returns access_level; the monthly usage has trial_count.
  • 2026-09-25
    • Access levels trial / free / full replace account activation. Free accounts search against their own monthly allowance (free_count in the monthly usage).
    • Specification draft and review need the Enterprise plan (403 access_level_insufficient).
  • 2026-09-17
    • Review accepts specification_id and specification together, to review unsaved edits of a saved specification.
  • 2026-09-13
    • New POST /api/v2/specifications/review. The draft endpoint runs the same review and returns findings and changed_fields.
  • 2026-09-07
    • Requests with a body must send Content-Type: application/json, otherwise 422.