{ "openapi": "3.1.0", "info": { "title": "OpenAxia Public API", "version": "1.0.0", "description": "OpenAxia — Read-only access to the claim-sourced knowledge base of motors, smart motion/shading products, manufacturers and certifications. Every spec, company fact and certification carries its original source and observation date. Only published, reviewed records are exposed. Access: anonymous callers get 60 requests per hour per client IP; a free API key (sent as \"Authorization: Bearer \" or \"X-API-Key: \") gets 5,000 requests per day per key. Over quota → 429 with Retry-After; an invalid or revoked key → 401. Every response reports the remaining quota in RateLimit-* headers. Attribution is required when data is reused (see x-attribution and GET /api/v1). Data may be quoted and reused with attribution: cite \"OpenAxia\" and link to the record page. Each value carries its original source; verify important facts there.", "license": { "name": "Attribution required — cite OpenAxia and link to the record page", "url": "https://openaxia.com/agent" }, "x-attribution": { "required": true, "name": "OpenAxia", "url": "https://openaxia.com", "text": "Attribution: OpenAxia (https://openaxia.com)", "policyUrl": "https://openaxia.com/agent", "notice": "Data may be quoted and reused with attribution: cite \"OpenAxia\" and link to the record page. Each value carries its original source; verify important facts there." } }, "servers": [ { "url": "https://openaxia.com" } ], "security": [ {}, { "ApiKeyHeader": [] }, { "BearerKey": [] } ], "paths": { "/api/v1": { "get": { "operationId": "getApiIndex", "summary": "API index: contract links, quota policy and the attribution term. Not counted against any quota.", "security": [ {} ], "responses": { "200": { "description": "The discovery document.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ApiIndex" } } } ] } } } } } } }, "/api/v1/products": { "get": { "operationId": "listProducts", "summary": "List/search/filter published products (same parameters and results as /products).", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Full-text search, 1–200 characters.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort key (default `updated`).", "schema": { "type": "string", "enum": [ "name", "manufacturer", "certs", "updated" ], "default": "updated" } }, { "name": "category", "in": "query", "required": false, "description": "Product category key, e.g. `tubular_motor`.", "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" } }, { "name": "manufacturer", "in": "query", "required": false, "description": "Manufacturer company `slug`(s) (server switch `MOTOBASE_PUBLIC_URLS_ENABLED` on) or legacy numeric ids (deprecated); repeat the parameter or comma-separate. An unknown slug yields an empty page.", "schema": { "type": "array", "items": { "type": "string", "maxLength": 96, "pattern": "^[A-Za-z0-9-]+$" } }, "style": "form", "explode": true, "examples": { "slug": { "value": [ "somfy" ] } } }, { "name": "applications", "in": "query", "required": false, "description": "Application id(s); repeat or comma-separate.", "schema": { "type": "array", "items": { "type": "string", "pattern": "^[0-9]{1,10}$" } }, "style": "form", "explode": true }, { "name": "technologies", "in": "query", "required": false, "description": "Technology id(s) (e.g. Matter, Zigbee); repeat or comma-separate.", "schema": { "type": "array", "items": { "type": "string", "pattern": "^[0-9]{1,10}$" } }, "style": "form", "explode": true }, { "name": "certified", "in": "query", "required": false, "description": "`1` = only products with at least one active, publicly verifiable certification.", "schema": { "type": "string", "enum": [ "0", "1" ] } }, { "name": "diameter_mm_min", "in": "query", "required": false, "description": "Inclusive lower bound for `diameter_mm`.", "schema": { "type": "number" } }, { "name": "diameter_mm_max", "in": "query", "required": false, "description": "Inclusive upper bound for `diameter_mm`.", "schema": { "type": "number" } }, { "name": "torque_nm_min", "in": "query", "required": false, "description": "Inclusive lower bound for `torque_nm`.", "schema": { "type": "number" } }, { "name": "torque_nm_max", "in": "query", "required": false, "description": "Inclusive upper bound for `torque_nm`.", "schema": { "type": "number" } }, { "name": "rpm_min", "in": "query", "required": false, "description": "Inclusive lower bound for `rpm`.", "schema": { "type": "number" } }, { "name": "rpm_max", "in": "query", "required": false, "description": "Inclusive upper bound for `rpm`.", "schema": { "type": "number" } }, { "name": "noise_db_min", "in": "query", "required": false, "description": "Inclusive lower bound for `noise_db`.", "schema": { "type": "number" } }, { "name": "noise_db_max", "in": "query", "required": false, "description": "Inclusive upper bound for `noise_db`.", "schema": { "type": "number" } }, { "name": "rated_voltage_v_min", "in": "query", "required": false, "description": "Inclusive lower bound for `rated_voltage_v` (rated voltage, V).", "schema": { "type": "number" } }, { "name": "rated_voltage_v_max", "in": "query", "required": false, "description": "Inclusive upper bound for `rated_voltage_v` (rated voltage, V).", "schema": { "type": "number" } }, { "name": "control_protocol", "in": "query", "required": false, "description": "Control protocol value(s); repeat or comma-separate. Matches products having at least one of them.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "rts", "io_homecontrol", "zigbee", "z_wave", "matter", "thread", "wifi", "ble", "rs485", "dry_contact", "knx", "proprietary_rf", "enocean", "smi", "dali", "modbus", "centronic", "loxone", "security_plus", "security_plus_2", "intellicode", "bisecur", "somloq2", "b_tronic", "elero_proline", "nice_era" ] } }, "style": "form", "explode": true }, { "name": "power_supply", "in": "query", "required": false, "description": "Power supply type(s); repeat or comma-separate. Matches products having at least one of them.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "ac", "dc", "battery", "solar", "poe", "usb" ] } }, "style": "form", "explode": true }, { "name": "application_types", "in": "query", "required": false, "description": "Application type(s) the product is sourced for (the attribute behind /applications/); repeat or comma-separate. Matches products having at least one of them.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "roller_shutter", "awning", "cassette_awning", "screen", "roller_blind", "venetian_blind", "external_venetian", "curtain", "insect_screen", "projection_screen", "skylight", "window", "louvre_roof", "lighting", "heating", "sectional_door", "rapid_door", "rolling_door", "garage_door", "up_and_over_door", "side_sliding_door", "swing_gate", "sliding_gate", "barrier", "other" ] } }, "style": "form", "explode": true }, { "name": "minSpecCompleteness", "in": "query", "required": false, "description": "Only products whose stored spec completeness snapshot is at least this value (0–1).", "schema": { "type": "number", "minimum": 0, "maximum": 1 } }, { "name": "series", "in": "query", "required": false, "description": "Series path `/` as in `/products/series//` (motobase-product-hierarchy-and-relations).", "schema": { "type": "string", "pattern": "^[a-z0-9\\\\p{L}-]{1,96}/[a-z0-9\\\\p{L}-]{1,128}$" } }, { "name": "lifecycle", "in": "query", "required": false, "description": "Materialized lifecycle status.", "schema": { "type": "string", "enum": [ "active", "discontinued", "replaced", "unknown" ] } }, { "name": "partNumber", "in": "query", "required": false, "description": "Exact match on the normalized part number or any alias (old and regional part numbers find the current model).", "schema": { "type": "string", "maxLength": 64 } } ], "responses": { "200": { "description": "A page of product summaries (24 per page).", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-Quota-Scope": { "$ref": "#/components/headers/QuotaScope" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/ProductSummary" }, { "type": "object", "properties": { "completeness": { "oneOf": [ { "$ref": "#/components/schemas/CompletenessSnapshot" }, { "type": "null" } ] } }, "required": [ "completeness" ] } ] } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } ] } } } }, "304": { "description": "Not modified (If-None-Match matched the current ETag)." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/products/{slug}": { "get": { "operationId": "getProduct", "summary": "One product with claim-sourced specs and publicly verifiable certifications.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Product identifier. Three forms are accepted and return the same `data`: (1) the product's `slug` from a previous response — the last segment of its canonical page URL, `-` (only the trailing publicId is authoritative; another readable part still resolves); (2) the bare `publicId`, in any letter case; (3) the legacy numeric record id — **deprecated**: it keeps resolving for the life of v1, but the response then carries the `Deprecation` and `Link` headers and `meta.deprecatedIdentifier: true`. The API never redirects (no 3xx). Do not guess identifiers.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}$" }, "examples": { "slug": { "summary": "Canonical segment (preferred)", "value": "somfy-sonesse-30-rts-k7q2m9x" }, "publicId": { "summary": "Bare publicId", "value": "k7q2m9x" } } } ], "responses": { "200": { "description": "The product.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-Quota-Scope": { "$ref": "#/components/headers/QuotaScope" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProductDetail" }, "meta": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeprecatedIdentifierMeta" } ] } } } ] } } } }, "304": { "description": "Not modified." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/companies": { "get": { "operationId": "listCompanies", "summary": "List/search published companies.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Full-text search, 1–200 characters.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } } ], "responses": { "200": { "description": "A page of companies (24 per page).", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-Quota-Scope": { "$ref": "#/components/headers/QuotaScope" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySummary" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } ] } } } }, "304": { "description": "Not modified (If-None-Match matched the current ETag)." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/companies/{slug}": { "get": { "operationId": "getCompany", "summary": "One company: claim-backed facts, ownership, product and certification counts.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Company identifier. Three forms are accepted and return the same `data`: (1) the company's `slug` from a previous response (its `companies.slug`, also the last segment of its canonical page URL); (2) a former slug of the company (legacy slug) — **deprecated**; (3) the legacy numeric record id — **deprecated**. Deprecated forms keep resolving for the life of v1; the response then carries the `Deprecation` and `Link` headers and `meta.deprecatedIdentifier: true`. The API never redirects (no 3xx). Do not guess identifiers.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}$" }, "examples": { "slug": { "summary": "Company slug", "value": "somfy" } } } ], "responses": { "200": { "description": "The company.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-Quota-Scope": { "$ref": "#/components/headers/QuotaScope" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CompanyDetail" }, "meta": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeprecatedIdentifierMeta" } ] } } } ] } } } }, "304": { "description": "Not modified." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/certifications": { "get": { "operationId": "listCertifications", "summary": "Publicly verifiable certifications on published products.", "parameters": [ { "name": "product", "in": "query", "required": false, "description": "Product identifier: `slug`, bare `publicId` (server switch `MOTOBASE_PUBLIC_URLS_ENABLED` on) or legacy numeric id (deprecated).", "schema": { "type": "string", "maxLength": 96, "pattern": "^[A-Za-z0-9-]+$" }, "examples": { "slug": { "value": "somfy-sonesse-30-rts-k7q2m9x" }, "publicId": { "value": "k7q2m9x" } } }, { "name": "company", "in": "query", "required": false, "description": "Manufacturer company `slug` (server switch `MOTOBASE_PUBLIC_URLS_ENABLED` on) or legacy numeric id (deprecated).", "schema": { "type": "string", "maxLength": 96, "pattern": "^[A-Za-z0-9-]+$" }, "examples": { "slug": { "value": "somfy" } } }, { "name": "standard", "in": "query", "required": false, "description": "Standard slug (as used by /standards/{slug}).", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 } } ], "responses": { "200": { "description": "A page of certifications, newest issue date first.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-Quota-Scope": { "$ref": "#/components/headers/QuotaScope" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Certification" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } ] } } } }, "304": { "description": "Not modified (If-None-Match matched the current ETag)." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/signals": { "get": { "operationId": "listSignals", "summary": "Human-reviewed industry news and compliance updates (same set and order as /signals).", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Signal type.", "schema": { "type": "string", "enum": [ "news", "compliance_update" ] } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 } } ], "responses": { "200": { "description": "A page of signals, most recent first.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-Quota-Scope": { "$ref": "#/components/headers/QuotaScope" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } ] } } } }, "304": { "description": "Not modified (If-None-Match matched the current ETag)." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/changes": { "get": { "operationId": "listChanges", "summary": "Incremental change feed over products, companies, certifications and signals.", "description": "Start without a cursor to walk the full current catalog, then keep the returned `meta.cursor` and call again to receive only records created, updated or withdrawn since. `created` means the record did not exist at the cursor position; treat `created` and `updated` alike as upserts. Events are ordered by (updatedAt, entity, id). `withdrawn` is emitted for products/companies that were public and no longer are; hard-deleted records and certification/signal withdrawals are not reported.", "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from a previous response's meta.cursor.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Rows scanned per page, 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "A page of change events.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeEvent" } }, "meta": { "$ref": "#/components/schemas/CursorMeta" } } } ] } } } }, "304": { "description": "Not modified." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/compare/brands": { "get": { "operationId": "compareBrands", "summary": "Qualifying manufacturer pairs (same set and order as /compare/brands), or one pair's full comparison with ?pair=.", "parameters": [ { "name": "pair", "in": "query", "required": false, "description": "A pair slug from a previous response (`a-vs-b`); either order is accepted.", "schema": { "type": "string", "pattern": "^[a-z0-9-]{3,200}$" } } ], "responses": { "200": { "description": "Without `pair`: every qualifying pair (data is an array of BrandPairSummary, meta is ListMeta). With `pair`: one BrandComparison (meta is null).", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-Quota-Scope": { "$ref": "#/components/headers/QuotaScope" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/BrandPairSummary" } }, { "$ref": "#/components/schemas/BrandComparison" } ] }, "meta": { "oneOf": [ { "$ref": "#/components/schemas/ListMeta" }, { "type": "null" } ] } } } ] } } } }, "304": { "description": "Not modified." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/compare/products": { "get": { "operationId": "compareProducts", "summary": "Side-by-side comparison of 2–6 products (same data as /compare and the model comparison pages).", "parameters": [ { "name": "ids", "in": "query", "required": true, "description": "Comma-separated product identifiers — `slug`s, bare `publicId`s (server switch `MOTOBASE_PUBLIC_URLS_ENABLED` on) and legacy numeric ids (deprecated) may be mixed. Invalid tokens and tokens naming the same product are dropped, the first 6 are used; at least 2 must be valid. Unresolvable tokens are echoed in `notFound`.", "schema": { "type": "string" }, "example": "somfy-sonesse-30-rts-k7q2m9x,p3d8f2a" } ], "responses": { "200": { "description": "The comparison.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-Quota-Scope": { "$ref": "#/components/headers/QuotaScope" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProductComparison" }, "meta": { "type": "null" } } } ] } } } }, "304": { "description": "Not modified." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/spec-templates": { "get": { "operationId": "listSpecTemplates", "summary": "The six spec-category parameter templates.", "parameters": [], "responses": { "200": { "description": "All templates (summary).", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-Quota-Scope": { "$ref": "#/components/headers/QuotaScope" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SpecTemplateSummary" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } ] } } } }, "304": { "description": "Not modified (If-None-Match matched the current ETag)." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/spec-templates/{specCategory}": { "get": { "operationId": "getSpecTemplate", "summary": "One spec-category parameter template (groups, rows, required, compare rules, tolerances).", "parameters": [ { "name": "specCategory", "in": "path", "required": true, "description": "One of tubular, curtain, venetian, window_opener, controller, accessory. Anything else is 404.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}$" } } ], "responses": { "200": { "description": "The template.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-Quota-Scope": { "$ref": "#/components/headers/QuotaScope" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SpecTemplate" }, "meta": { "type": "null" } } } ] } } } }, "304": { "description": "Not modified." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/series": { "get": { "operationId": "listSeries", "summary": "List published product series (motobase-product-hierarchy-and-relations).", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (default 24, max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 } }, { "name": "brand", "in": "query", "required": false, "description": "Brand slug.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "Category key of at least one member, e.g. tubular_motor.", "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" } } ], "responses": { "200": { "description": "A page of series.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-Quota-Scope": { "$ref": "#/components/headers/QuotaScope" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SeriesSummary" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } ] } } } }, "304": { "description": "Not modified (If-None-Match matched the current ETag)." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/series/{brand}/{series}": { "get": { "operationId": "getSeries", "summary": "One product series: members, variant-axis values, axis matrix and verified relations; same data as the series page and the MCP tool motobase_get_series.", "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Slug from a series URL `/products/series//`.", "schema": { "type": "string", "pattern": "^[a-z0-9\\\\p{L}-]{1,128}$" } }, { "name": "series", "in": "path", "required": true, "description": "Slug from a series URL `/products/series//`.", "schema": { "type": "string", "pattern": "^[a-z0-9\\\\p{L}-]{1,128}$" } } ], "responses": { "200": { "description": "The series.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-Quota-Scope": { "$ref": "#/components/headers/QuotaScope" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SeriesDetail" }, "meta": { "type": "null" } } } ] } } } }, "304": { "description": "Not modified." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/applications": { "get": { "operationId": "listApplications", "summary": "Published application (use-case) knowledge pages, in menu order.", "parameters": [ { "name": "category", "in": "query", "required": false, "description": "Category slug (e.g. tubular-motor).", "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 96 } } ], "responses": { "200": { "description": "All templates (summary).", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationSummary" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } ] } } } }, "304": { "description": "Not modified (If-None-Match matched the current ETag)." }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "description": "Each page opens with an essence bridge naming the product category that serves the use case. Optional `category` returns only pages that bridge to that category (for category pages). Unpublished drafts are never returned." } }, "/api/v1/applications/{slug}": { "get": { "operationId": "getApplication", "summary": "One application knowledge page with related categories (and their product-filter paths), standards, certification programs, sourced selection notes and references.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Application slug (roller-shutters, awnings, zip-screens, roller-blinds, curtains, venetian-blinds, window-openers, doors). Unknown or unpublished is 404.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}$" } } ], "responses": { "200": { "description": "The application page.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ApplicationDetail" }, "meta": { "type": "null" } } } ] } } } }, "304": { "description": "Not modified." }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/replacements": { "get": { "operationId": "findReplacements", "summary": "Replacement finder: resolve a motor model as typed on its label (e.g. `becker r8 17 c01`, `oximo rts 10/17`) and list replacement candidates by tier, with every matched value, difference, unchecked item and missing-data reason. Same data as the MCP tool motobase_find_replacement. Suggestions compare published specifications; they never state fit or compatibility. Quota: each request costs 3 units of the caller's quota (anonymous or API key), not 1 — a lookup runs the resolver, the candidate recall and the live checks. The MCP tool motobase_find_replacement costs the same 3 units per call. With the server switch MOTOBASE_PUBLIC_URLS_ENABLED on, the output carries no numeric record ids: product summaries have `id: null` and are identified by `slug` (canonical URL segment) and `publicId`; `unchecked[].productIds` and `target.series.id` are null (use `productKeys`, `series.brand.slug` + `series.slug`). Claim ids stay, as in GET /api/v1/products/{slug}.", "parameters": [ { "name": "model", "in": "query", "required": true, "description": "Model as printed on the motor (1–80 characters); brand name and words like 'replacement' may be included.", "schema": { "type": "string", "minLength": 1, "maxLength": 80 } }, { "name": "brand", "in": "query", "required": false, "description": "Brand slug to restrict the lookup to (e.g. `becker`); an unknown slug gives status not_found.", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,96}$" } }, { "name": "tiers", "in": "query", "required": false, "description": "Comma-separated tiers to return: a = manufacturer-stated replacement, b = same series, c = same brand (default a,b,c). Other brands (d) are not offered yet.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "a", "b", "c" ] } }, "style": "form", "explode": false }, { "name": "torque", "in": "query", "required": false, "description": "Rated torque in Nm from the motor label (0.5–300). Used only to complete or stand in for the target (a resolved product keeps its published values; a value read from the model name is replaced; with `brand`, torque, rpm and diameter an unknown model is compared on these values alone). Reported under `data.override`; values carry basis `user_override`.", "schema": { "type": "number", "minimum": 0.5, "maximum": 300 } }, { "name": "rpm", "in": "query", "required": false, "description": "Rated speed in rpm from the motor label (5–60).", "schema": { "type": "number", "minimum": 5, "maximum": 60 } }, { "name": "diameter", "in": "query", "required": false, "description": "Motor diameter class in mm.", "schema": { "type": "number", "enum": [ 22, 25, 28, 30, 35, 40, 45, 50, 58, 60 ] } }, { "name": "voltage", "in": "query", "required": false, "description": "Rated voltage: 12, 24, 100–127 or 208–240 V.", "schema": { "type": "number", "minimum": 12, "maximum": 240 } } ], "responses": { "200": { "description": "The resolution (resolved / resolved_edition / series_only / ambiguous / not_found) and, when a target exists, the replacement groups.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-Quota-Scope": { "$ref": "#/components/headers/QuotaScope" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReplacementResult" }, "meta": { "type": "null" } } } ] } } } }, "304": { "description": "Not modified." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/products/{slug}/replacements": { "get": { "operationId": "getProductReplacements", "summary": "Replacement candidates for one published product (no model resolution). Identifier rules as GET /api/v1/products/{slug}: the canonical segment, a bare publicId or the deprecated numeric id (with the switch on: `Deprecation`, `meta.deprecatedIdentifier: true` and `Link: <…/products/{canonical}/replacements>; rel=\"successor-version\"`). A withdrawn once-public product answers 410 `gone`; one merged into a live product answers 410 with that product's replacements URL in `Link` (rel=\"successor-version\") and in the message. Quota: each request costs 3 units of the caller's quota (anonymous or API key), not 1 — a lookup runs the resolver, the candidate recall and the live checks. The MCP tool motobase_find_replacement costs the same 3 units per call. With the server switch MOTOBASE_PUBLIC_URLS_ENABLED on, the output carries no numeric record ids: product summaries have `id: null` and are identified by `slug` (canonical URL segment) and `publicId`; `unchecked[].productIds` and `target.series.id` are null (use `productKeys`, `series.brand.slug` + `series.slug`). Claim ids stay, as in GET /api/v1/products/{slug}.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Product key: `publicId` (preferred), the last segment of its canonical `url`, or the deprecated numeric `slug`.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}$" } }, { "name": "tiers", "in": "query", "required": false, "description": "Comma-separated tiers to return: a = manufacturer-stated replacement, b = same series, c = same brand (default a,b,c). Other brands (d) are not offered yet.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "a", "b", "c" ] } }, "style": "form", "explode": false }, { "name": "torque", "in": "query", "required": false, "description": "Rated torque in Nm from the motor label (0.5–300). Used only to complete or stand in for the target (a resolved product keeps its published values; a value read from the model name is replaced; with `brand`, torque, rpm and diameter an unknown model is compared on these values alone). Reported under `data.override`; values carry basis `user_override`.", "schema": { "type": "number", "minimum": 0.5, "maximum": 300 } }, { "name": "rpm", "in": "query", "required": false, "description": "Rated speed in rpm from the motor label (5–60).", "schema": { "type": "number", "minimum": 5, "maximum": 60 } }, { "name": "diameter", "in": "query", "required": false, "description": "Motor diameter class in mm.", "schema": { "type": "number", "enum": [ 22, 25, 28, 30, 35, 40, 45, 50, 58, 60 ] } }, { "name": "voltage", "in": "query", "required": false, "description": "Rated voltage: 12, 24, 100–127 or 208–240 V.", "schema": { "type": "number", "minimum": 12, "maximum": 240 } } ], "responses": { "200": { "description": "Replacement groups for the product; 404 when the product is not publicly visible.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-Quota-Scope": { "$ref": "#/components/headers/QuotaScope" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReplacementResult" }, "meta": { "type": "null" } } } ] } } } }, "304": { "description": "Not modified." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/events": { "get": { "operationId": "listEvents", "summary": "Reviewed industry events (trade shows, conferences, standards meetings): editions with dates, venue and organisers. Default: not yet finished, soonest first.", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Event type.", "schema": { "type": "string", "enum": [ "trade_show", "conference", "product_launch_event", "training_webinar", "standards_meeting", "other" ] } }, { "name": "country", "in": "query", "required": false, "description": "ISO 3166-1 alpha-2 country of the venue (case-insensitive).", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" } }, { "name": "region", "in": "query", "required": false, "description": "Region derived from the venue country.", "schema": { "type": "string", "enum": [ "europe", "china", "asia_pacific", "middle_east_africa", "north_america", "latin_america", "cis" ] } }, { "name": "month", "in": "query", "required": false, "description": "Editions running (at least partly) in this month, YYYY-MM.", "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" } }, { "name": "when", "in": "query", "required": false, "description": "upcoming (default: not finished, soonest first), past (most recent first) or all.", "schema": { "type": "string", "enum": [ "upcoming", "past", "all" ], "default": "upcoming" } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 } } ], "responses": { "200": { "description": "A page of events.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-Quota-Scope": { "$ref": "#/components/headers/QuotaScope" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } ] } } } }, "304": { "description": "Not modified (If-None-Match matched the current ETag)." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/events/{slug}": { "get": { "operationId": "getEvent", "summary": "One event edition with the tracked companies attending (public, reviewed participations only; never the full exhibitor list).", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Edition identifier: the `slug` from a previous response (e.g. `r-t-stuttgart-2027`). Do not guess identifiers.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}$" }, "examples": { "slug": { "summary": "Edition slug", "value": "r-t-stuttgart-2027" } } } ], "responses": { "200": { "description": "The event edition.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-Quota-Scope": { "$ref": "#/components/headers/QuotaScope" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EventDetail" } } } ] } } } }, "304": { "description": "Not modified." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "schemas": { "SuccessEnvelope": { "type": "object", "properties": { "ok": { "const": true }, "data": {}, "error": { "type": "null" }, "meta": {} }, "required": [ "ok", "data", "error", "meta" ] }, "ErrorEnvelope": { "type": "object", "properties": { "ok": { "const": false }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "invalid_cursor", "invalid_api_key", "not_found", "gone", "rate_limited", "internal_error" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "meta": { "type": "null" } }, "required": [ "ok", "data", "error", "meta" ] }, "ListMeta": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } }, "required": [ "total", "page", "limit" ] }, "CursorMeta": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ] }, "Source": { "type": [ "object", "null" ], "properties": { "title": { "type": [ "string", "null" ] }, "kind": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "retrievedAt": { "type": [ "string", "null" ] }, "legalBasis": { "type": [ "string", "null" ] } }, "required": [ "title", "kind", "url", "retrievedAt", "legalBasis" ] }, "Evidence": { "type": "object", "description": "Provenance of a claim-backed value.", "properties": { "claimId": { "type": [ "string", "integer", "null" ] }, "source": { "$ref": "#/components/schemas/Source" }, "observedAt": { "type": "string" }, "assertionType": { "type": [ "string", "null" ] }, "evidenceStrength": { "type": "string" }, "confidence": { "type": "string" }, "sourceExcerpt": { "type": "string", "description": "Present only when the excerpt passed this service's public review gate." } }, "required": [ "claimId", "source", "observedAt", "assertionType", "evidenceStrength", "confidence" ] }, "Links": { "type": "object", "properties": { "page": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" } }, "required": [ "page", "api" ], "description": "`page`: the record's public page; `api`: its API v1 detail URL. With the server switch `MOTOBASE_PUBLIC_URLS_ENABLED` on both use the canonical identifier." }, "EntityRef": { "type": "object", "properties": { "slug": { "type": "string", "description": "Identifier of the referenced product or company, in the same form as ProductSummary.slug / CompanySummary.slug (canonical identifier with the server switch `MOTOBASE_PUBLIC_URLS_ENABLED` on; numeric only while that record is not backfilled)." }, "name": { "type": "string" } }, "required": [ "slug", "name" ] }, "ProductSummary": { "type": "object", "properties": { "slug": { "type": "string", "description": "With the server switch `MOTOBASE_PUBLIC_URLS_ENABLED` on: the canonical identifier — the last segment of the canonical page URL, `-` (e.g. `somfy-sonesse-30-rts-k7q2m9x`); pass it to GET /api/v1/products/{slug}. A record whose publicId is not backfilled yet keeps its numeric id (its page URL is still numeric). Switch off: the legacy numeric record id (deprecated as an input)." }, "name": { "type": "string" }, "series": { "oneOf": [ { "$ref": "#/components/schemas/SeriesRef" }, { "type": "null" } ], "description": "The published series entity, or null when the product is not in a published series." }, "manufacturer": { "oneOf": [ { "$ref": "#/components/schemas/CompanyRef" }, { "type": "null" } ] }, "category": { "type": [ "string", "null" ] }, "categoryDisplayName": { "type": [ "string", "null" ] }, "activeCertificationCount": { "type": "integer" }, "links": { "$ref": "#/components/schemas/Links" }, "publicId": { "type": [ "string", "null" ], "description": "The product's random public key (7 characters, unambiguous alphabet; stored uppercase, accepted in any case), e.g. `K7Q2M9X`. Accepted by GET /api/v1/products/{slug}. `null` until the record is backfilled." }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "Absolute canonical page URL `/products/-` (only the trailing publicId is authoritative). `null` until `publicId` is backfilled, and always null while the server switch `MOTOBASE_PUBLIC_URLS_ENABLED` is off. With the switch on `links.page` is the same canonical URL." }, "displayName": { "type": "string", "description": "Canonical display name (the public page H1). Presentation only — never use it as an id, slug or filter value; `name` keeps the original value." } }, "required": [ "slug", "name", "series", "manufacturer", "category", "categoryDisplayName", "activeCertificationCount", "links", "publicId", "url", "displayName" ] }, "ProductDetail": { "allOf": [ { "$ref": "#/components/schemas/ProductSummary" }, { "type": "object", "properties": { "categorySource": { "type": "string" }, "applications": { "type": "array", "items": { "type": "string" } }, "technologies": { "type": "array", "items": { "type": "string" } }, "identifiers": { "type": "object", "properties": { "productLabel": { "type": [ "string", "null" ] }, "partNumber": { "type": [ "string", "null" ] }, "vidPid": { "type": [ "string", "null" ] } } }, "externalLinks": { "type": "object", "properties": { "productUrl": { "type": [ "string", "null" ] }, "supportUrl": { "type": [ "string", "null" ] }, "userManualUrl": { "type": [ "string", "null" ] } } }, "image": { "type": [ "object", "null" ], "properties": { "url": { "type": "string" }, "alt": { "type": "string" } } }, "specs": { "type": "array", "items": { "$ref": "#/components/schemas/Spec" } }, "certifications": { "type": "array", "items": { "$ref": "#/components/schemas/Certification" } }, "competitors": { "type": "array", "items": { "$ref": "#/components/schemas/EntityRef" } }, "assets": { "type": "array", "items": { "$ref": "#/components/schemas/DossierAsset" } }, "summary": { "$ref": "#/components/schemas/DossierSummary" }, "specTable": { "$ref": "#/components/schemas/SpecTable" }, "completeness": { "oneOf": [ { "$ref": "#/components/schemas/Completeness" }, { "type": "null" } ] }, "brand": { "oneOf": [ { "$ref": "#/components/schemas/BrandRef" }, { "type": "null" } ] }, "standalone": { "type": "boolean" }, "lifecycle": { "oneOf": [ { "$ref": "#/components/schemas/Lifecycle" }, { "type": "null" } ] }, "relations": { "type": "array", "items": { "$ref": "#/components/schemas/Relation" } }, "partNumberAliases": { "type": "array", "items": { "$ref": "#/components/schemas/PartNumberAlias" } }, "certificationLevels": { "type": "array", "items": { "$ref": "#/components/schemas/CertificationLevel" } } }, "required": [ "specs", "certifications", "specTable", "completeness", "brand", "standalone", "lifecycle", "relations", "partNumberAliases", "certificationLevels" ] } ] }, "Spec": { "type": "object", "properties": { "property": { "type": "string" }, "displayName": { "type": "string" }, "valueType": { "type": "string" }, "value": {}, "unit": { "type": [ "string", "null" ] }, "evidence": { "$ref": "#/components/schemas/Evidence" } }, "required": [ "property", "displayName", "valueType", "value", "unit", "evidence" ] }, "Certification": { "type": "object", "properties": { "id": { "type": [ "string", "integer" ] }, "product": { "oneOf": [ { "$ref": "#/components/schemas/EntityRef" }, { "type": "null" } ] }, "certBody": { "type": "string" }, "certNumber": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] }, "issuedAt": { "type": [ "string", "null" ] }, "standardCode": { "type": [ "string", "null" ] }, "certificationType": { "type": [ "string", "null" ] }, "softwareVersion": { "type": [ "string", "null" ] }, "transport": { "type": "array", "items": { "type": "string" } }, "specificationVersion": { "type": [ "string", "null" ] }, "holderName": { "type": [ "string", "null" ] }, "targetMarket": { "type": [ "string", "null" ] }, "registry": { "type": "string" }, "verifyUrl": { "type": [ "string", "null" ] }, "evidence": { "$ref": "#/components/schemas/Evidence" } }, "required": [ "id", "product", "certBody", "certNumber", "status", "issuedAt", "standardCode", "transport", "holderName", "registry", "verifyUrl", "evidence" ] }, "CompanySummary": { "type": "object", "properties": { "slug": { "type": "string", "description": "With the server switch `MOTOBASE_PUBLIC_URLS_ENABLED` on: the canonical identifier — the company slug (`companies.slug`, e.g. `somfy`); pass it to GET /api/v1/companies/{slug}. A company whose slug is not backfilled yet keeps its numeric id. Switch off: the legacy numeric record id (deprecated as an input)." }, "name": { "type": "string" }, "links": { "$ref": "#/components/schemas/Links" }, "publicId": { "type": [ "string", "null" ], "description": "The company's public key: its URL slug (lowercase ASCII words joined by dashes, never all digits). Accepted by GET /api/v1/companies/{slug}. `null` until the record is backfilled." }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "Absolute canonical page URL `/companies/`. `null` until the slug is backfilled, and always null while the server switch `MOTOBASE_PUBLIC_URLS_ENABLED` is off. With the switch on `links.page` is the same canonical URL." } }, "required": [ "slug", "name", "links", "publicId", "url" ] }, "CompanyDetail": { "allOf": [ { "$ref": "#/components/schemas/CompanySummary" }, { "type": "object", "properties": { "aliases": { "type": "array", "items": { "type": "string" } }, "legalEntities": { "type": "array", "description": "All legal entities of the company (hq, subsidiary, business unit, ...), each with its own source when it carries one. Empty array when none.", "items": { "$ref": "#/components/schemas/CompanyLegalEntity" } }, "facts": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyFact" } }, "ownership": { "type": "object", "properties": { "parents": { "type": "array", "items": { "$ref": "#/components/schemas/EntityRef" } }, "parentPercentage": { "type": [ "object", "null" ], "properties": { "value": { "type": "number" }, "evidence": { "$ref": "#/components/schemas/Evidence" } } }, "subsidiaries": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/EntityRef" }, { "type": "object", "properties": { "percentage": { "type": [ "object", "null" ], "properties": { "value": { "type": "number" }, "evidence": { "$ref": "#/components/schemas/Evidence" } } } } } ] } } } }, "publishedProductCount": { "type": "integer" }, "activeCertificationCount": { "type": "integer" }, "profile": { "$ref": "#/components/schemas/CompanyProfile" }, "relations": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyRelation" } } }, "required": [ "aliases", "legalEntities", "facts", "ownership", "publishedProductCount", "activeCertificationCount", "profile", "relations" ] } ] }, "CompanyLegalEntity": { "type": "object", "properties": { "legalName": { "type": "string" }, "jurisdiction": { "type": [ "string", "null" ] }, "role": { "type": [ "string", "null" ], "enum": [ "hq", "factory", "sales", "domestic_brand", "subsidiary", "business_unit", null ] }, "sourceUrl": { "type": [ "string", "null" ], "format": "uri" }, "verifiedAt": { "type": [ "string", "null" ] } }, "required": [ "legalName", "jurisdiction", "role", "sourceUrl", "verifiedAt" ] }, "CompanyFact": { "type": "object", "description": "A claim-backed company fact. Structural fields without a claim are never emitted.", "properties": { "property": { "type": "string" }, "displayName": { "type": "string" }, "value": {}, "unit": { "type": [ "string", "null" ] }, "relatedCompany": { "oneOf": [ { "$ref": "#/components/schemas/EntityRef" }, { "type": "null" } ] }, "evidence": { "$ref": "#/components/schemas/Evidence" } }, "required": [ "property", "displayName", "value", "unit", "relatedCompany", "evidence" ] }, "CompanyProfile": { "type": "object", "description": "Company profile entries. Only entries carrying their own sourceUrl are emitted; mainCategories is the catalog's own classification.", "properties": { "summary": { "type": [ "object", "null" ], "properties": { "text": { "type": "string" }, "sourceUrls": { "type": "array", "items": { "type": "string" } }, "writtenAt": { "type": [ "string", "null" ] } }, "required": [ "text", "sourceUrls", "writtenAt" ] }, "mainCategories": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ] } }, "registrationIds": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "lei", "national_register", "vat", "eori", "duns", "weee", "wikidata_qid", "other" ] }, "value": { "type": "string" }, "legalName": { "type": [ "string", "null" ] }, "jurisdiction": { "type": [ "string", "null" ] }, "issuer": { "type": [ "string", "null" ] }, "sourceUrl": { "type": "string" }, "verifiedAt": { "type": [ "string", "null" ] } }, "required": [ "type", "value", "legalName", "jurisdiction", "issuer", "sourceUrl", "verifiedAt" ] } }, "headquartersAddress": { "type": [ "object", "null" ], "properties": { "addressLines": { "type": [ "string", "null" ] }, "postalCode": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2" }, "sourceUrl": { "type": "string" }, "verifiedAt": { "type": [ "string", "null" ] } }, "required": [ "addressLines", "postalCode", "city", "region", "country", "sourceUrl", "verifiedAt" ] }, "tradeFairAppearances": { "type": "array", "items": { "type": "object", "properties": { "fair": { "type": "string" }, "year": { "type": [ "integer", "null" ] }, "booth": { "type": [ "string", "null" ] }, "sourceUrl": { "type": "string" } }, "required": [ "fair", "year", "booth", "sourceUrl" ] } }, "contactChannels": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "email", "phone", "fax", "contact_page" ] }, "value": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "sourceUrl": { "type": "string" } }, "required": [ "kind", "value", "label", "sourceUrl" ] } }, "socialLinks": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "linkedin", "youtube", "x", "facebook", "instagram", "wechat", "bilibili", "douyin", "xiaohongshu", "other" ] }, "url": { "type": "string" }, "sourceUrl": { "type": "string" } }, "required": [ "platform", "url", "sourceUrl" ] } } }, "required": [ "summary", "mainCategories", "registrationIds", "headquartersAddress", "tradeFairAppearances", "contactChannels", "socialLinks" ] }, "Signal": { "type": "object", "properties": { "id": { "type": [ "string", "integer" ] }, "type": { "type": "string", "enum": [ "news", "compliance_update" ] }, "headline": { "type": [ "string", "null" ] }, "summary": { "type": "string" }, "detectedAt": { "type": "string" }, "sourceUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "headline", "summary", "detectedAt", "sourceUrl" ] }, "ChangeEvent": { "type": "object", "properties": { "entity": { "type": "string", "enum": [ "product", "company", "certification", "signal" ] }, "slug": { "type": "string", "description": "Record identifier. With the server switch `MOTOBASE_PUBLIC_URLS_ENABLED` on, products and companies use the canonical identifier (withdrawn products: the lowercase publicId); certifications and signals keep their record id." }, "action": { "type": "string", "enum": [ "created", "updated", "withdrawn" ] }, "updatedAt": { "type": "string" }, "title": { "type": "string", "description": "Absent for withdrawn events." }, "links": { "$ref": "#/components/schemas/Links" } }, "required": [ "entity", "slug", "action", "updatedAt" ] }, "DossierAsset": { "type": "object", "description": "A document, image or page in the product dossier. Only metadata and URLs are returned; content is never proxied. `hostedUrl` is non-null only for assets this service is licensed to host (licenseClass hostable_*); reference_only assets link to their source.", "properties": { "kind": { "type": "string", "enum": [ "image", "datasheet_pdf", "manual_pdf", "brochure", "drawing", "video", "press_release", "product_page", "support_page", "registry_record" ] }, "title": { "type": "string" }, "sourceUrl": { "type": "string" }, "foundOnUrl": { "type": [ "string", "null" ] }, "hostedUrl": { "type": [ "string", "null" ] }, "sourceChannel": { "type": "string", "enum": [ "manufacturer_site", "fcc_exhibit", "dcl", "distributor", "press_kit", "vendor_portal", "association", "patent" ] }, "sourceName": { "type": "string" }, "licenseClass": { "type": "string", "enum": [ "hostable_public_record", "hostable_licensed", "reference_only" ] }, "fetchedAt": { "type": "string" }, "linkStatus": { "type": "string", "enum": [ "ok", "unverified" ] } }, "required": [ "kind", "title", "sourceUrl", "hostedUrl", "sourceChannel", "sourceName", "licenseClass", "fetchedAt", "linkStatus" ] }, "DossierSummary": { "type": [ "object", "null" ], "description": "This service's own English summary of the product, composed only from the listed sourced facts.", "properties": { "text": { "type": "string" }, "composer": { "type": "string", "enum": [ "template", "ai" ] }, "composerVersion": { "type": "string" }, "generatedAt": { "type": "string" }, "facts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "text": { "type": "string" }, "sourceLabel": { "type": "string" } } } } } }, "BrandCompany": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "productCount": { "type": "integer" } }, "required": [ "slug", "name", "productCount" ] }, "BrandPairSummary": { "type": "object", "description": "A qualifying manufacturer pair (both have at least 5 published models).", "properties": { "slug": { "type": "string", "description": "Pair slug `a-vs-b` (alphabetical)." }, "companies": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "$ref": "#/components/schemas/BrandCompany" } }, "links": { "type": "object", "properties": { "page": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" } }, "required": [ "page", "api" ] } }, "required": [ "slug", "companies", "links" ] }, "CountRow": { "type": "object", "description": "A derived count per label for each company (no per-row source; counts are over records that each carry their own evidence).", "properties": { "label": { "type": "string" }, "counts": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "integer" } } }, "required": [ "label", "counts" ] }, "CompanyFactValue": { "type": "object", "properties": { "value": { "type": "string" }, "source": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "retrievedAt": { "type": [ "string", "null" ] } }, "required": [ "title", "url", "retrievedAt" ] }, "observedAt": { "type": "string" } }, "required": [ "value", "source", "observedAt" ] }, "RangeEndpoint": { "type": "object", "description": "One end of a range: exactly the value of one verified claim.", "properties": { "value": { "type": "number" }, "unit": { "type": [ "string", "null" ] }, "product": { "$ref": "#/components/schemas/ProductRef" }, "evidence": { "$ref": "#/components/schemas/Evidence" } }, "required": [ "value", "unit", "product", "evidence" ] }, "SpecRange": { "type": "object", "properties": { "count": { "type": "integer", "description": "Models of this company with a value." }, "total": { "type": "integer", "description": "Published models of this company." }, "min": { "$ref": "#/components/schemas/RangeEndpoint" }, "max": { "$ref": "#/components/schemas/RangeEndpoint" } }, "required": [ "count", "total", "min", "max" ] }, "BrandComparison": { "type": "object", "description": "Same data as the /compare/brands/{a}-vs-{b} page.", "properties": { "pair": { "$ref": "#/components/schemas/BrandPairSummary" }, "columns": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "object", "properties": { "company": { "$ref": "#/components/schemas/BrandCompany" }, "seriesCount": { "type": "integer" }, "activeCertificationCount": { "type": "integer" }, "facts": { "type": "object", "properties": { "hqCountry": { "oneOf": [ { "$ref": "#/components/schemas/CompanyFactValue" }, { "type": "null" } ] }, "legalName": { "oneOf": [ { "$ref": "#/components/schemas/CompanyFactValue" }, { "type": "null" } ] }, "website": { "oneOf": [ { "$ref": "#/components/schemas/CompanyFactValue" }, { "type": "null" } ] } }, "required": [ "hqCountry", "legalName", "website" ] } }, "required": [ "company", "seriesCount", "activeCertificationCount", "facts" ] } }, "coverage": { "type": "array", "items": { "$ref": "#/components/schemas/CountRow" } }, "ranges": { "type": "array", "items": { "type": "object", "properties": { "property": { "type": "string" }, "displayName": { "type": "string" }, "cells": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "oneOf": [ { "$ref": "#/components/schemas/SpecRange" }, { "type": "null" } ] } } }, "required": [ "property", "displayName", "cells" ] } }, "protocols": { "type": "array", "items": { "$ref": "#/components/schemas/CountRow" } }, "certifications": { "type": "array", "items": { "$ref": "#/components/schemas/CountRow" } }, "closestModels": { "type": "array", "items": { "type": "object", "properties": { "products": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "$ref": "#/components/schemas/ProductRef" } }, "page": { "type": "string", "format": "uri" } }, "required": [ "products", "page" ] } } }, "required": [ "pair", "columns", "coverage", "ranges", "protocols", "certifications", "closestModels" ] }, "ProductComparison": { "type": "object", "description": "Same shape as the motobase_compare_products MCP tool result, plus the indexable page link.", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductRef" } }, "baseline": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "displayName": { "type": "string" }, "values": { "type": "array", "items": { "type": [ "string", "null" ] } } }, "required": [ "key", "displayName", "values" ] } }, "specs": { "type": "array", "items": { "type": "object", "properties": { "property": { "type": "string" }, "displayName": { "type": "string" }, "group": { "type": [ "string", "null" ] }, "isDifferent": { "type": "boolean", "description": "Rule-based: tolerance, qualifier and set rules; not-published / unchecked cells never participate." }, "values": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/Spec" }, { "type": "null" } ] } }, "allValues": { "type": "array", "items": { "type": "array", "items": { "$ref": "#/components/schemas/Spec" } } }, "specGroup": { "type": "string", "description": "v2 spec group (12-group order); `group` keeps the legacy three-group value." }, "compareRule": { "type": "string" }, "states": { "type": "array", "items": { "type": "string", "enum": [ "value", "standard", "optional", "none", "not_published", "not_applicable", "unknown" ] } }, "differentBasis": { "type": "array", "items": { "type": "boolean" } }, "best": { "type": "array", "items": { "type": "boolean" } } }, "required": [ "property", "displayName", "group", "isDifferent", "values", "allValues", "specGroup", "compareRule", "states", "differentBasis", "best" ] } }, "notFound": { "type": "array", "items": { "type": "string" } }, "recommended": { "type": "boolean", "description": "True when exactly two products resolve and they form a recommended (indexable) pair." }, "canonicalPage": { "type": [ "string", "null" ], "format": "uri", "description": "The model comparison page when exactly two products resolve." }, "templateAlignment": { "type": "string", "enum": [ "same_template", "shared_rows_only", "no_template" ] }, "seriesGroup": { "type": [ "object", "null" ], "description": "\"Series & variant axes\" row group when ≥2 compared products share a published series.", "properties": { "series": { "type": "array", "items": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" } } } }, "axes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "isDifferent": { "type": "boolean" }, "values": { "type": "array", "items": { "type": [ "object", "null" ], "properties": { "values": { "type": "array", "items": { "type": "string" } }, "fromModelName": { "type": "boolean" }, "claimIds": { "type": "array", "items": { "type": "string" } } } } } } } }, "viewAll": { "type": [ "object", "null" ], "properties": { "url": { "type": "string" }, "memberCount": { "type": "integer" } } } } } }, "required": [ "products", "baseline", "specs", "notFound", "recommended", "canonicalPage", "templateAlignment" ] }, "CompletenessSnapshot": { "type": "object", "description": "Stored completeness snapshot (recomputed on claim writes and daily); null until first computed. motobase-category-spec-templates D7.", "properties": { "specCategory": { "type": [ "string", "null" ] }, "specCompleteness": { "type": [ "number", "null" ], "description": "Filled required rows ÷ applicable required rows (0–1)." }, "auditCoverage": { "type": [ "number", "null" ] }, "assetCompleteness": { "type": [ "number", "null" ] }, "templateVersion": { "type": [ "string", "null" ] }, "computedAt": { "type": [ "string", "null" ] } }, "required": [ "specCategory", "specCompleteness", "auditCoverage", "assetCompleteness", "templateVersion", "computedAt" ] }, "Completeness": { "type": "object", "description": "Live completeness of the product's spec template (motobase-category-spec-templates D6).", "properties": { "specCompleteness": { "type": [ "number", "null" ] }, "auditCoverage": { "type": [ "number", "null" ] }, "assetCompleteness": { "type": [ "number", "null" ], "description": "Share of the four raw-archive classes (photo, drawing, datasheet, manual); null when the raw archive is not connected." }, "templateVersion": { "type": [ "string", "null" ] }, "missingRequired": { "type": "array", "items": { "type": "string" } } }, "required": [ "specCompleteness", "auditCoverage", "assetCompleteness", "templateVersion", "missingRequired" ] }, "SpecTableValue": { "type": "object", "properties": { "value": {}, "valueLabel": { "type": "string" }, "unit": { "type": [ "string", "null" ], "description": "Display unit." }, "qualifier": { "type": "string", "enum": [ "eq", "approx", "max", "min", "gt", "lt", "typ" ] }, "measurementNote": { "type": [ "string", "null" ] }, "availability": { "type": "string", "enum": [ "standard", "optional", "none" ] }, "optionPartNumbers": { "type": "array", "items": { "type": "string" } }, "evidence": { "$ref": "#/components/schemas/Evidence" } }, "required": [ "value", "valueLabel", "unit", "qualifier", "measurementNote", "availability", "optionPartNumbers", "evidence" ] }, "SpecTable": { "type": "object", "description": "Template-ordered spec table. Rows that are not applicable or not yet checked are omitted; `not_published` = checked, the manufacturer does not publish it; `none` = the manufacturer states the feature is absent. A final group `other` holds keys outside the product's template.", "properties": { "specCategory": { "type": [ "string", "null" ] }, "templateVersion": { "type": [ "string", "null" ] }, "groups": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string" }, "label": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "state": { "type": "string", "enum": [ "value", "standard", "optional", "none", "not_published" ] }, "required": { "type": "boolean" }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/SpecTableValue" } } }, "required": [ "key", "label", "state", "required", "values" ] } } }, "required": [ "group", "label", "rows" ] } } }, "required": [ "specCategory", "templateVersion", "groups" ] }, "SpecTemplateSummary": { "type": "object", "properties": { "specCategory": { "type": "string" }, "templateVersion": { "type": "string" }, "revision": { "type": "integer" }, "rowCount": { "type": "integer" }, "requiredCount": { "type": "integer" }, "links": { "type": "object", "properties": { "api": { "type": "string", "format": "uri" } }, "required": [ "api" ] } }, "required": [ "specCategory", "templateVersion", "revision", "rowCount", "requiredCount", "links" ] }, "SpecTemplate": { "type": "object", "properties": { "specCategory": { "type": "string" }, "templateVersion": { "type": "string" }, "revision": { "type": "integer" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string" }, "label": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "unit": { "type": [ "string", "null" ] }, "displayUnit": { "type": [ "string", "null" ] }, "valueType": { "type": "string" }, "multiValued": { "type": "boolean" }, "applicability": { "type": "string", "enum": [ "core", "extended" ] }, "required": { "type": "boolean" }, "comparable": { "type": "boolean" }, "compareRule": { "type": "string" }, "tolerance": { "type": [ "object", "null" ] }, "applicableWhen": { "type": [ "object", "null" ] } }, "required": [ "key", "label", "unit", "displayUnit", "valueType", "multiValued", "applicability", "required", "comparable", "compareRule", "tolerance", "applicableWhen" ] } } }, "required": [ "group", "label", "rows" ] } } }, "required": [ "specCategory", "templateVersion", "revision", "groups" ] }, "BrandRef": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ] }, "SeriesRef": { "type": "object", "description": "A published product series (motobase-product-hierarchy-and-relations).", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "brand": { "$ref": "#/components/schemas/BrandRef" }, "url": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" } }, "required": [ "slug", "name", "brand", "url", "api" ] }, "Lifecycle": { "type": "object", "description": "Materialized lifecycle. `active` only means listed in the vendor's current catalog; a vanished vendor page is `unknown`, never `discontinued`.", "properties": { "status": { "type": "string", "enum": [ "active", "discontinued", "replaced", "unknown" ] }, "since": { "type": [ "string", "null" ] }, "sinceBasis": { "type": [ "string", "null" ], "enum": [ "stated", "first_observed", null ] }, "basis": { "type": [ "string", "null" ] } }, "required": [ "status", "since", "sinceBasis", "basis" ] }, "Relation": { "type": "object", "description": "A relation whose evidence was re-checked on this request (fail closed).", "properties": { "type": { "type": "string", "enum": [ "successor_of", "replaced_by", "variant_of", "requires_accessory", "compatible_with", "white_label_of", "regional_edition_of" ] }, "direction": { "type": "string", "enum": [ "outgoing", "incoming" ] }, "label": { "type": "string" }, "other": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "product", "series", "part" ] }, "slug": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "partNumber": { "type": [ "string", "null" ] }, "brand": { "oneOf": [ { "$ref": "#/components/schemas/BrandRef" }, { "type": "null" } ] }, "url": { "type": [ "string", "null" ] } }, "required": [ "kind", "slug", "name", "partNumber", "brand", "url" ] }, "requiredChanges": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "crown", "drive", "bracket", "adapter", "controller", "wiring", "other" ] }, "text": { "type": "string" }, "partNumber": { "type": [ "string", "null" ] } } } }, "regions": { "type": "array", "items": { "type": "string" } }, "evidence": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "claim", "certification_match", "human_review" ] }, "claimId": { "type": [ "string", "null" ] }, "source": { "oneOf": [ { "$ref": "#/components/schemas/Evidence" }, { "type": "null" } ] }, "certificationIds": { "type": "array", "items": { "type": "string" } }, "matchedIdentifier": { "type": [ "string", "null" ] }, "identifierValue": { "type": [ "string", "null" ] }, "verifiedAt": { "type": [ "string", "null" ] } }, "required": [ "kind", "claimId", "source", "certificationIds", "matchedIdentifier", "identifierValue", "verifiedAt" ] } }, "required": [ "type", "direction", "label", "other", "requiredChanges", "regions", "evidence" ] }, "PartNumberAlias": { "type": "object", "properties": { "value": { "type": "string" }, "normalized": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "as_published", "superseded", "successor", "regional", "base_code", "vendor_alt" ] } }, "required": [ "value", "normalized", "kind" ] }, "AxisValue": { "type": "object", "properties": { "axisKey": { "type": "string" }, "state": { "type": "string", "enum": [ "value", "unknown" ] }, "fromModelName": { "type": "boolean" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "display": { "type": "string" }, "claimId": { "type": [ "string", "null" ] } } } } }, "required": [ "axisKey", "state", "fromModelName", "values" ] }, "SeriesSummary": { "allOf": [ { "$ref": "#/components/schemas/SeriesRef" }, { "type": "object", "properties": { "memberCount": { "type": "integer" }, "status": { "type": "string", "enum": [ "current", "legacy", "unknown" ] }, "indexable": { "type": "boolean" } }, "required": [ "memberCount", "status", "indexable" ] } ] }, "SeriesDetail": { "allOf": [ { "$ref": "#/components/schemas/SeriesSummary" }, { "type": "object", "properties": { "generation": { "type": [ "string", "null" ] }, "catalogComplete": { "type": "boolean" }, "variantAxes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "source": { "type": "string" } } } }, "facts": { "type": "array", "items": { "type": "object", "properties": { "property": { "type": "string" }, "displayName": { "type": "string" }, "value": { "type": "number" }, "evidence": { "$ref": "#/components/schemas/Evidence" } } } }, "members": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "partNumber": { "type": [ "string", "null" ] }, "variant": { "type": "string" }, "lifecycle": { "oneOf": [ { "$ref": "#/components/schemas/Lifecycle" }, { "type": "null" } ] }, "axisValues": { "type": "array", "items": { "$ref": "#/components/schemas/AxisValue" } }, "relations": { "type": "array", "items": { "$ref": "#/components/schemas/Relation" } }, "displayName": { "type": "string", "description": "Canonical display name (the public page H1). Presentation only — never use it as an id, slug or filter value; `name` keeps the original value." } }, "required": [ "displayName" ] } }, "pivot": { "oneOf": [ { "type": "object", "properties": { "rowAxis": { "type": "string" }, "columnAxis": { "type": "string" }, "rowValues": { "type": "array", "items": { "type": "string" } }, "columnValues": { "type": "array", "items": { "type": "string" } }, "cells": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "members": { "type": "array", "items": { "type": "string" } }, "emptyLabel": { "type": [ "string", "null" ] } } } } } } }, { "type": "null" } ] } }, "required": [ "generation", "catalogComplete", "variantAxes", "facts", "members", "pivot" ] } ] }, "CertificationLevelEvidence": { "description": "Evidence behind a certification verification level: an active, publicly visible registry record, or a vendor-stated mark (certification_marks claim).", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "registry_record" }, "certificationId": { "type": [ "string", "integer" ] }, "certBody": { "type": "string" }, "certNumber": { "type": [ "string", "null" ] }, "issuedAt": { "type": [ "string", "null" ] }, "verifyUrl": { "type": [ "string", "null" ] }, "registry": { "type": "string" }, "provenance": { "$ref": "#/components/schemas/Evidence" } }, "required": [ "kind", "certificationId", "certBody", "certNumber", "issuedAt", "verifyUrl", "registry", "provenance" ] }, { "type": "object", "properties": { "kind": { "const": "vendor_claim" }, "mark": { "type": "string" }, "provenance": { "$ref": "#/components/schemas/Evidence" } }, "required": [ "kind", "mark", "provenance" ] } ] }, "CertificationLevel": { "type": "object", "description": "One certification program on a product with its verification level. registry_verified: an active record from the program's official registry; self_declared: the program has no official lookup (e.g. CE), counted as the vendor declares; vendor_claimed_unverified: vendor claim only, while the program has a registry we have not matched (or cannot read), or the program is not yet published. Vendor-stated UL marks are always vendor_claimed_unverified.", "properties": { "program": { "type": "object", "properties": { "code": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "hasOfficialLookup": { "type": [ "string", "null" ], "enum": [ "yes", "no", "blocked", null ] } }, "required": [ "code", "slug", "name", "hasOfficialLookup" ] }, "level": { "type": "string", "enum": [ "registry_verified", "self_declared", "vendor_claimed_unverified" ] }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/CertificationLevelEvidence" } } }, "required": [ "program", "level", "evidence" ] }, "ApiIndex": { "type": "object", "description": "Discovery document: contract links, access/quota policy and the attribution term.", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "openapi": { "type": "string", "format": "uri" }, "mcp": { "type": "string", "format": "uri" }, "docs": { "type": "string", "format": "uri" }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "access": { "type": "object", "properties": { "authentication": { "type": "array", "items": { "type": "string" } }, "anonymous": { "$ref": "#/components/schemas/QuotaPolicy" }, "keyTiers": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/QuotaPolicy" } }, "requestKey": { "type": "string", "description": "How to request a free API key." } }, "required": [ "authentication", "anonymous", "keyTiers", "requestKey" ] } }, "required": [ "name", "version", "openapi", "mcp", "docs", "attribution", "access" ] }, "QuotaPolicy": { "type": "object", "properties": { "limit": { "type": "integer" }, "windowSeconds": { "type": "integer" }, "per": { "type": "string", "enum": [ "client_ip", "api_key" ] } }, "required": [ "limit", "windowSeconds", "per" ] }, "Attribution": { "type": "object", "description": "Attribution term: reuse of the data requires citing the service by name with a link.", "properties": { "required": { "const": true }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "text": { "type": "string", "description": "Suggested attribution line, e.g. \"Attribution: ()\"." }, "policyUrl": { "type": "string", "format": "uri" }, "notice": { "type": "string" } }, "required": [ "required", "name", "url", "text", "policyUrl", "notice" ] }, "CompanyRef": { "description": "A company reference: EntityRef plus the public key and canonical page URL. `slug` follows CompanySummary.slug (company slug with the server switch `MOTOBASE_PUBLIC_URLS_ENABLED` on, else the numeric id).", "allOf": [ { "$ref": "#/components/schemas/EntityRef" }, { "type": "object", "properties": { "publicId": { "type": [ "string", "null" ], "description": "Company slug (public key); `null` until backfilled." }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "Absolute canonical `/companies/` URL; `null` until backfilled and while the server switch `MOTOBASE_PUBLIC_URLS_ENABLED` is off." } }, "required": [ "publicId", "url" ] } ] }, "ApplicationSummary": { "type": "object", "required": [ "slug", "name", "summary", "essenceBridge", "path", "url" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "essenceBridge": { "type": "string", "description": "Opening paragraph: which product category serves this use case and why." }, "path": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "servesNote": { "type": [ "string", "null" ], "description": "Only with ?category=: how that category serves this use case." } } }, "ApplicationDetail": { "allOf": [ { "$ref": "#/components/schemas/ApplicationSummary" }, { "type": "object", "required": [ "keyParameters", "applicationTypeValues", "categories", "standards", "certificationPrograms", "relatedScenarios", "selectionNotes", "references" ], "properties": { "typicalLoadsAndSizes": { "type": [ "string", "null" ] }, "keyParameters": { "type": "array", "items": { "type": "string" }, "description": "Spec vocabulary keys." }, "applicationTypeValues": { "type": "array", "items": { "type": "string" }, "description": "application_types vocabulary values." }, "categories": { "type": "array", "items": { "type": "object", "required": [ "slug", "name", "servesNote", "categoryPath", "productFilterPath", "productCount" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "servesNote": { "type": [ "string", "null" ] }, "categoryPath": { "type": [ "string", "null" ] }, "productFilterPath": { "type": "string" }, "productCount": { "type": [ "integer", "null" ], "description": "Null until the category template-completeness gate is met." } } } }, "standards": { "type": "array", "items": { "type": "object", "required": [ "slug", "name" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } } } }, "certificationPrograms": { "type": "array", "items": { "type": "object", "required": [ "slug", "name" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } } } }, "relatedScenarios": { "type": "array", "items": { "type": "object", "required": [ "label", "note" ], "properties": { "label": { "type": "string" }, "note": { "type": [ "string", "null" ] } } } }, "selectionNotes": { "type": "array", "items": { "type": "object", "required": [ "point", "sources" ], "properties": { "point": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string", "format": "uri" } } } } }, "references": { "type": "array", "items": { "type": "object", "required": [ "url", "title" ], "properties": { "url": { "type": "string", "format": "uri" }, "title": { "type": [ "string", "null" ] } } } } } } ] }, "DeprecatedIdentifierMeta": { "type": "object", "description": "Present on a detail response addressed by a deprecated identifier (legacy numeric id, legacy company slug); otherwise `meta` is null.", "properties": { "deprecatedIdentifier": { "const": true } }, "required": [ "deprecatedIdentifier" ] }, "CompanyRelation": { "type": "object", "description": "A confirmed, sourced link from this company to another (motobase-company-relations). The row reads `this company —relationType→ related entity`; e.g. `business_unit` means the related entity is a business unit of this company. `company` is set only when the related company has a public record; otherwise `legalName` names it.", "properties": { "relationType": { "type": "string", "enum": [ "parent", "subsidiary", "business_unit", "affiliate", "brand_owner", "oem_supplier", "distributor", "former_name", "merged_into" ] }, "company": { "oneOf": [ { "$ref": "#/components/schemas/CompanyRef" }, { "type": "null" } ] }, "legalName": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 of the related entity." }, "note": { "type": [ "string", "null" ] }, "sources": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "title": { "type": [ "string", "null" ] }, "retrievedAt": { "type": [ "string", "null" ] } }, "required": [ "url", "title", "retrievedAt" ] } } }, "required": [ "relationType", "company", "legalName", "country", "note", "sources" ] }, "ReplacementProductSummary": { "type": "object", "required": [ "id", "slug", "publicId", "path", "url", "displayName", "label", "modelCode", "partNumber", "aliases", "brand", "series", "lifecycle", "speedBasis", "specs" ], "properties": { "id": { "type": [ "string", "null" ], "description": "Deprecated numeric id; null while MOTOBASE_PUBLIC_URLS_ENABLED is on (the API never outputs numeric ids then). Use slug or publicId." }, "slug": { "type": "string", "description": "API identifier, same rule as GET /api/v1/products/{slug}: the canonical URL segment with public URLs on, else (or while not backfilled) the numeric id." }, "publicId": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "displayName": { "type": "string" }, "label": { "type": "string", "description": "What to show: displayName, or — when another product in the same result shares the display name — `displayName ()`, the first that tells them apart. Deterministic." }, "modelCode": { "type": "string", "description": "The raw model string as published (e.g. `R8/17C PLUS`)." }, "partNumber": { "type": [ "string", "null" ], "description": "Manufacturer part number / SKU as published." }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Part-number aliases (superseded, regional, vendor alternatives), sorted." }, "brand": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } } }, "series": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } }, "lifecycle": { "type": "string", "enum": [ "active", "discontinued", "replaced", "unknown" ] }, "speedBasis": { "type": "string", "enum": [ "load", "no_load", "unknown" ] }, "specs": { "type": "object", "description": "Key specs from the product's published values: torque_nm, rpm, diameter_mm when known.", "additionalProperties": { "$ref": "#/components/schemas/ReplacementSpecValue" } } } }, "ReplacementSpecValue": { "type": "object", "properties": { "value": { "description": "Number, text or list of values.", "oneOf": [ { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "type": [ "string", "number" ] } }, { "type": "null" } ] }, "display": { "type": "string", "description": "Display text with unit; enum values as vocabulary labels (e.g. `8 Nm`, `Roller shutter, Awning`, `io-homecontrol`)." }, "unit": { "type": [ "string", "null" ] }, "basis": { "type": "string", "enum": [ "claim", "derived_model_name", "series_default", "user_override" ], "description": "claim = a product claim; derived_model_name = read from the model name (shown as 'from the model name'); series_default = a series-level value; user_override = a value the requester supplied (torque/rpm/diameter/voltage params, shown as 'your value')." }, "basisLabel": { "type": [ "string", "null" ] }, "claimId": { "type": [ "string", "null" ] }, "qualifier": { "type": [ "string", "null" ] }, "evidenceStrength": { "type": [ "string", "null" ] } } }, "ReplacementMatchLine": { "type": "object", "properties": { "key": { "type": "string" }, "targetValue": { "description": "Number, text or list of values.", "oneOf": [ { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "type": [ "string", "number" ] } }, { "type": "null" } ] }, "candidateValue": { "description": "Number, text or list of values.", "oneOf": [ { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "type": [ "string", "number" ] } }, { "type": "null" } ] }, "delta": { "type": [ "number", "null" ] }, "basis": { "type": "object", "properties": { "target": { "type": [ "string", "null" ] }, "candidate": { "type": [ "string", "null" ] } } }, "text": { "type": "string" } } }, "ReplacementEvidence": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "claim", "certification_match", "human_review", "spec_comparison" ] }, "claimId": { "type": [ "string", "null" ] }, "verifiedAt": { "type": [ "string", "null" ] }, "referenceUrl": { "type": [ "string", "null" ] }, "rationale": { "type": [ "string", "null" ] } } }, "ReplacementMatch": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/ReplacementProductSummary" }, "tier": { "type": "string", "enum": [ "a", "b", "c", "d" ] }, "grade": { "type": [ "string", "null" ], "enum": [ "direct", "with_changes", null ] }, "label": { "type": "string" }, "matched": { "type": "array", "items": { "$ref": "#/components/schemas/ReplacementMatchLine" } }, "differences": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/ReplacementMatchLine" }, { "type": "object", "properties": { "severity": { "type": "string", "enum": [ "consequence" ] } } } ] } }, "notes": { "type": "array", "items": { "type": "string" } }, "requiredChanges": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "crown", "drive", "bracket", "adapter", "controller", "wiring", "other" ] }, "text": { "type": "string" }, "partNumber": { "type": "string" } } } }, "notChecked": { "type": "array", "items": { "type": "object", "properties": { "item": { "type": "string", "enum": [ "head_and_adapters", "brackets", "remote_pairing", "wiring" ] }, "text": { "type": "string" } } } }, "weakEvidence": { "type": "boolean" }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/ReplacementEvidence" } } } }, "ReplacementResult": { "type": "object", "required": [ "query", "resolution", "target", "specMatching", "groups", "statedParts", "insufficient", "unchecked", "override", "excludedCounts", "disclaimer", "generatedAt", "provenance" ], "properties": { "query": { "type": [ "object", "null" ], "description": "Null for /api/v1/products/{slug}/replacements.", "properties": { "raw": { "type": "string" }, "brand": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } } }, "modelKey": { "type": "string" }, "torqueSpeedHint": { "type": [ "object", "null" ], "properties": { "torqueNm": { "type": "number" }, "rpm": { "type": "number" }, "ruleId": { "type": "string" } } } } }, "resolution": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "resolved", "resolved_edition", "series_only", "ambiguous", "not_found" ] }, "resolvedVia": { "type": [ "string", "null" ], "enum": [ "product_key", "exact", "model_group", "edition", "series_token", "duplicate", "index", null ] }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/ReplacementProductSummary" }, "description": "ambiguous: choose one (max 10); series_only: current sizes of the series." }, "groupMembers": { "type": "array", "items": { "$ref": "#/components/schemas/ReplacementProductSummary" } }, "note": { "type": [ "string", "null" ] }, "truncated": { "type": "boolean", "description": "The named series has more sizes than the listed cap (60): series_only candidates are the first page. The exact size was still looked up across the whole series." }, "truncatedText": { "type": [ "string", "null" ] }, "suggestions": { "type": "array", "items": { "$ref": "#/components/schemas/ReplacementProductSummary" }, "description": "status not_found or ambiguous only: up to 10 fuzzy search hits that were not resolved to a product (\"did you mean\" links, never a target). Empty otherwise. id is null while public URLs are on; use slug / path / url." }, "suggestionsText": { "type": [ "string", "null" ], "description": "\"Did you mean one of these?\" when suggestions is non-empty, else null." } } }, "target": { "type": [ "object", "null" ], "properties": { "kind": { "type": "string", "enum": [ "product", "virtual" ] }, "product": { "oneOf": [ { "$ref": "#/components/schemas/ReplacementProductSummary" }, { "type": "null" } ] }, "series": { "type": [ "object", "null" ], "description": "Series of a model query (series_token / series_only). `id` is null while public URLs are on.", "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "slug": { "type": "string" }, "brand": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" } } } } }, "assumption": { "type": [ "string", "null" ], "description": "Virtual target sentence, or which values came from the requester (torque/rpm/diameter/voltage params)." }, "lifecycle": { "type": "string" }, "speedBasis": { "type": "string", "enum": [ "load", "no_load", "unknown" ] }, "specs": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ReplacementSpecValue" } } } }, "specMatching": { "type": "string", "enum": [ "ok", "insufficient_data", "not_tubular", "no_target" ] }, "groups": { "type": "array", "items": { "type": "object", "properties": { "tier": { "type": "string", "enum": [ "a", "b", "c", "d" ] }, "label": { "type": "string" }, "matches": { "type": "array", "items": { "$ref": "#/components/schemas/ReplacementMatch" } } } } }, "statedParts": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "partNumber": { "type": [ "string", "null" ] }, "brand": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } } }, "requiredChanges": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "crown", "drive", "bracket", "adapter", "controller", "wiring", "other" ] }, "text": { "type": "string" }, "partNumber": { "type": "string" } } } }, "evidence": { "$ref": "#/components/schemas/ReplacementEvidence" }, "label": { "type": "string" } } } }, "insufficient": { "type": [ "object", "null" ], "properties": { "heading": { "type": "string" }, "missing": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "torque", "speed", "diameter", "supply" ] }, "reason": { "type": "string", "enum": [ "not_published", "not_yet_collected", "conflict", "limit_only" ] }, "text": { "type": "string" } } } } } }, "unchecked": { "type": "array", "items": { "type": "object", "properties": { "tier": { "type": "string", "enum": [ "a", "b", "c", "d" ] }, "count": { "type": "integer" }, "missing": { "type": "array", "items": { "type": "string" } }, "productIds": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Deprecated numeric ids; null while public URLs are on. Use productKeys." }, "productKeys": { "type": "array", "items": { "type": "string" }, "description": "API identifiers of the unchecked products (ReplacementProductSummary.slug rule)." }, "text": { "type": "string" }, "catalogPath": { "type": [ "string", "null" ], "description": "Catalogue listing of the tier's scope: `/products?product_line=…&brand=…[&series=…]` (b = same series, c = same brand, d = product line). The catalogue has no missing-field filter; this is the closest filtered view." }, "catalogUrl": { "type": [ "string", "null" ], "description": "Absolute catalogPath; null while public URLs are disabled." } } } }, "override": { "type": [ "object", "null" ], "description": "Requester values (torque/rpm/diameter/voltage params): requested, applied to the target, ignored with a reason. Null when none were given.", "properties": { "requested": { "type": "object", "properties": { "torque": { "type": [ "number", "null" ] }, "rpm": { "type": [ "number", "null" ] }, "diameter": { "type": [ "number", "null" ] }, "voltage": { "type": [ "number", "null" ] } } }, "applied": { "type": "array", "items": { "type": "string", "enum": [ "torque", "rpm", "diameter", "voltage" ] } }, "ignored": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "torque", "rpm", "diameter", "voltage" ] }, "reason": { "type": "string", "enum": [ "product_value", "no_target" ], "description": "product_value = the resolved product publishes this value (never replaced); no_target = no brand, or torque/rpm/diameter incomplete, so nothing could be compared." } } } }, "text": { "type": [ "string", "null" ] } } }, "excludedCounts": { "type": "object", "additionalProperties": { "type": "integer" } }, "disclaimer": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" }, "provenance": { "type": "object", "properties": { "method": { "type": "string" }, "tolerances": { "type": "string" }, "tiersRequested": { "type": "array", "items": { "type": "string", "enum": [ "a", "b", "c", "d" ] } }, "candidatePool": { "type": "object", "properties": { "recalled": { "type": "integer" }, "truncated": { "type": "boolean" } } } } } } }, "EventOrganiser": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "organiserType": { "type": "string", "enum": [ "trade_fair_organiser", "association", "standards_body", "manufacturer", "certification_body", "other" ] }, "country": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } }, "required": [ "slug", "name", "organiserType", "country", "website" ] }, "Event": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "series": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ] }, "year": { "type": "integer" }, "editionLabel": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "trade_show", "conference", "product_launch_event", "training_webinar", "standards_meeting", "other" ] }, "status": { "type": "string", "enum": [ "announced", "confirmed", "postponed", "cancelled", "completed" ], "description": "Status on the response date; announced/confirmed editions whose last day has passed read completed." }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": [ "string", "null" ], "format": "date" }, "datePrecision": { "type": "string", "enum": [ "day", "month", "year" ], "description": "month / year: only the period is known; startDate is the first day of it." }, "dateLabel": { "type": [ "string", "null" ] }, "format": { "type": "string", "enum": [ "in_person", "online", "hybrid" ] }, "venue": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ], "enum": [ "europe", "china", "asia_pacific", "middle_east_africa", "north_america", "latin_america", "cis", null ] }, "organisers": { "type": "array", "items": { "$ref": "#/components/schemas/EventOrganiser" } }, "website": { "type": [ "string", "null" ] }, "attendanceUrl": { "type": [ "string", "null" ] }, "exhibitorDirectoryUrl": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ], "description": "Editorial caveat, e.g. unverified dates." }, "lastVerifiedAt": { "type": [ "string", "null" ], "format": "date" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": [ "string", "null" ] } }, "required": [ "url", "title" ] } }, "links": { "type": "object", "properties": { "api": { "type": "string" } }, "required": [ "api" ] } }, "required": [ "slug", "name", "series", "year", "editionLabel", "type", "status", "startDate", "endDate", "datePrecision", "dateLabel", "format", "venue", "city", "country", "region", "organisers", "website", "attendanceUrl", "exhibitorDirectoryUrl", "note", "lastVerifiedAt", "sources", "links" ] }, "EventParticipant": { "type": "object", "properties": { "company": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ] }, "brand": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ] }, "role": { "type": "string", "enum": [ "exhibitor", "co_exhibitor", "sponsor", "speaker", "organiser_member" ] }, "hall": { "type": [ "string", "null" ] }, "stand": { "type": [ "string", "null" ] }, "confidence": { "type": "string", "enum": [ "confirmed", "announced" ] }, "evidenceKind": { "type": "string", "enum": [ "organiser_directory", "company_announcement", "press", "submission", "editorial" ] }, "attribution": { "type": "string", "description": "Provenance label, e.g. 'Source: organiser directory' or 'Announced by '." }, "sourceUrl": { "type": [ "string", "null" ] }, "directoryEntryUrl": { "type": [ "string", "null" ] } }, "required": [ "company", "brand", "role", "hall", "stand", "confidence", "evidenceKind", "attribution", "sourceUrl", "directoryEntryUrl" ] }, "EventDetail": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "trackedParticipants": { "type": "array", "items": { "$ref": "#/components/schemas/EventParticipant" } } }, "required": [ "trackedParticipants" ] } ] }, "ProductRef": { "description": "A product reference: EntityRef plus the canonical display name.", "allOf": [ { "$ref": "#/components/schemas/EntityRef" }, { "type": "object", "properties": { "displayName": { "type": "string", "description": "Canonical display name (the public page H1). Presentation only — never use it as an id, slug or filter value; `name` keeps the original value." } }, "required": [ "displayName" ] } ] } }, "responses": { "BadRequest": { "description": "Invalid or unknown query parameter, or malformed cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "NotFound": { "description": "No publicly visible record matches this identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "RateLimited": { "description": "Quota exhausted; retry after Retry-After seconds, or use an API key for a higher quota.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-Quota-Scope": { "$ref": "#/components/headers/QuotaScope" } } }, "InternalError": { "description": "Temporary failure; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Unauthorized": { "description": "The API key is malformed, unknown or revoked (omit it to use the anonymous quota).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" } } } }, "Gone": { "description": "The record was publicly visible and has been withdrawn (`error.code` = `gone`). Records that were never public answer 404. Only while the server switch `MOTOBASE_PUBLIC_URLS_ENABLED` is on; otherwise 404.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "headers": { "ETag": { "description": "Weak entity tag; send as If-None-Match to get 304.", "schema": { "type": "string" } }, "CacheControl": { "schema": { "type": "string", "example": "public, max-age=60" } }, "RateLimitRemaining": { "schema": { "type": "integer" }, "description": "Requests left in the current quota window." }, "RateLimitLimit": { "description": "Quota size of the window that applies to this caller.", "schema": { "type": "integer" } }, "RateLimitReset": { "description": "Seconds until the current quota window resets.", "schema": { "type": "integer" } }, "RateLimitPolicy": { "description": "Quota policy, e.g. \"60;w=3600\" (anonymous) or \"5000;w=86400\" (free key).", "schema": { "type": "string" } }, "QuotaScope": { "description": "Which quota applied: anonymous, free or partner.", "schema": { "type": "string", "enum": [ "anonymous", "free", "partner" ] } }, "Deprecation": { "description": "RFC 9745 structured-field date (`@`, here 2026-10-06T00:00:00Z): the identifier used in the request is deprecated. Sent only when a detail request addressed the entity by its legacy numeric id (products, companies) or a legacy company slug, and only while the server switch `MOTOBASE_PUBLIC_URLS_ENABLED` is on.", "schema": { "type": "string", "const": "@1791244800" } }, "Link": { "description": "With `Deprecation`: `; rel=\"successor-version\"` — the same endpoint addressed by the entity's current identifier (e.g. `/api/v1/products/somfy-sonesse-30-rts-k7q2m9x`, `/api/v1/companies/somfy`). Absent while the entity has no public key yet (not backfilled).", "schema": { "type": "string" } } }, "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key (oax_…). Optional: without a key the anonymous per-IP quota applies." }, "BearerKey": { "type": "http", "scheme": "bearer", "description": "The same API key sent as \"Authorization: Bearer \"." } } } }