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. 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_KEYin your environment. -
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. 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. Read the result
Each entry in
specsholds 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 innot_found, never guessed. -
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).
- Save your specifications once as a category and search with
Search
CORE SERVICEPerforms the core SpecScout service: searches the web for product specifications based on a query.
Query Parameters
- product_name Required string. E.g. "MacBook Pro 16 M3 Max". A barcode (8 or more digits) next to other words is left out of the web search; a name that is only a barcode or part number is searched as it is.
- brand Required string. E.g. "Apple". Also activates saved domain rules scoped to this brand.
- required_specs Optional string (nullable). JSON-encoded array of specification objects to look for, using the same fields as specification creation (including
sub_values,options,tolerance), e.g.[{"name": "Battery Capacity", "description": "Rated capacity of the battery", "instance": "int", "unit": "mAh"}]. Invalid JSON or a non-array is rejected with422 validation_error; so is an entry that fails validation ({"index": n, "errors": [...]}). - category Optional string. ID (UUID) of a predefined category (see category creation) whose attached specifications should be looked for. Not the category name. Values that are not valid UUIDs are rejected with
422 validation_error; an unknown or inaccessible category with404 category_not_found. At least one specification must result fromrequired_specsand/orcategory, otherwise400 no_specifications_to_search. - include_product_images Optional boolean. Default:
false. Include product image URLs in the response. - blacklist_sources Optional, repeatable. Which pools feed the effective domain blacklist for this request:
stored(your global saved rules),category(saved rules scoped to the searched category),brand(saved rules scoped to the searched brand),provided(theblacklist_domainslist below),none(disable the blacklist; must be the only value). Default when absent: all four real sources. E.g.?blacklist_sources=stored&blacklist_sources=provided. - whitelist_sources Optional, repeatable. Same values and default as
blacklist_sources, for the effective domain whitelist. - whitelist_exclusive Optional boolean. Default:
false. Whentrue, the entire search run is restricted to whitelisted domains (all web searches are site-restricted, other URLs are dropped before scraping). Without it the whitelist only adds and boosts sources. Requires a non-empty effective whitelist. - blacklist_domains Optional string. JSON-encoded array of domains to exclude for this request only, e.g.
["ebay.com", "amazon.de"]. Requiresprovidedinblacklist_sources(it is by default). - whitelist_domains Optional string. JSON-encoded array of objects for this request only, e.g.
[{"domain": "bosch.com", "trust": "authoritative"}].trustis optional:normal(default),trusted,authoritative(see the trust ladder under Domain Rules). Requiresprovidedinwhitelist_sources. Provided entries win over saved rules for the same domain.
Domain-rule validation (422, code: "validation_error")
nonecombined with any other value in the same*_sourceslist.whitelist_exclusive=truetogether withwhitelist_sources=none, or with an empty effective whitelist (no saved rule matched and nowhitelist_domainsgiven).blacklist_domains/whitelist_domainssupplied whileprovidedis not in that list's sources.
Duplicate source values are tolerated. Malformed JSON in a domain list, or JSON that is not a list, is 422 too; an invalid entry (non-string domain, unknown trust) is 422 with {"index": n, "error": "..."}.
Rate limit: 200 requests per minute. A search takes about 10 to 40 seconds and at most 175; set your client timeout to at least 180 seconds. The server also caps how many searches run at the same time: when it is busy you get 429 search_concurrency_limit_reached with a Retry-After header; wait that many seconds and try again. Every completed search counts against your quota, including one that ends with status: "fail"; error responses do not.
Success Response (200 OK)
{
"status": "success",
"specs": [
{
"id": "3fa85f64-...",
"name": "Processor",
"instance": "str",
"value": [
{
"value": "Apple M3 Max",
"unit": null,
"sources": ["https://www.apple.com/macbook-pro/specs/", "https://www.notebookcheck.net/..."],
"confidence": 0.84
}
],
"unit": null
}
],
"not_found": [],
"errors": [],
"image_links": null // populated when include_product_images=true
}
Responses
200Successful Response, schema:#/components/schemas/ServiceResponsePublic
{
"specs": [{ // SpecificationLite: one entry per specification with at least one verified value
"id": "uuid",
"name": "string",
"instance": "string", // "float" | "int" | "str" | "bool"
"unit": "string | null",
"value": [ // one entry per verified value; several when sources legitimately
{ // differ (e.g. 256 GB and 512 GB), each with its own sources
"value": "string | number | boolean | array", // array only for sub_values specs (ranges, dimensions)
"unit": "string | null",
"sources": ["url"], // at least two independent pages, or one authoritative page (see Confidence scores)
"confidence": 0.89 // 0 to 0.99, see Confidence scores
}
]
}],
"status": "success", // "success" or "fail"; on "fail", errors = ["No consistent specifications found"]
"not_found": [ // same SpecificationLite shape as specs, always with an empty value list
{"id": "uuid", "name": "string", "instance": "string", "unit": "string | null", "value": []}
],
"errors": ["string"],
"image_links": [{"url": "string", "source_page": "string"}] // null unless include_product_images=true ([] on "fail")
}
400 no_specifications_to_search: neither required_specs nor category gave a specification to look for401 not_authenticated (missing or invalid key), email_not_verified, account_blocked, trial_key_ended403 api_key_scope_insufficient404 category_not_found (does not exist or is not visible to you)422 validation_error: malformed required_specs / domain-list JSON, category not a UUID, or one of the domain-rule rules above; or FastAPI's schema error (missing product_name or brand):{
"detail": [
{"loc": ["query", "field_name"], "msg": "Field required", "type": "missing"}
]
}
429 rate_limit_exceeded (200 per minute), search_quota_exceeded (monthly allowance used up, see Quotas; checked before the category), search_concurrency_limit_reached (server busy; honour Retry-After)500 search_processing_failed503 browser_unavailable: temporary, retry laterConfidence 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
authoritativein your domain rules. It is read by two different AI models, which counts as two sources. Everything else ends up innot_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
trustedorauthoritativecount 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.
| Confidence | Typically means |
|---|---|
| around 0.5 | two pages from sites with little track record |
| around 0.75 | two good sources, for example a specification database and a review |
| 0.85 to 0.9 | three or four good sources |
| 0.95 and above | four 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>
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
200Successful 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_endedMaking 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.
| Status | Meaning | Typical codes |
|---|---|---|
| 400 | The request cannot be carried out as asked | no_specifications_to_search, invalid_prompt, category_hierarchy_cycle |
| 401 | Missing, invalid, expired or revoked API key; email not confirmed; account blocked; trial ended | not_authenticated, invalid_or_missing_api_key, invalid_api_key (validate_api_key), email_not_verified, account_blocked, trial_key_ended |
| 403 | Key valid but not allowed: access level or key scope too low, someone else's private resource | access_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 |
| 404 | Resource does not exist or is not visible to you | category_not_found, specification_not_found, specification_not_attached_to_category, parent_category_not_found, domain_blacklist_item_not_found, scope_term_not_found, ... |
| 409 | Conflict with existing data or a cap | specification_name_conflict_in_category, domain_whitelist_item_duplicate, scope_term_duplicate, scope_term_limit_exceeded, scope_term_last_undeletable |
| 422 | Request understood but invalid, including malformed JSON in a query parameter and a category that is not a UUID | validation_error, invalid_scope_term, invalid_brand, or FastAPI's {"detail": [...]} |
| 429 | Rate 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 |
| 500 | Unexpected failure; nothing about the cause is exposed | internal_server_error, search_processing_failed |
| 502 | The AI model behind the specification assistant failed | draft_generation_failed, draft_normalization_failed, review_generation_failed, review_normalization_failed |
| 503 | Temporarily unavailable; retry later | browser_unavailable |
Users
Get your account information.
Rate limit: 20 requests per minute.
Responses
200Successful 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 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
200Successful 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 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
200Successful 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/HTTPValidationErrorSpecifications
Best Practices
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"whileunit: "inch"is already setinstance: "list"(not allowed - usesub_valuesfor 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; definesub_valueswhen a spec has multiple values. - Use
intonly for counts (cores, gears). Physical quantities (weight, size, clock speed) arefloat, even if they are usually listed as whole numbers. unitis optional. Leave it out for values without a unit; it reads back asnull. Unit conversion only happens forint/float; on astrspec a unit acts as a format hint, onboolit does nothing.- No duplicated semantics: if
unitis 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_elementsis 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_elementsstaysnullfor a variable count or states a fixed count ≥ 2).subvalues_orderedsays whether each position has a fixed meaning; it defaults totruefor the array form andfalsefor the string form, andtruewith 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:
float0.02,int0,str0.15 (recommended to keep near that),boolignored. 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 Capacityinstead ofBattery; 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.
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
201Successful 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"}
]
}
/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
200Successful 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"}
]
}
/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
200Successful 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"}
]
}
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
200Successful 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"}
]
}
/api/v2/specifications/{spec_id}
Delete spec
Responses
204Successful Response (no content)403forbidden_specification(not your own);404specification_not_found422Validation Error, schema:#/components/schemas/HTTPValidationError
Rate limit: 100 requests per minute.
/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
200Successful 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_prompt403 access_level_insufficient, forbidden_category, forbidden_specification404 category_not_found, specification_not_found422 Validation Error502 draft_generation_failed, draft_normalization_failed: the AI model failed; try again/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
200Successful 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_specification404 category_not_found, specification_not_found422 Validation Error502 review_generation_failed, review_normalization_failed/api/v2/specifications/{spec_id}/categories
List spec's categories
List all categories the specification is attached to.
Responses
200Successful Response - array ofCategoryPublic
[
{
"id": "uuid",
"name": "Laptops",
"user_id": "uuid",
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T00:00:00Z"
}
]
422 Validation ErrorCategories
Categories group related specifications.
/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
200Successful 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"}
]
}
/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
200Successful 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"}
]
}
/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
200Successful 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"}
]
}
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
201Successful Response, schema:#/components/schemas/CategoryPublic403forbidden_parent_category;404parent_category_not_found422Validation Error, schema:#/components/schemas/HTTPValidationError
{
"detail": [
{"loc": ["query", "field_name"], "msg": "Field required", "type": "missing"}
]
}
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
200Successful 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"}
]
}
/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
204Successful Response (no content)422Validation Error, schema:#/components/schemas/HTTPValidationError
{
"detail": [
{"loc": ["query", "field_name"], "msg": "Field required", "type": "missing"}
]
}
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
201Successful Response:{"detail": "attached"}403forbidden_category,forbidden_specification,public_category_accepts_only_own_specifications404category_not_found,specification_not_found409specification_name_conflict_in_category: another spec with the same name is already attached422Validation Error, schema:#/components/schemas/HTTPValidationError
{
"detail": [
{"loc": ["query", "field_name"], "msg": "Field required", "type": "missing"}
]
}
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
204Successful Response (no content)422Validation Error, schema:#/components/schemas/HTTPValidationError
{
"detail": [
{"loc": ["query", "field_name"], "msg": "Field required", "type": "missing"}
]
}
/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
201Successful Response - returnsCategoryPublicof the new category422Validation 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/brandparameters 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) andbrand_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. Everythingtrusteddoes, 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).
/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
200Successful 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/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
201Successful Response, schema:DomainBlacklistItemPublic/DomainWhitelistItemPublic(see list example above)404category_not_foundfor an unknowncategory_idinscopes409domain_blacklist_item_duplicate/domain_whitelist_item_duplicateif the domain already has a rule;domain_blacklist_limit_exceeded/domain_whitelist_limit_exceededat the per-user rule cap422invalid_scope_termfor an empty scope entry;validation_errorfor a blacklistglobally_activeorglobally_active: truewithout scopes;invalid_domain_blacklist_entry/invalid_domain_whitelist_entryfor an invalid domain
/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
200Successful 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_found422 Validation Error/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
200Successful Response, returns the updatedDomainBlacklistItemPublic/DomainWhitelistItemPublic404domain_blacklist_item_not_found/domain_whitelist_item_not_found422validation_errorforglobally_activeon a blacklist rule or on a rule without scope terms
/api/v1/users/search-settings/{list}/{item_id}
Delete rule
Deletes the rule together with all its scope terms.
Responses
204Successful Response (no content)404domain_blacklist_item_not_found/domain_whitelist_item_not_found422Validation Error
/api/v1/users/search-settings/{list}/ensure
Ensure rule covers a scope (idempotent)
Guide: a "block this source" button in your own system
- Show the
sourcesof each value next to it in your PIM or review tool. - 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
ensurewith the product'sbrandor yourcategory_id. - 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
outcomeas a short confirmation ("blocked", "was already blocked"). - 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 before | Request | Effect | outcome |
|---|---|---|---|
| missing | global or scoped | rule created | created |
| global | anything | no scope change (already covers everything) | already_global |
| scoped | scope already covered by an existing term | no scope change | already_covered |
| scoped | new scope | term appended | scope_added |
| scoped | global | all terms deleted, returned in removed_scopes | promoted_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
200Successful 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_found409 scope_term_limit_exceeded (100 terms per rule); domain_blacklist_limit_exceeded / domain_whitelist_limit_exceeded on create422 invalid_scope_term; Validation Error/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
201Successful 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_found409 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/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
200Successful Response:{"items": [...scope terms...], "pagination": {...}}404domain_blacklist_item_not_found/domain_whitelist_item_not_found
/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
204Successful Response (no content)404scope_term_not_found;domain_blacklist_item_not_found/domain_whitelist_item_not_found409scope_term_last_undeletable(exception: the last term of a whitelist rule flaggedglobally_activemay be deleted; the flag is cleared)
/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": {...}}.
/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
200Successful Response, schema:BrandSuggestResponse
{"items": ["Bosch", "Bosch Professional", "Sony"]}
422 Validation ErrorChangelog
Changes you may notice as an API user, newest first.
- 2026-10-19
limit=0on list routes returns only the pagination block.
- 2026-10-15
- Negative
skipis rejected with 422 on every list;limitis 0 to 1000. GET /users/meshowspending_emailwhile an email change waits for confirmation.
- Negative
- 2026-10-08
- Every error response has a stable
code; the OpenAPI schema lists the codes per route. - Rate limits answer
429 rate_limit_exceededwith the standard error body. - Search: a processing failure is now
500 search_processing_failed(was 400), an unavailable browser503 browser_unavailable(was 400), acategorythat is not a UUID422(was 400). - Attaching a specification reports a missing category and a missing specification separately.
- Every error response has a stable
- 2026-10-07
- Every error with a
codecarries acorrelation_idand theX-Correlation-IDheader. - Malformed JSON in search parameters is
422 validation_error(was 400).
- Every error with a
- 2026-10-04
- Specification draft:
promptup to 500 characters (was 200); rewrite an existing definition withspecification_idorspecification; optionalname;suggested_namein the response, never an automatic rename; new warningoptions_list_long.
- Specification draft:
- 2026-09-28
GET /quotas/mereturnsfree_limitfor trial accounts.
- 2026-09-27
- Demo keys removed;
demo_countremoved from the monthly usage.
- Demo keys removed;
- 2026-09-26
is_activatedremoved from user responses and the erroraccount_not_activatedremoved.validate_api_keyreturnsaccess_level; the monthly usage hastrial_count.
- 2026-09-25
- Access levels
trial/free/fullreplace account activation. Free accounts search against their own monthly allowance (free_countin the monthly usage). - Specification draft and review need the Enterprise plan (
403 access_level_insufficient).
- Access levels
- 2026-09-17
- Review accepts
specification_idandspecificationtogether, to review unsaved edits of a saved specification.
- Review accepts
- 2026-09-13
- New
POST /api/v2/specifications/review. The draft endpoint runs the same review and returnsfindingsandchanged_fields.
- New
- 2026-09-07
- Requests with a body must send
Content-Type: application/json, otherwise 422.
- Requests with a body must send