{ "schemaVersion": 1, "generatedFrom": { "openapi": "3.1.0", "apiVersion": "1.71.0", "releaseStatus": "published" }, "authority": "https://docs.tapinomahub.com/specs/tapinoma-hub.en.json", "operationCount": 67, "operations": [ { "operationId": "resolvePartIntelligence", "method": "GET", "path": "/parts/intelligence", "tags": [ "Intelligence" ], "summary": "Resolves part identifiers to a part cluster and returns intelligence", "description": "At least `oeNumber` or `aftermarketNumber` must be set. kType, NatCode and\nGenArt are contextual and disambiguation attributes; on their own, they do not form\nan interchangeable cluster. The call searches only known identifiers and can trigger\na targeted cluster refresh. It does not enumerate the OE-number space.\n\n\nPilot availability: the paid production pilot is commercially closed. No real results are delivered without approved positive prices and atomic billing. Approved Observed Supply data and the authorised dealer panel are not yet available in production. Adaptive refresh and VIN economic analysis are disabled; scores remain `null` or `publishable=false` without sufficient evidence.", "authentication": [ { "apiKeyAuth": [] }, { "marketIntelligenceSessionCookie": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable key for exactly one business-level request. Without an approved positive price and atomic billing, the real-data path remains locked.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/parameters/0/schema", "schema": { "type": "string", "minLength": 16, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/parameters/0" }, { "name": "oeNumber", "in": "query", "required": false, "description": "OE number used as the entry point into the versioned cluster graph.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/parameters/1/schema", "schema": { "type": "string", "minLength": 3, "maxLength": 80 }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/parameters/1" }, { "name": "oeManufacturer", "in": "query", "required": false, "description": "Manufacturer namespace of the OE number.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/parameters/2/schema", "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/parameters/2" }, { "name": "aftermarketNumber", "in": "query", "required": false, "description": "Aftermarket, MPN or GTIN reference.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/parameters/3/schema", "schema": { "type": "string", "minLength": 3, "maxLength": 120 }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/parameters/3" }, { "name": "aftermarketManufacturer", "in": "query", "required": false, "description": "Manufacturer or namespace of the aftermarket reference.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/parameters/4/schema", "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/parameters/4" }, { "name": "kType", "in": "query", "required": false, "description": "Optional kType for disambiguation; never an identity anchor on its own.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/parameters/5/schema", "schema": { "type": "integer", "minimum": 1 }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/parameters/5" }, { "name": "natCode", "in": "query", "required": false, "description": "Optional NatCode for disambiguation; never an identity anchor on its own.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/parameters/6/schema", "schema": { "type": "string", "minLength": 1, "maxLength": 80 }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/parameters/6" }, { "name": "genArt", "in": "query", "required": false, "description": "Optional GenArt for classification; never an identity anchor on its own.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/parameters/7/schema", "schema": { "type": "string", "minLength": 1, "maxLength": 80 }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/parameters/7" }, { "name": "marketCountry", "in": "query", "required": false, "description": null, "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/parameters/8/schema", "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "default": "DE" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/parameters/8" }, { "name": "currency", "in": "query", "required": false, "description": null, "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/parameters/9/schema", "schema": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "EUR" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/parameters/9" }, { "name": "condition", "in": "query", "required": false, "description": null, "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/parameters/10/schema", "schema": { "type": "string", "enum": [ "new", "remanufactured", "used", "unknown" ], "default": "used" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/parameters/10" }, { "name": "windowDays", "in": "query", "required": false, "description": null, "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/parameters/11/schema", "schema": { "type": "integer", "enum": [ 30, 60, 90, 180, 365 ], "default": 90 }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/parameters/11" }, { "name": "asOf", "in": "query", "required": false, "description": "Historical cutoff; the most recent eligible snapshot is used when omitted.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/parameters/12/schema", "schema": { "type": "string", "format": "date-time" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/parameters/12" }, { "name": "minimumEvidence", "in": "query", "required": false, "description": "Required minimum coverage. `any` transparently returns known clusters even with\n`status=insufficient_evidence`; if a higher tier is not reached, the API returns\n`422 insufficient_evidence`.\n", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/parameters/13/schema", "schema": { "type": "string", "enum": [ "any", "directional", "usable", "strong" ], "default": "any" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/parameters/13" }, { "name": "freshnessPolicy", "in": "query", "required": false, "description": "`allow_stale` returns the latest marked snapshot. `refresh_if_stale` schedules a\ntargeted refresh when required. `require_fresh` returns 202 until a fresh snapshot\nis available.\n", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/parameters/14/schema", "schema": { "type": "string", "enum": [ "allow_stale", "refresh_if_stale", "require_fresh" ], "default": "refresh_if_stale" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/parameters/14" } ], "requestBody": null, "responses": [ { "status": "200", "description": "The cluster was resolved; the status may also be `insufficient_evidence`.", "headers": [ "X-Tapinoma-Idempotent-Replay" ], "openApiPointer": "#/paths/~1parts~1intelligence/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/MarketIntelligenceClusterIntelligenceResponse", "schemaPointer": "#/components/schemas/MarketIntelligenceClusterIntelligenceResponse", "exampleNames": [], "examples": [] } ], "errorCodes": [] }, { "status": "202", "description": "A targeted refresh of a known cluster has been accepted.", "headers": [ "Location", "X-Tapinoma-Idempotent-Replay", "Retry-After" ], "openApiPointer": "#/paths/~1parts~1intelligence/get/responses/202", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/MarketIntelligenceAsyncAccepted", "schemaPointer": "#/components/schemas/MarketIntelligenceAsyncAccepted", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "requestId": "70b35c44-3bfa-45f5-98ee-c282f7ca4cb8", "jobId": "70b35c44-3bfa-45f5-98ee-c282f7ca4cb8", "status": "queued", "reason": "stale_snapshot", "requestedAt": "2026-09-11T13:40:00Z", "statusUrl": "https://api.tapinomahub.com/parts/intelligence/jobs/70b35c44-3bfa-45f5-98ee-c282f7ca4cb8" } } ] } ], "errorCodes": [] }, { "status": "400", "description": "The query, header or JSON body is syntactically invalid.", "headers": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/responses/400/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_query_parameter", "invalid_minimum_evidence", "invalid_idempotency_key" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "invalid_query_parameter", "invalid_minimum_evidence", "invalid_idempotency_key" ], "examples": [ { "name": "invalid_query_parameter", "value": { "error": "invalid_query_parameter", "details": { "parameter": "unknown" } } }, { "name": "invalid_minimum_evidence", "value": { "error": "invalid_minimum_evidence" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key" } } ] } ], "errorCodes": [ "invalid_idempotency_key", "invalid_minimum_evidence", "invalid_query_parameter" ] }, { "status": "401", "description": "The session or API key is missing, invalid or cannot be assigned unambiguously to a pilot account.", "headers": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/responses/401/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "authentication_required" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "authentication_required" ], "examples": [ { "name": "authentication_required", "value": { "error": "authentication_required" } } ] } ], "errorCodes": [ "authentication_required" ] }, { "status": "403", "description": "Pilot access is missing, the session email is unverified, or the CSRF proof is invalid for a session-authenticated POST request.", "headers": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/responses/403/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "market_intelligence_not_enabled", "email_not_verified" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "market_intelligence_not_enabled", "email_not_verified" ], "examples": [ { "name": "market_intelligence_not_enabled", "value": { "error": "market_intelligence_not_enabled" } }, { "name": "email_not_verified", "value": { "error": "email_not_verified" } } ] } ], "errorCodes": [ "email_not_verified", "market_intelligence_not_enabled" ] }, { "status": "404", "description": "No matching identifier, cluster, VIN or job is known.", "headers": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/responses/404/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "cluster_not_found", "snapshot_not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "cluster_not_found", "snapshot_not_found" ], "examples": [ { "name": "cluster_not_found", "value": { "error": "cluster_not_found", "message": "No known part cluster matches the requested scope.", "requestId": "ac6cffca-46e4-4fc8-8cd5-601892188c7c" } }, { "name": "snapshot_not_found", "value": { "error": "snapshot_not_found" } } ] } ], "errorCodes": [ "cluster_not_found", "snapshot_not_found" ] }, { "status": "409", "description": "The Idempotency-Key has already been used for a different business scope.", "headers": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/responses/409/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "idempotency_key_conflict" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict" } } ] } ], "errorCodes": [ "idempotency_key_conflict" ] }, { "status": "422", "description": "The input is ambiguous or invalid, or the required evidence tier is missing.", "headers": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/responses/422", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/responses/422/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "identifier_required", "invalid_identifier", "invalid_integer", "invalid_enum", "invalid_format", "invalid_instant", "ambiguous_cluster", "insufficient_evidence", "refresh_unavailable" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "identifier_required", "invalid_identifier", "invalid_integer", "invalid_enum", "invalid_format", "invalid_instant", "ambiguous_cluster", "insufficient_evidence", "refresh_unavailable" ], "examples": [ { "name": "identifier_required", "value": { "error": "identifier_required" } }, { "name": "invalid_identifier", "value": { "error": "invalid_identifier" } }, { "name": "invalid_integer", "value": { "error": "invalid_integer" } }, { "name": "invalid_enum", "value": { "error": "invalid_enum" } }, { "name": "invalid_format", "value": { "error": "invalid_format" } }, { "name": "invalid_instant", "value": { "error": "invalid_instant" } }, { "name": "ambiguous_cluster", "value": { "error": "ambiguous_cluster", "message": "Multiple part clusters remain plausible; add manufacturer or fitment context.", "requestId": "67dbc724-7303-4623-a6fd-4c58c8d68d6e", "details": { "candidateCount": 2, "disambiguationFields": [ "oeManufacturer", "kType", "natCode" ] } } }, { "name": "insufficient_evidence", "value": { "error": "insufficient_evidence", "message": "The requested minimum evidence level is not available for this cluster.", "requestId": "52469176-c17a-4fa4-95c0-2e1d15745153", "details": { "requestedLevel": "usable", "availableLevel": "directional", "missingEvidence": [ "verified_sales:30", "contributors:10" ] } } }, { "name": "refresh_unavailable", "value": { "error": "refresh_unavailable" } } ] } ], "errorCodes": [ "ambiguous_cluster", "identifier_required", "insufficient_evidence", "invalid_enum", "invalid_format", "invalid_identifier", "invalid_instant", "invalid_integer", "refresh_unavailable" ] }, { "status": "429", "description": "The shared tenant-wide per-minute limit across all API replicas has been reached.", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1parts~1intelligence/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/responses/429/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limit_exceeded" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "rate_limit_exceeded" ], "examples": [ { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded" } } ] } ], "errorCodes": [ "rate_limit_exceeded" ] }, { "status": "503", "description": "The intelligence runtime or a required dependency is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1parts~1intelligence/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence/get/responses/503/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "market_intelligence_unavailable" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } }, "exampleNames": [ "market_intelligence_unavailable" ], "examples": [ { "name": "market_intelligence_unavailable", "value": { "error": "market_intelligence_unavailable" } } ] } ], "errorCodes": [ "market_intelligence_unavailable" ] } ], "supportsIdempotencyKey": true, "asynchronous": true, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1parts~1intelligence/get" }, { "operationId": "getPartClusterIntelligence", "method": "GET", "path": "/parts/clusters/{clusterId}/intelligence", "tags": [ "Intelligence" ], "summary": "Returns the current intelligence snapshot for a known part cluster", "description": "Reads a materialized snapshot. With `minimumEvidence=any`, a known cluster is\nalso returned with status 200 when `status=insufficient_evidence`. If the client\nrequires a minimum tier that has not been reached, the API responds with\n`422 insufficient_evidence`.\n\n\nPilot availability: the paid production pilot is commercially closed. No real results are delivered without approved positive prices and atomic billing. Approved Observed Supply data and the authorised dealer panel are not yet available in production. Adaptive refresh and VIN economic analysis are disabled; scores remain `null` or `publishable=false` without sufficient evidence.", "authentication": [ { "apiKeyAuth": [] }, { "marketIntelligenceSessionCookie": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable key for exactly one business-level request. Without an approved positive price and atomic billing, the real-data path remains locked.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/parameters/0/schema", "schema": { "type": "string", "minLength": 16, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/parameters/0" }, { "name": "clusterId", "in": "path", "required": true, "description": "Stable ID of a part cluster; its composition is versioned separately.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/parameters/1/schema", "schema": { "type": "string", "format": "uuid" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/parameters/1" }, { "name": "clusterVersion", "in": "query", "required": false, "description": "Optional historical cluster version; the active version is used when omitted.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/parameters/2/schema", "schema": { "type": "integer", "minimum": 1 }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/parameters/2" }, { "name": "marketCountry", "in": "query", "required": false, "description": null, "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/parameters/3/schema", "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "default": "DE" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/parameters/3" }, { "name": "currency", "in": "query", "required": false, "description": null, "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/parameters/4/schema", "schema": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "EUR" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/parameters/4" }, { "name": "condition", "in": "query", "required": false, "description": null, "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/parameters/5/schema", "schema": { "type": "string", "enum": [ "new", "remanufactured", "used", "unknown" ], "default": "used" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/parameters/5" }, { "name": "windowDays", "in": "query", "required": false, "description": null, "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/parameters/6/schema", "schema": { "type": "integer", "enum": [ 30, 60, 90, 180, 365 ], "default": 90 }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/parameters/6" }, { "name": "asOf", "in": "query", "required": false, "description": "Historical cutoff; the most recent eligible snapshot is used when omitted.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/parameters/7/schema", "schema": { "type": "string", "format": "date-time" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/parameters/7" }, { "name": "minimumEvidence", "in": "query", "required": false, "description": "Required minimum coverage. `any` transparently returns known clusters even with\n`status=insufficient_evidence`; if a higher tier is not reached, the API returns\n`422 insufficient_evidence`.\n", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/parameters/8/schema", "schema": { "type": "string", "enum": [ "any", "directional", "usable", "strong" ], "default": "any" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/parameters/8" }, { "name": "freshnessPolicy", "in": "query", "required": false, "description": "`allow_stale` returns the latest marked snapshot. `refresh_if_stale` schedules a\ntargeted refresh when required. `require_fresh` returns 202 until a fresh snapshot\nis available.\n", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/parameters/9/schema", "schema": { "type": "string", "enum": [ "allow_stale", "refresh_if_stale", "require_fresh" ], "default": "refresh_if_stale" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/parameters/9" } ], "requestBody": null, "responses": [ { "status": "200", "description": "Materialized cluster intelligence.", "headers": [ "X-Tapinoma-Idempotent-Replay" ], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/MarketIntelligenceClusterIntelligenceResponse", "schemaPointer": "#/components/schemas/MarketIntelligenceClusterIntelligenceResponse", "exampleNames": [], "examples": [] } ], "errorCodes": [] }, { "status": "202", "description": "A targeted refresh of a known cluster has been accepted.", "headers": [ "Location", "X-Tapinoma-Idempotent-Replay", "Retry-After" ], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/responses/202", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/MarketIntelligenceAsyncAccepted", "schemaPointer": "#/components/schemas/MarketIntelligenceAsyncAccepted", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "requestId": "70b35c44-3bfa-45f5-98ee-c282f7ca4cb8", "jobId": "70b35c44-3bfa-45f5-98ee-c282f7ca4cb8", "status": "queued", "reason": "stale_snapshot", "requestedAt": "2026-09-11T13:40:00Z", "statusUrl": "https://api.tapinomahub.com/parts/intelligence/jobs/70b35c44-3bfa-45f5-98ee-c282f7ca4cb8" } } ] } ], "errorCodes": [] }, { "status": "400", "description": "The query, header or JSON body is syntactically invalid.", "headers": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/responses/400/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_query_parameter", "invalid_minimum_evidence", "invalid_idempotency_key" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "invalid_query_parameter", "invalid_minimum_evidence", "invalid_idempotency_key" ], "examples": [ { "name": "invalid_query_parameter", "value": { "error": "invalid_query_parameter", "details": { "parameter": "unknown" } } }, { "name": "invalid_minimum_evidence", "value": { "error": "invalid_minimum_evidence" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key" } } ] } ], "errorCodes": [ "invalid_idempotency_key", "invalid_minimum_evidence", "invalid_query_parameter" ] }, { "status": "401", "description": "The session or API key is missing, invalid or cannot be assigned unambiguously to a pilot account.", "headers": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/responses/401/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "authentication_required" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "authentication_required" ], "examples": [ { "name": "authentication_required", "value": { "error": "authentication_required" } } ] } ], "errorCodes": [ "authentication_required" ] }, { "status": "403", "description": "Pilot access is missing, the session email is unverified, or the CSRF proof is invalid for a session-authenticated POST request.", "headers": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/responses/403/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "market_intelligence_not_enabled", "email_not_verified" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "market_intelligence_not_enabled", "email_not_verified" ], "examples": [ { "name": "market_intelligence_not_enabled", "value": { "error": "market_intelligence_not_enabled" } }, { "name": "email_not_verified", "value": { "error": "email_not_verified" } } ] } ], "errorCodes": [ "email_not_verified", "market_intelligence_not_enabled" ] }, { "status": "404", "description": "No matching identifier, cluster, VIN or job is known.", "headers": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/responses/404/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "cluster_not_found", "snapshot_not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "cluster_not_found", "snapshot_not_found" ], "examples": [ { "name": "cluster_not_found", "value": { "error": "cluster_not_found", "message": "No known part cluster matches the requested scope.", "requestId": "ac6cffca-46e4-4fc8-8cd5-601892188c7c" } }, { "name": "snapshot_not_found", "value": { "error": "snapshot_not_found" } } ] } ], "errorCodes": [ "cluster_not_found", "snapshot_not_found" ] }, { "status": "409", "description": "The Idempotency-Key has already been used for a different business scope.", "headers": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/responses/409/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "idempotency_key_conflict" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict" } } ] } ], "errorCodes": [ "idempotency_key_conflict" ] }, { "status": "422", "description": "The input is ambiguous or invalid, or the required evidence tier is missing.", "headers": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/responses/422", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/responses/422/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_integer", "invalid_enum", "invalid_format", "invalid_instant", "insufficient_evidence", "refresh_unavailable" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "invalid_integer", "invalid_enum", "invalid_format", "invalid_instant", "insufficient_evidence", "refresh_unavailable" ], "examples": [ { "name": "invalid_integer", "value": { "error": "invalid_integer" } }, { "name": "invalid_enum", "value": { "error": "invalid_enum" } }, { "name": "invalid_format", "value": { "error": "invalid_format" } }, { "name": "invalid_instant", "value": { "error": "invalid_instant" } }, { "name": "insufficient_evidence", "value": { "error": "insufficient_evidence", "message": "The requested minimum evidence level is not available for this cluster.", "requestId": "52469176-c17a-4fa4-95c0-2e1d15745153", "details": { "requestedLevel": "usable", "availableLevel": "directional", "missingEvidence": [ "verified_sales:30", "contributors:10" ] } } }, { "name": "refresh_unavailable", "value": { "error": "refresh_unavailable" } } ] } ], "errorCodes": [ "insufficient_evidence", "invalid_enum", "invalid_format", "invalid_instant", "invalid_integer", "refresh_unavailable" ] }, { "status": "429", "description": "The shared tenant-wide per-minute limit across all API replicas has been reached.", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/responses/429/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limit_exceeded" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "rate_limit_exceeded" ], "examples": [ { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded" } } ] } ], "errorCodes": [ "rate_limit_exceeded" ] }, { "status": "503", "description": "The intelligence runtime or a required dependency is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get/responses/503/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "market_intelligence_unavailable" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } }, "exampleNames": [ "market_intelligence_unavailable" ], "examples": [ { "name": "market_intelligence_unavailable", "value": { "error": "market_intelligence_unavailable" } } ] } ], "errorCodes": [ "market_intelligence_unavailable" ] } ], "supportsIdempotencyKey": true, "asynchronous": true, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1intelligence/get" }, { "operationId": "getPartClusterIntelligenceHistory", "method": "GET", "path": "/parts/clusters/{clusterId}/history", "tags": [ "Intelligence" ], "summary": "Returns versioned historical intelligence snapshots", "description": "Historical data points retain the cluster and score versions that applied at the\ntime. The pilot returns only original snapshots. `restated=true` is reserved for\nfuture recalculation; pilot data points remain explicitly marked with\n`restated=false`.\n\n\nPilot availability: the paid production pilot is commercially closed. No real results are delivered without approved positive prices and atomic billing. Approved Observed Supply data and the authorised dealer panel are not yet available in production. Adaptive refresh and VIN economic analysis are disabled; scores remain `null` or `publishable=false` without sufficient evidence.", "authentication": [ { "apiKeyAuth": [] }, { "marketIntelligenceSessionCookie": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable key for exactly one business-level request. Without an approved positive price and atomic billing, the real-data path remains locked.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/parameters/0/schema", "schema": { "type": "string", "minLength": 16, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/parameters/0" }, { "name": "clusterId", "in": "path", "required": true, "description": "Stable ID of a part cluster; its composition is versioned separately.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/parameters/1/schema", "schema": { "type": "string", "format": "uuid" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/parameters/1" }, { "name": "marketCountry", "in": "query", "required": false, "description": null, "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/parameters/2/schema", "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "default": "DE" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/parameters/2" }, { "name": "currency", "in": "query", "required": false, "description": null, "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/parameters/3/schema", "schema": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "EUR" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/parameters/3" }, { "name": "condition", "in": "query", "required": false, "description": null, "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/parameters/4/schema", "schema": { "type": "string", "enum": [ "new", "remanufactured", "used", "unknown" ], "default": "used" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/parameters/4" }, { "name": "from", "in": "query", "required": true, "description": null, "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/parameters/5/schema", "schema": { "type": "string", "format": "date" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/parameters/5" }, { "name": "to", "in": "query", "required": true, "description": null, "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/parameters/6/schema", "schema": { "type": "string", "format": "date" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/parameters/6" }, { "name": "granularity", "in": "query", "required": false, "description": null, "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/parameters/7/schema", "schema": { "type": "string", "enum": [ "day", "week", "month" ], "default": "week" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/parameters/7" }, { "name": "restated", "in": "query", "required": false, "description": null, "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/parameters/8/schema", "schema": { "type": "boolean", "default": false }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/parameters/8" }, { "name": "minimumEvidence", "in": "query", "required": false, "description": "Required minimum coverage. `any` transparently returns known clusters even with\n`status=insufficient_evidence`; if a higher tier is not reached, the API returns\n`422 insufficient_evidence`.\n", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/parameters/9/schema", "schema": { "type": "string", "enum": [ "any", "directional", "usable", "strong" ], "default": "any" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/parameters/9" } ], "requestBody": null, "responses": [ { "status": "200", "description": "Historical, versioned snapshot series.", "headers": [ "X-Tapinoma-Idempotent-Replay" ], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/MarketIntelligenceClusterHistoryResponse", "schemaPointer": "#/components/schemas/MarketIntelligenceClusterHistoryResponse", "exampleNames": [], "examples": [] } ], "errorCodes": [] }, { "status": "400", "description": "The query, header or JSON body is syntactically invalid.", "headers": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/responses/400/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_query_parameter", "invalid_minimum_evidence", "invalid_idempotency_key" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "invalid_query_parameter", "invalid_minimum_evidence", "invalid_idempotency_key" ], "examples": [ { "name": "invalid_query_parameter", "value": { "error": "invalid_query_parameter", "details": { "parameter": "unknown" } } }, { "name": "invalid_minimum_evidence", "value": { "error": "invalid_minimum_evidence" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key" } } ] } ], "errorCodes": [ "invalid_idempotency_key", "invalid_minimum_evidence", "invalid_query_parameter" ] }, { "status": "401", "description": "The session or API key is missing, invalid or cannot be assigned unambiguously to a pilot account.", "headers": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/responses/401/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "authentication_required" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "authentication_required" ], "examples": [ { "name": "authentication_required", "value": { "error": "authentication_required" } } ] } ], "errorCodes": [ "authentication_required" ] }, { "status": "403", "description": "Pilot access is missing, the session email is unverified, or the CSRF proof is invalid for a session-authenticated POST request.", "headers": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/responses/403/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "market_intelligence_not_enabled", "email_not_verified" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "market_intelligence_not_enabled", "email_not_verified" ], "examples": [ { "name": "market_intelligence_not_enabled", "value": { "error": "market_intelligence_not_enabled" } }, { "name": "email_not_verified", "value": { "error": "email_not_verified" } } ] } ], "errorCodes": [ "email_not_verified", "market_intelligence_not_enabled" ] }, { "status": "404", "description": "No matching identifier, cluster, VIN or job is known.", "headers": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/responses/404/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "cluster_not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "cluster_not_found" ], "examples": [ { "name": "cluster_not_found", "value": { "error": "cluster_not_found", "message": "No known part cluster matches the requested scope.", "requestId": "ac6cffca-46e4-4fc8-8cd5-601892188c7c" } } ] } ], "errorCodes": [ "cluster_not_found" ] }, { "status": "409", "description": "The Idempotency-Key has already been used for a different business scope.", "headers": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/responses/409/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "idempotency_key_conflict" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict" } } ] } ], "errorCodes": [ "idempotency_key_conflict" ] }, { "status": "422", "description": "The input is ambiguous or invalid, or the required evidence tier is missing.", "headers": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/responses/422", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/responses/422/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_format", "invalid_enum", "invalid_date", "invalid_boolean", "invalid_history_window", "insufficient_evidence" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "invalid_format", "invalid_enum", "invalid_date", "invalid_boolean", "invalid_history_window", "insufficient_evidence" ], "examples": [ { "name": "invalid_format", "value": { "error": "invalid_format" } }, { "name": "invalid_enum", "value": { "error": "invalid_enum" } }, { "name": "invalid_date", "value": { "error": "invalid_date" } }, { "name": "invalid_boolean", "value": { "error": "invalid_boolean" } }, { "name": "invalid_history_window", "value": { "error": "invalid_history_window" } }, { "name": "insufficient_evidence", "value": { "error": "insufficient_evidence", "message": "The requested minimum evidence level is not available for this cluster.", "requestId": "52469176-c17a-4fa4-95c0-2e1d15745153", "details": { "requestedLevel": "usable", "availableLevel": "directional", "missingEvidence": [ "verified_sales:30", "contributors:10" ] } } } ] } ], "errorCodes": [ "insufficient_evidence", "invalid_boolean", "invalid_date", "invalid_enum", "invalid_format", "invalid_history_window" ] }, { "status": "429", "description": "The shared tenant-wide per-minute limit across all API replicas has been reached.", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/responses/429/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limit_exceeded" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "rate_limit_exceeded" ], "examples": [ { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded" } } ] } ], "errorCodes": [ "rate_limit_exceeded" ] }, { "status": "503", "description": "The intelligence runtime or a required dependency is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get/responses/503/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "market_intelligence_unavailable" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } }, "exampleNames": [ "market_intelligence_unavailable" ], "examples": [ { "name": "market_intelligence_unavailable", "value": { "error": "market_intelligence_unavailable" } } ] } ], "errorCodes": [ "market_intelligence_unavailable" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1parts~1clusters~1{clusterId}~1history/get" }, { "operationId": "getPartIntelligenceJob", "method": "GET", "path": "/parts/intelligence/jobs/{jobId}", "tags": [ "Intelligence" ], "summary": "Retrieves a cluster refresh", "description": "A completed job returns a cluster snapshot. While the job is running, the response\nremains 202 and does not create a second order. Status presentation is part of the paid\noriginal service and follows its agreed terms. In the pilot, history reads only snapshots\nthat have already been materialized and does not generate a backfill.\n\n\nPilot availability: the paid production pilot is commercially closed. No real results are delivered without approved positive prices and atomic billing. Approved Observed Supply data and the authorised dealer panel are not yet available in production. Adaptive refresh and VIN economic analysis are disabled; scores remain `null` or `publishable=false` without sufficient evidence.", "authentication": [ { "apiKeyAuth": [] }, { "marketIntelligenceSessionCookie": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": null, "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence~1jobs~1{jobId}/get/parameters/0/schema", "schema": { "type": "string", "format": "uuid" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1intelligence~1jobs~1{jobId}/get/parameters/0" } ], "requestBody": null, "responses": [ { "status": "200", "description": "The cluster refresh is complete.", "headers": [ "X-Tapinoma-Idempotent-Replay" ], "openApiPointer": "#/paths/~1parts~1intelligence~1jobs~1{jobId}/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/MarketIntelligenceClusterIntelligenceResponse", "schemaPointer": "#/components/schemas/MarketIntelligenceClusterIntelligenceResponse", "exampleNames": [], "examples": [] } ], "errorCodes": [] }, { "status": "202", "description": "A targeted refresh of a known cluster has been accepted.", "headers": [ "Location", "X-Tapinoma-Idempotent-Replay", "Retry-After" ], "openApiPointer": "#/paths/~1parts~1intelligence~1jobs~1{jobId}/get/responses/202", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/MarketIntelligenceAsyncAccepted", "schemaPointer": "#/components/schemas/MarketIntelligenceAsyncAccepted", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "requestId": "70b35c44-3bfa-45f5-98ee-c282f7ca4cb8", "jobId": "70b35c44-3bfa-45f5-98ee-c282f7ca4cb8", "status": "queued", "reason": "stale_snapshot", "requestedAt": "2026-09-11T13:40:00Z", "statusUrl": "https://api.tapinomahub.com/parts/intelligence/jobs/70b35c44-3bfa-45f5-98ee-c282f7ca4cb8" } } ] } ], "errorCodes": [] }, { "status": "400", "description": "The query, header or JSON body is syntactically invalid.", "headers": [], "openApiPointer": "#/paths/~1parts~1intelligence~1jobs~1{jobId}/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence~1jobs~1{jobId}/get/responses/400/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_query_parameter" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "invalid_query_parameter" ], "examples": [ { "name": "invalid_query_parameter", "value": { "error": "invalid_query_parameter", "details": { "parameter": "unknown" } } } ] } ], "errorCodes": [ "invalid_query_parameter" ] }, { "status": "401", "description": "The session or API key is missing, invalid or cannot be assigned unambiguously to a pilot account.", "headers": [], "openApiPointer": "#/paths/~1parts~1intelligence~1jobs~1{jobId}/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence~1jobs~1{jobId}/get/responses/401/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "authentication_required" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "authentication_required" ], "examples": [ { "name": "authentication_required", "value": { "error": "authentication_required" } } ] } ], "errorCodes": [ "authentication_required" ] }, { "status": "403", "description": "Pilot access is missing, the session email is unverified, or the CSRF proof is invalid for a session-authenticated POST request.", "headers": [], "openApiPointer": "#/paths/~1parts~1intelligence~1jobs~1{jobId}/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence~1jobs~1{jobId}/get/responses/403/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "market_intelligence_not_enabled", "email_not_verified" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "market_intelligence_not_enabled", "email_not_verified" ], "examples": [ { "name": "market_intelligence_not_enabled", "value": { "error": "market_intelligence_not_enabled" } }, { "name": "email_not_verified", "value": { "error": "email_not_verified" } } ] } ], "errorCodes": [ "email_not_verified", "market_intelligence_not_enabled" ] }, { "status": "404", "description": "No matching identifier, cluster, VIN or job is known.", "headers": [], "openApiPointer": "#/paths/~1parts~1intelligence~1jobs~1{jobId}/get/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence~1jobs~1{jobId}/get/responses/404/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "job_not_found", "snapshot_not_found", "cluster_not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "job_not_found", "snapshot_not_found", "cluster_not_found" ], "examples": [ { "name": "job_not_found", "value": { "error": "job_not_found" } }, { "name": "snapshot_not_found", "value": { "error": "snapshot_not_found" } }, { "name": "cluster_not_found", "value": { "error": "cluster_not_found", "message": "No known part cluster matches the requested scope.", "requestId": "ac6cffca-46e4-4fc8-8cd5-601892188c7c" } } ] } ], "errorCodes": [ "cluster_not_found", "job_not_found", "snapshot_not_found" ] }, { "status": "422", "description": "The input is ambiguous or invalid, or the required evidence tier is missing.", "headers": [], "openApiPointer": "#/paths/~1parts~1intelligence~1jobs~1{jobId}/get/responses/422", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence~1jobs~1{jobId}/get/responses/422/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "intelligence_job_failed", "refresh_timeout", "insufficient_evidence", "refresh_failed", "refresh_completed_without_snapshot", "refresh_job_missing" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "intelligence_job_failed", "refresh_timeout", "insufficient_evidence", "refresh_failed", "refresh_completed_without_snapshot", "refresh_job_missing" ], "examples": [ { "name": "intelligence_job_failed", "value": { "error": "intelligence_job_failed" } }, { "name": "refresh_timeout", "value": { "error": "refresh_timeout" } }, { "name": "insufficient_evidence", "value": { "error": "insufficient_evidence", "message": "The requested minimum evidence level is not available for this cluster.", "requestId": "52469176-c17a-4fa4-95c0-2e1d15745153", "details": { "requestedLevel": "usable", "availableLevel": "directional", "missingEvidence": [ "verified_sales:30", "contributors:10" ] } } }, { "name": "refresh_failed", "value": { "error": "refresh_failed" } }, { "name": "refresh_completed_without_snapshot", "value": { "error": "refresh_completed_without_snapshot" } }, { "name": "refresh_job_missing", "value": { "error": "refresh_job_missing" } } ] } ], "errorCodes": [ "insufficient_evidence", "intelligence_job_failed", "refresh_completed_without_snapshot", "refresh_failed", "refresh_job_missing", "refresh_timeout" ] }, { "status": "429", "description": "The shared tenant-wide per-minute limit across all API replicas has been reached.", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1parts~1intelligence~1jobs~1{jobId}/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence~1jobs~1{jobId}/get/responses/429/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limit_exceeded" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "rate_limit_exceeded" ], "examples": [ { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded" } } ] } ], "errorCodes": [ "rate_limit_exceeded" ] }, { "status": "503", "description": "The intelligence runtime or a required dependency is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1parts~1intelligence~1jobs~1{jobId}/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1intelligence~1jobs~1{jobId}/get/responses/503/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "market_intelligence_unavailable" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } }, "exampleNames": [ "market_intelligence_unavailable" ], "examples": [ { "name": "market_intelligence_unavailable", "value": { "error": "market_intelligence_unavailable" } } ] } ], "errorCodes": [ "market_intelligence_unavailable" ] } ], "supportsIdempotencyKey": false, "asynchronous": true, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1parts~1intelligence~1jobs~1{jobId}/get" }, { "operationId": "createVinEconomicIntelligence", "method": "POST", "path": "/vin/economic-intelligence", "tags": [ "Intelligence" ], "summary": "Aggregates vehicle-specific part candidates across part clusters into Economic Intelligence", "description": "Pipeline: VIN -> vehicle-specific part candidates -> versioned part cluster -> materialized\ncluster intelligence -> risk-adjusted vehicle aggregation. The VIN is stored neither in the\nURL nor in public market snapshots. The route is deployed in the production pilot\nbut remains disabled fail-closed until the single-dispatch and billing reconciliation\ngate has been passed.\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.\n\n\nPilot availability: the paid production pilot is commercially closed. No real results are delivered without approved positive prices and atomic billing. Approved Observed Supply data and the authorised dealer panel are not yet available in production. Adaptive refresh and VIN economic analysis are disabled; scores remain `null` or `publishable=false` without sufficient evidence.", "authentication": [ { "apiKeyAuth": [] }, { "marketIntelligenceSessionCookie": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable key for exactly one business-level request. Without an approved positive price and atomic billing, the real-data path remains locked.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence/post/parameters/0/schema", "schema": { "type": "string", "minLength": 16, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1vin~1economic-intelligence/post/parameters/0" }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for POST requests authenticated by session cookie; not required with a server-side X-Api-Key.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence/post/parameters/1/schema", "schema": { "type": "string" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1vin~1economic-intelligence/post/parameters/1" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/MarketIntelligenceVinEconomicIntelligenceRequest", "schemaPointer": "#/components/schemas/MarketIntelligenceVinEconomicIntelligenceRequest", "exampleNames": [], "examples": [] } ] }, "responses": [ { "status": "200", "description": "Complete or partial VIN Economic Intelligence.", "headers": [ "X-Tapinoma-Idempotent-Replay" ], "openApiPointer": "#/paths/~1vin~1economic-intelligence/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/MarketIntelligenceVinEconomicIntelligenceResponse", "schemaPointer": "#/components/schemas/MarketIntelligenceVinEconomicIntelligenceResponse", "exampleNames": [], "examples": [] } ], "errorCodes": [] }, { "status": "202", "description": "Vehicle-specific parts determination or intelligence aggregation is running asynchronously.", "headers": [ "Location", "X-Tapinoma-Idempotent-Replay", "Retry-After" ], "openApiPointer": "#/paths/~1vin~1economic-intelligence/post/responses/202", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/MarketIntelligenceAsyncAccepted", "schemaPointer": "#/components/schemas/MarketIntelligenceAsyncAccepted", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "requestId": "25f697c2-0675-4560-8d83-43169ce42e84", "jobId": "25f697c2-0675-4560-8d83-43169ce42e84", "status": "running", "reason": "vehicle_parts_pending", "requestedAt": "2026-09-11T13:40:00Z", "statusUrl": "https://api.tapinomahub.com/vin/economic-intelligence/jobs/25f697c2-0675-4560-8d83-43169ce42e84" } } ] } ], "errorCodes": [] }, { "status": "400", "description": "The query, header or JSON body is syntactically invalid.", "headers": [], "openApiPointer": "#/paths/~1vin~1economic-intelligence/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence/post/responses/400/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_query_parameter", "invalid_request_property", "invalid_json", "invalid_json_object", "invalid_minimum_evidence", "invalid_idempotency_key" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "invalid_query_parameter", "invalid_request_property", "invalid_json", "invalid_json_object", "invalid_minimum_evidence", "invalid_idempotency_key" ], "examples": [ { "name": "invalid_query_parameter", "value": { "error": "invalid_query_parameter", "details": { "parameter": "unknown" } } }, { "name": "invalid_request_property", "value": { "error": "invalid_request_property" } }, { "name": "invalid_json", "value": { "error": "invalid_json" } }, { "name": "invalid_json_object", "value": { "error": "invalid_json_object" } }, { "name": "invalid_minimum_evidence", "value": { "error": "invalid_minimum_evidence" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key" } } ] } ], "errorCodes": [ "invalid_idempotency_key", "invalid_json", "invalid_json_object", "invalid_minimum_evidence", "invalid_query_parameter", "invalid_request_property" ] }, { "status": "401", "description": "The session or API key is missing, invalid or cannot be assigned unambiguously to a pilot account.", "headers": [], "openApiPointer": "#/paths/~1vin~1economic-intelligence/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence/post/responses/401/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "authentication_required" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "authentication_required" ], "examples": [ { "name": "authentication_required", "value": { "error": "authentication_required" } } ] } ], "errorCodes": [ "authentication_required" ] }, { "status": "403", "description": "Pilot access is missing, the session email is unverified, or the CSRF proof is invalid for a session-authenticated POST request.", "headers": [], "openApiPointer": "#/paths/~1vin~1economic-intelligence/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence/post/responses/403/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "market_intelligence_not_enabled", "invalid_csrf", "email_not_verified" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "market_intelligence_not_enabled", "invalid_csrf", "email_not_verified" ], "examples": [ { "name": "market_intelligence_not_enabled", "value": { "error": "market_intelligence_not_enabled" } }, { "name": "invalid_csrf", "value": { "error": "invalid_csrf" } }, { "name": "email_not_verified", "value": { "error": "email_not_verified" } } ] } ], "errorCodes": [ "email_not_verified", "invalid_csrf", "market_intelligence_not_enabled" ] }, { "status": "404", "description": "No matching identifier, cluster, VIN or job is known.", "headers": [], "openApiPointer": "#/paths/~1vin~1economic-intelligence/post/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence/post/responses/404/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "vin_not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "vin_not_found" ], "examples": [ { "name": "vin_not_found", "value": { "error": "vin_not_found", "message": "No vehicle parts result is available for this VIN.", "requestId": "8d918ef4-627b-4c66-a558-403b0e326355" } } ] } ], "errorCodes": [ "vin_not_found" ] }, { "status": "409", "description": "The Idempotency-Key has already been used for a different business scope.", "headers": [], "openApiPointer": "#/paths/~1vin~1economic-intelligence/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence/post/responses/409/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "idempotency_key_conflict" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict" } } ] } ], "errorCodes": [ "idempotency_key_conflict" ] }, { "status": "413", "description": "The JSON body exceeds the pilot limit of 32 KiB.", "headers": [], "openApiPointer": "#/paths/~1vin~1economic-intelligence/post/responses/413", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence/post/responses/413/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "request_body_too_large" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "request_body_too_large" ], "examples": [ { "name": "request_body_too_large", "value": { "error": "request_body_too_large" } } ] } ], "errorCodes": [ "request_body_too_large" ] }, { "status": "415", "description": "The VIN request must be sent as `application/json`.", "headers": [], "openApiPointer": "#/paths/~1vin~1economic-intelligence/post/responses/415", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence/post/responses/415/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unsupported_media_type" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "unsupported_media_type" ], "examples": [ { "name": "unsupported_media_type", "value": { "error": "unsupported_media_type" } } ] } ], "errorCodes": [ "unsupported_media_type" ] }, { "status": "422", "description": "The input is ambiguous or invalid, or the required evidence tier is missing.", "headers": [], "openApiPointer": "#/paths/~1vin~1economic-intelligence/post/responses/422", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence/post/responses/422/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_vin", "invalid_format", "invalid_enum", "invalid_instant", "invalid_integer", "invalid_string", "invalid_boolean" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "invalid_vin", "invalid_format", "invalid_enum", "invalid_instant", "invalid_integer", "invalid_string", "invalid_boolean" ], "examples": [ { "name": "invalid_vin", "value": { "error": "invalid_vin" } }, { "name": "invalid_format", "value": { "error": "invalid_format" } }, { "name": "invalid_enum", "value": { "error": "invalid_enum" } }, { "name": "invalid_instant", "value": { "error": "invalid_instant" } }, { "name": "invalid_integer", "value": { "error": "invalid_integer" } }, { "name": "invalid_string", "value": { "error": "invalid_string" } }, { "name": "invalid_boolean", "value": { "error": "invalid_boolean" } } ] } ], "errorCodes": [ "invalid_boolean", "invalid_enum", "invalid_format", "invalid_instant", "invalid_integer", "invalid_string", "invalid_vin" ] }, { "status": "429", "description": "The shared tenant-wide per-minute limit across all API replicas has been reached.", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vin~1economic-intelligence/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence/post/responses/429/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limit_exceeded" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "rate_limit_exceeded" ], "examples": [ { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded" } } ] } ], "errorCodes": [ "rate_limit_exceeded" ] }, { "status": "502", "description": "The vehicle-specific parts determination could not be completed.", "headers": [], "openApiPointer": "#/paths/~1vin~1economic-intelligence/post/responses/502", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence/post/responses/502/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_vehicle_parts_response" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } }, "exampleNames": [ "invalid_vehicle_parts_response" ], "examples": [ { "name": "invalid_vehicle_parts_response", "value": { "error": "invalid_vehicle_parts_response" } } ] } ], "errorCodes": [ "invalid_vehicle_parts_response" ] }, { "status": "503", "description": "VIN Intelligence is safely disabled or vehicle-specific parts determination is unavailable.", "headers": [], "openApiPointer": "#/paths/~1vin~1economic-intelligence/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence/post/responses/503/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "market_intelligence_vin_not_enabled", "vehicle_parts_unavailable", "market_intelligence_dependency_unavailable", "market_intelligence_unavailable" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } }, "exampleNames": [ "market_intelligence_vin_not_enabled", "vehicle_parts_unavailable", "market_intelligence_dependency_unavailable", "market_intelligence_unavailable" ], "examples": [ { "name": "market_intelligence_vin_not_enabled", "value": { "error": "market_intelligence_vin_not_enabled" } }, { "name": "vehicle_parts_unavailable", "value": { "error": "vehicle_parts_unavailable" } }, { "name": "market_intelligence_dependency_unavailable", "value": { "error": "market_intelligence_dependency_unavailable" } }, { "name": "market_intelligence_unavailable", "value": { "error": "market_intelligence_unavailable" } } ] } ], "errorCodes": [ "market_intelligence_dependency_unavailable", "market_intelligence_unavailable", "market_intelligence_vin_not_enabled", "vehicle_parts_unavailable" ] } ], "supportsIdempotencyKey": true, "asynchronous": true, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vin~1economic-intelligence/post" }, { "operationId": "getVinEconomicIntelligenceJob", "method": "GET", "path": "/vin/economic-intelligence/jobs/{jobId}", "tags": [ "Intelligence" ], "summary": "Retrieves the status or result of a VIN intelligence job", "description": "Retrieves only the request started with `POST /vin/economic-intelligence`. While\nprocessing is still running, the route returns 202; afterwards it returns the result\nwith 200. The status query is part of the paid original service, creates no second order,\nand uses the same UUID exposed by the original request as `requestId` and `jobId`.\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.\n\n\nPilot availability: the paid production pilot is commercially closed. No real results are delivered without approved positive prices and atomic billing. Approved Observed Supply data and the authorised dealer panel are not yet available in production. Adaptive refresh and VIN economic analysis are disabled; scores remain `null` or `publishable=false` without sufficient evidence.", "authentication": [ { "apiKeyAuth": [] }, { "marketIntelligenceSessionCookie": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": null, "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence~1jobs~1{jobId}/get/parameters/0/schema", "schema": { "type": "string", "format": "uuid" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1vin~1economic-intelligence~1jobs~1{jobId}/get/parameters/0" } ], "requestBody": null, "responses": [ { "status": "200", "description": "The job is complete; the result is available.", "headers": [ "X-Tapinoma-Idempotent-Replay" ], "openApiPointer": "#/paths/~1vin~1economic-intelligence~1jobs~1{jobId}/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/MarketIntelligenceVinEconomicIntelligenceResponse", "schemaPointer": "#/components/schemas/MarketIntelligenceVinEconomicIntelligenceResponse", "exampleNames": [], "examples": [] } ], "errorCodes": [] }, { "status": "202", "description": "Vehicle-specific parts determination or intelligence aggregation is running asynchronously.", "headers": [ "Location", "X-Tapinoma-Idempotent-Replay", "Retry-After" ], "openApiPointer": "#/paths/~1vin~1economic-intelligence~1jobs~1{jobId}/get/responses/202", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/MarketIntelligenceAsyncAccepted", "schemaPointer": "#/components/schemas/MarketIntelligenceAsyncAccepted", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "requestId": "25f697c2-0675-4560-8d83-43169ce42e84", "jobId": "25f697c2-0675-4560-8d83-43169ce42e84", "status": "running", "reason": "vehicle_parts_pending", "requestedAt": "2026-09-11T13:40:00Z", "statusUrl": "https://api.tapinomahub.com/vin/economic-intelligence/jobs/25f697c2-0675-4560-8d83-43169ce42e84" } } ] } ], "errorCodes": [] }, { "status": "400", "description": "The query, header or JSON body is syntactically invalid.", "headers": [], "openApiPointer": "#/paths/~1vin~1economic-intelligence~1jobs~1{jobId}/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence~1jobs~1{jobId}/get/responses/400/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_query_parameter" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "invalid_query_parameter" ], "examples": [ { "name": "invalid_query_parameter", "value": { "error": "invalid_query_parameter", "details": { "parameter": "unknown" } } } ] } ], "errorCodes": [ "invalid_query_parameter" ] }, { "status": "401", "description": "The session or API key is missing, invalid or cannot be assigned unambiguously to a pilot account.", "headers": [], "openApiPointer": "#/paths/~1vin~1economic-intelligence~1jobs~1{jobId}/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence~1jobs~1{jobId}/get/responses/401/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "authentication_required" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "authentication_required" ], "examples": [ { "name": "authentication_required", "value": { "error": "authentication_required" } } ] } ], "errorCodes": [ "authentication_required" ] }, { "status": "403", "description": "Pilot access is missing, the session email is unverified, or the CSRF proof is invalid for a session-authenticated POST request.", "headers": [], "openApiPointer": "#/paths/~1vin~1economic-intelligence~1jobs~1{jobId}/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence~1jobs~1{jobId}/get/responses/403/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "market_intelligence_not_enabled", "email_not_verified" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "market_intelligence_not_enabled", "email_not_verified" ], "examples": [ { "name": "market_intelligence_not_enabled", "value": { "error": "market_intelligence_not_enabled" } }, { "name": "email_not_verified", "value": { "error": "email_not_verified" } } ] } ], "errorCodes": [ "email_not_verified", "market_intelligence_not_enabled" ] }, { "status": "404", "description": "No matching identifier, cluster, VIN or job is known.", "headers": [], "openApiPointer": "#/paths/~1vin~1economic-intelligence~1jobs~1{jobId}/get/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence~1jobs~1{jobId}/get/responses/404/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "job_not_found", "vin_not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "job_not_found", "vin_not_found" ], "examples": [ { "name": "job_not_found", "value": { "error": "job_not_found" } }, { "name": "vin_not_found", "value": { "error": "vin_not_found", "message": "No vehicle parts result is available for this VIN.", "requestId": "8d918ef4-627b-4c66-a558-403b0e326355" } } ] } ], "errorCodes": [ "job_not_found", "vin_not_found" ] }, { "status": "422", "description": "The input is ambiguous or invalid, or the required evidence tier is missing.", "headers": [], "openApiPointer": "#/paths/~1vin~1economic-intelligence~1jobs~1{jobId}/get/responses/422", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence~1jobs~1{jobId}/get/responses/422/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "vin_intelligence_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "vin_intelligence_failed" ], "examples": [ { "name": "vin_intelligence_failed", "value": { "error": "vin_intelligence_failed" } } ] } ], "errorCodes": [ "vin_intelligence_failed" ] }, { "status": "429", "description": "The shared tenant-wide per-minute limit across all API replicas has been reached.", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vin~1economic-intelligence~1jobs~1{jobId}/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence~1jobs~1{jobId}/get/responses/429/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limit_exceeded" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "exampleNames": [ "rate_limit_exceeded" ], "examples": [ { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded" } } ] } ], "errorCodes": [ "rate_limit_exceeded" ] }, { "status": "502", "description": "The vehicle-specific parts determination could not be completed.", "headers": [], "openApiPointer": "#/paths/~1vin~1economic-intelligence~1jobs~1{jobId}/get/responses/502", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence~1jobs~1{jobId}/get/responses/502/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_vehicle_parts_response" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } }, "exampleNames": [ "invalid_vehicle_parts_response" ], "examples": [ { "name": "invalid_vehicle_parts_response", "value": { "error": "invalid_vehicle_parts_response" } } ] } ], "errorCodes": [ "invalid_vehicle_parts_response" ] }, { "status": "503", "description": "VIN Intelligence is safely disabled or vehicle-specific parts determination is unavailable.", "headers": [], "openApiPointer": "#/paths/~1vin~1economic-intelligence~1jobs~1{jobId}/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-intelligence~1jobs~1{jobId}/get/responses/503/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "market_intelligence_vin_not_enabled", "vehicle_parts_unavailable", "market_intelligence_dependency_unavailable", "market_intelligence_unavailable" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } }, "exampleNames": [ "market_intelligence_vin_not_enabled", "vehicle_parts_unavailable", "market_intelligence_dependency_unavailable", "market_intelligence_unavailable" ], "examples": [ { "name": "market_intelligence_vin_not_enabled", "value": { "error": "market_intelligence_vin_not_enabled" } }, { "name": "vehicle_parts_unavailable", "value": { "error": "vehicle_parts_unavailable" } }, { "name": "market_intelligence_dependency_unavailable", "value": { "error": "market_intelligence_dependency_unavailable" } }, { "name": "market_intelligence_unavailable", "value": { "error": "market_intelligence_unavailable" } } ] } ], "errorCodes": [ "market_intelligence_dependency_unavailable", "market_intelligence_unavailable", "market_intelligence_vin_not_enabled", "vehicle_parts_unavailable" ] } ], "supportsIdempotencyKey": false, "asynchronous": true, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vin~1economic-intelligence~1jobs~1{jobId}/get" }, { "operationId": "getSystemStatus", "method": "GET", "path": "/ping", "tags": [ "System" ], "summary": "Check system status", "description": "**Service description**\n\nChecks API availability and returns a compact technical status. The endpoint performs no business data query.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [], "requestBody": null, "responses": [ { "status": "200", "description": "API system status", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1ping/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/PingResponse", "schemaPointer": "#/components/schemas/PingResponse", "exampleNames": [ "documented" ], "examples": [ { "name": "documented", "value": { "status": "ok", "service": "tapinoma hub" } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [], "openApiPointer": "#/paths/~1ping/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1ping/get/responses/400/content/application~1json/schema", "schema": { "title": "GetSystemStatus400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } ] } ], "errorCodes": [ "idempotency_key_not_supported" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1ping/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1ping/get/responses/401/content/application~1json/schema", "schema": { "title": "GetSystemStatus401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1ping/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1ping/get/responses/403/content/application~1json/schema", "schema": { "title": "GetSystemStatus403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "invalid_api_key" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1ping/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1ping/get/responses/429/content/application~1json/schema", "schema": { "title": "GetSystemStatus429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [], "openApiPointer": "#/paths/~1ping/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1ping/get/responses/500/content/application~1json/schema", "schema": { "title": "GetSystemStatus500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1ping/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1ping/get/responses/503/content/application~1json/schema", "schema": { "title": "GetSystemStatus503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1ping/get" }, { "operationId": "listClientUsers", "method": "GET", "path": "/client/users", "tags": [ "Client Admin" ], "summary": "List sub-users of the current master client", "description": "**Service description**\n\nReturns the authenticated master client’s managed sub-users and the status required for administration.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [], "requestBody": null, "responses": [ { "status": "200", "description": "Sub-user list", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users/get/responses/200/content/application~1json/schema", "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/ClientUser" } } } }, "exampleNames": [ "documented" ], "examples": [ { "name": "documented", "value": { "users": [ { "id": 4711, "name": "Werkstatt Nord GmbH", "isActive": true, "defaultProviderId": 1, "balanceCents": 12500, "balance": "125.00", "currency": "EUR", "planAssignments": [ { "endpointKey": "vin.vehicle", "id": 7, "code": "VIN_BASIC", "name": "VIN Basic" } ], "apiKeyCount": 2, "createdAt": "2026-05-04T09:12:33+00:00" } ] } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [], "openApiPointer": "#/paths/~1client~1users/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users/get/responses/400/content/application~1json/schema", "schema": { "title": "ListClientUsers400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } ] } ], "errorCodes": [ "idempotency_key_not_supported" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1client~1users/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users/get/responses/401/content/application~1json/schema", "schema": { "title": "ListClientUsers401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "Only master clients may manage sub-users", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users/get/responses/403/content/application~1json/schema", "schema": { "title": "ListClientUsers403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "forbidden", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "forbidden", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "forbidden", "invalid_api_key" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1client~1users/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users/get/responses/429/content/application~1json/schema", "schema": { "title": "ListClientUsers429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users/get/responses/500/content/application~1json/schema", "schema": { "title": "ListClientUsers500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1client~1users/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users/get/responses/503/content/application~1json/schema", "schema": { "title": "ListClientUsers503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1client~1users/get" }, { "operationId": "createClientUser", "method": "POST", "path": "/client/users", "tags": [ "Client Admin" ], "summary": "Create a sub-user with an initial API key", "description": "**Service description**\n\nCreate a sub-user with an initial API key. The request and response follow the schemas documented below.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/ClientUserCreateRequest", "schemaPointer": "#/components/schemas/ClientUserCreateRequest", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "name": "Werkstatt Nord GmbH", "defaultProviderId": 1, "isActive": true, "applicationLabel": "erp-connector", "rateLimits": [ { "endpointKey": "vin.vehicle", "windowSeconds": 60, "maxRequests": 120, "isActive": true } ] } } ] } ] }, "responses": [ { "status": "201", "description": "Sub-user created; the raw API key is returned once", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users/post/responses/201", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users/post/responses/201/content/application~1json/schema", "schema": { "type": "object", "required": [ "user", "apiKey" ], "properties": { "user": { "$ref": "#/components/schemas/ClientUser" }, "apiKey": { "$ref": "#/components/schemas/ApiKeyCreateResponse" } } }, "exampleNames": [ "documented" ], "examples": [ { "name": "documented", "value": { "user": { "id": 4711, "name": "Werkstatt Nord GmbH", "isActive": true, "defaultProviderId": 1, "parentClientId": 1001, "role": "user", "balanceCents": 0, "balance": "0.00", "currency": "EUR", "createdAt": "2026-08-18T10:04:11+00:00" }, "apiKey": { "id": 9821, "label": "erp-connector", "key": "tap_2f8b9c1d0e4a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e", "createdAt": "2026-08-18T10:04:11+00:00" } } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users/post/responses/400/content/application~1json/schema", "schema": { "title": "CreateClientUser400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "idempotency_key_not_supported" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } ] } ], "errorCodes": [ "bad_request", "idempotency_key_not_supported" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1client~1users/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users/post/responses/401/content/application~1json/schema", "schema": { "title": "CreateClientUser401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "Only master clients may manage sub-users", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users/post/responses/403/content/application~1json/schema", "schema": { "title": "CreateClientUser403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "forbidden", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "forbidden", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "forbidden", "invalid_api_key" ] }, { "status": "404", "description": "Not found", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users/post/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users/post/responses/404/content/application~1json/schema", "schema": { "title": "CreateClientUser404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "not_found", "message": "No record matches the given identifier" } } ] } ], "errorCodes": [ "not_found" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1client~1users/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users/post/responses/429/content/application~1json/schema", "schema": { "title": "CreateClientUser429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users/post/responses/500/content/application~1json/schema", "schema": { "title": "CreateClientUser500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1client~1users/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users/post/responses/503/content/application~1json/schema", "schema": { "title": "CreateClientUser503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1client~1users/post" }, { "operationId": "updateClientUser", "method": "PATCH", "path": "/client/users/{clientId}", "tags": [ "Client Admin" ], "summary": "Update or deactivate a sub-user", "description": "**Service description**\n\nChanges permitted master data or the active status of a managed sub-user.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "Unique ID of a managed sub-user.", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}/patch/parameters/0/schema", "schema": { "type": "integer" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": 4711 } ], "openApiPointer": "#/paths/~1client~1users~1{clientId}/patch/parameters/0" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}/patch/parameters/1/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1client~1users~1{clientId}/patch/parameters/1" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/ClientUserUpdateRequest", "schemaPointer": "#/components/schemas/ClientUserUpdateRequest", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "name": "Werkstatt Nord GmbH & Co. KG", "isActive": true, "defaultProviderId": 2 } } ] } ] }, "responses": [ { "status": "200", "description": "Sub-user updated", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Idempotency-Stored" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}/patch/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}/patch/responses/200/content/application~1json/schema", "schema": { "type": "object", "required": [ "user" ], "properties": { "user": { "$ref": "#/components/schemas/ClientUser" } } }, "exampleNames": [ "documented" ], "examples": [ { "name": "documented", "value": { "user": { "id": 4711, "name": "Werkstatt Nord GmbH & Co. KG", "isActive": true, "defaultProviderId": 2, "parentClientId": 1001, "role": "user", "balanceCents": 12500, "balance": "125.00", "currency": "EUR", "createdAt": "2026-08-18T10:04:11+00:00" } } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [], "openApiPointer": "#/paths/~1client~1users~1{clientId}/patch/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}/patch/responses/400/content/application~1json/schema", "schema": { "title": "UpdateClientUser400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1client~1users~1{clientId}/patch/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}/patch/responses/401/content/application~1json/schema", "schema": { "title": "UpdateClientUser401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "Invalid API key", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}/patch/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}/patch/responses/403/content/application~1json/schema", "schema": { "title": "UpdateClientUser403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "forbidden", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "forbidden", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "forbidden", "invalid_api_key" ] }, { "status": "404", "description": "Sub-user not found", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}/patch/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}/patch/responses/404/content/application~1json/schema", "schema": { "title": "UpdateClientUser404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "not_found", "message": "No record matches the given identifier" } } ] } ], "errorCodes": [ "not_found" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}/patch/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}/patch/responses/409/content/application~1json/schema", "schema": { "title": "UpdateClientUser409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}/patch/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}/patch/responses/429/content/application~1json/schema", "schema": { "title": "UpdateClientUser429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}/patch/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}/patch/responses/500/content/application~1json/schema", "schema": { "title": "UpdateClientUser500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1client~1users~1{clientId}/patch/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}/patch/responses/503/content/application~1json/schema", "schema": { "title": "UpdateClientUser503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1client~1users~1{clientId}/patch" }, { "operationId": "createClientUserApiKey", "method": "POST", "path": "/client/users/{clientId}/keys", "tags": [ "Client Admin" ], "summary": "Create another API key for a sub-user", "description": "**Service description**\n\nCreate another API key for a sub-user. The request and response follow the schemas documented below.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "Unique ID of a managed sub-user.", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1keys/post/parameters/0/schema", "schema": { "type": "integer" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": 4711 } ], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1keys/post/parameters/0" } ], "requestBody": { "required": false, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/ApiKeyCreateRequest", "schemaPointer": "#/components/schemas/ApiKeyCreateRequest", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "label": "erp-connector-2" } } ] } ] }, "responses": [ { "status": "201", "description": "API key created", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1keys/post/responses/201", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1keys/post/responses/201/content/application~1json/schema", "schema": { "type": "object", "properties": { "apiKey": { "$ref": "#/components/schemas/ApiKeyCreateResponse" } } }, "exampleNames": [ "documented" ], "examples": [ { "name": "documented", "value": { "apiKey": { "id": 9822, "label": "erp-connector-2", "key": "tap_7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a09f8e", "createdAt": "2026-08-18T11:20:05+00:00" } } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1keys/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1keys/post/responses/400/content/application~1json/schema", "schema": { "title": "CreateClientUserApiKey400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } ] } ], "errorCodes": [ "idempotency_key_not_supported" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1keys/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1keys/post/responses/401/content/application~1json/schema", "schema": { "title": "CreateClientUserApiKey401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "Invalid API key", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1keys/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1keys/post/responses/403/content/application~1json/schema", "schema": { "title": "CreateClientUserApiKey403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "forbidden", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "forbidden", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "forbidden", "invalid_api_key" ] }, { "status": "404", "description": "Not found", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1keys/post/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1keys/post/responses/404/content/application~1json/schema", "schema": { "title": "CreateClientUserApiKey404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "not_found", "message": "No record matches the given identifier" } } ] } ], "errorCodes": [ "not_found" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1keys/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1keys/post/responses/429/content/application~1json/schema", "schema": { "title": "CreateClientUserApiKey429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1keys/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1keys/post/responses/500/content/application~1json/schema", "schema": { "title": "CreateClientUserApiKey500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1keys/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1keys/post/responses/503/content/application~1json/schema", "schema": { "title": "CreateClientUserApiKey503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1client~1users~1{clientId}~1keys/post" }, { "operationId": "replaceClientUserRateLimits", "method": "PUT", "path": "/client/users/{clientId}/rate-limits", "tags": [ "Client Admin" ], "summary": "Replace rate limits for a sub-user", "description": "**Service description**\\n\\nSets the documented rate limits for a sub-user from the submitted configuration.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "Unique ID of a managed sub-user.", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/parameters/0/schema", "schema": { "type": "integer" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": 4711 } ], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/parameters/0" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/parameters/1/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/parameters/1" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/requestBody/content/application~1json/schema", "schema": { "type": "object", "required": [ "rateLimits" ], "properties": { "rateLimits": { "type": "array", "items": { "$ref": "#/components/schemas/RateLimitInput" } } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "rateLimits": [ { "endpointKey": "vin.vehicle", "windowSeconds": 60, "maxRequests": 120, "isActive": true }, { "apiKeyId": 9821, "endpointKey": "parts.oe", "windowSeconds": 3600, "maxRequests": 5000, "isActive": true } ] } } ] } ] }, "responses": [ { "status": "200", "description": "Rate limits replaced", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/responses/200/content/application~1json/schema", "schema": { "type": "object", "properties": { "rateLimits": { "type": "array", "items": { "$ref": "#/components/schemas/RateLimit" } } } }, "exampleNames": [ "documented" ], "examples": [ { "name": "documented", "value": { "rateLimits": [ { "id": 331, "clientId": 4711, "apiKeyId": null, "endpointKey": "vin.vehicle", "windowSeconds": 60, "maxRequests": 120, "isActive": true, "createdAt": "2026-08-18T11:41:02+00:00" }, { "id": 332, "clientId": 4711, "apiKeyId": 9821, "endpointKey": "parts.oe", "windowSeconds": 3600, "maxRequests": 5000, "isActive": true, "createdAt": "2026-08-18T11:41:02+00:00" } ] } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/responses/400/content/application~1json/schema", "schema": { "title": "ReplaceClientUserRateLimits400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key", "unsupported_rate_limit_window" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key", "unsupported_rate_limit_window" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } }, { "name": "unsupported_rate_limit_window", "value": { "error": "unsupported_rate_limit_window", "message": "windowSeconds must be one of the windows the operator defines" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key", "unsupported_rate_limit_window" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/responses/401/content/application~1json/schema", "schema": { "title": "ReplaceClientUserRateLimits401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "Invalid API key", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/responses/403/content/application~1json/schema", "schema": { "title": "ReplaceClientUserRateLimits403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "forbidden", "invalid_api_key", "rate_limit_above_operator_default" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "forbidden", "invalid_api_key", "rate_limit_above_operator_default" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } }, { "name": "rate_limit_above_operator_default", "value": { "error": "rate_limit_above_operator_default", "message": "A rate limit must not exceed the operator default" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "forbidden", "invalid_api_key", "rate_limit_above_operator_default" ] }, { "status": "404", "description": "Not found", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/responses/404/content/application~1json/schema", "schema": { "title": "ReplaceClientUserRateLimits404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "not_found", "message": "No record matches the given identifier" } } ] } ], "errorCodes": [ "not_found" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/responses/409/content/application~1json/schema", "schema": { "title": "ReplaceClientUserRateLimits409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/responses/429/content/application~1json/schema", "schema": { "title": "ReplaceClientUserRateLimits429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/responses/500/content/application~1json/schema", "schema": { "title": "ReplaceClientUserRateLimits500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put/responses/503/content/application~1json/schema", "schema": { "title": "ReplaceClientUserRateLimits503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1client~1users~1{clientId}~1rate-limits/put" }, { "operationId": "getClientUserUsage", "method": "GET", "path": "/client/users/{clientId}/usage", "tags": [ "Client Admin" ], "summary": "Get usage and balance for a sub-user", "description": "**Service description**\n\nReturns usage, balance and plan consumption for a managed sub-user.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "Unique ID of a managed sub-user.", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1usage/get/parameters/0/schema", "schema": { "type": "integer" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": 4711 } ], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1usage/get/parameters/0" } ], "requestBody": null, "responses": [ { "status": "200", "description": "Usage status", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1usage/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/UsageStatus", "schemaPointer": "#/components/schemas/UsageStatus", "exampleNames": [], "examples": [] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1usage/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1usage/get/responses/400/content/application~1json/schema", "schema": { "title": "GetClientUserUsage400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } ] } ], "errorCodes": [ "idempotency_key_not_supported" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1usage/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1usage/get/responses/401/content/application~1json/schema", "schema": { "title": "GetClientUserUsage401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "Invalid API key", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1usage/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1usage/get/responses/403/content/application~1json/schema", "schema": { "title": "GetClientUserUsage403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "forbidden", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "forbidden", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "forbidden", "invalid_api_key" ] }, { "status": "404", "description": "Sub-user not found", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1usage/get/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1usage/get/responses/404/content/application~1json/schema", "schema": { "title": "GetClientUserUsage404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "not_found", "message": "No record matches the given identifier" } } ] } ], "errorCodes": [ "not_found" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1usage/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1usage/get/responses/429/content/application~1json/schema", "schema": { "title": "GetClientUserUsage429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1usage/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1usage/get/responses/500/content/application~1json/schema", "schema": { "title": "GetClientUserUsage500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1client~1users~1{clientId}~1usage/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1users~1{clientId}~1usage/get/responses/503/content/application~1json/schema", "schema": { "title": "GetClientUserUsage503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1client~1users~1{clientId}~1usage/get" }, { "operationId": "getClientCredits", "method": "GET", "path": "/client/credits", "tags": [ "Client Admin" ], "summary": "Get own balance", "description": "**Service description**\n\nReturns the authenticated client’s current balance, any overdraft allowance and the amount available from both. When the client works on partner terms the balance is omitted: `billingMode` is then `partner` and the amounts are null, because its balance is not charged.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [], "requestBody": null, "responses": [ { "status": "200", "description": "Credit status", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1credits/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/CreditStatus", "schemaPointer": "#/components/schemas/CreditStatus", "exampleNames": [ "documented" ], "examples": [ { "name": "documented", "value": { "clientId": 1001, "billingMode": "own", "balanceCents": 250000, "balance": "2500.00", "currency": "EUR", "creditLimitCents": 50000, "availableCents": 300000 } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [], "openApiPointer": "#/paths/~1client~1credits/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1credits/get/responses/400/content/application~1json/schema", "schema": { "title": "GetClientCredits400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } ] } ], "errorCodes": [ "idempotency_key_not_supported" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1client~1credits/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1credits/get/responses/401/content/application~1json/schema", "schema": { "title": "GetClientCredits401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1client~1credits/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1credits/get/responses/403/content/application~1json/schema", "schema": { "title": "GetClientCredits403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1client~1credits/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1credits/get/responses/429/content/application~1json/schema", "schema": { "title": "GetClientCredits429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1credits/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1credits/get/responses/500/content/application~1json/schema", "schema": { "title": "GetClientCredits500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1client~1credits/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1credits/get/responses/503/content/application~1json/schema", "schema": { "title": "GetClientCredits503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1client~1credits/get" }, { "operationId": "getClientUsage", "method": "GET", "path": "/client/usage", "tags": [ "Client Admin" ], "summary": "Get own usage and plan consumption", "description": "**Service description**\n\nReturns the authenticated client’s current balance, plan consumption and endpoint-specific usage.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [], "requestBody": null, "responses": [ { "status": "200", "description": "Usage status", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1usage/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/UsageStatus", "schemaPointer": "#/components/schemas/UsageStatus", "exampleNames": [], "examples": [] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [], "openApiPointer": "#/paths/~1client~1usage/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1usage/get/responses/400/content/application~1json/schema", "schema": { "title": "GetClientUsage400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } ] } ], "errorCodes": [ "idempotency_key_not_supported" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1client~1usage/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1usage/get/responses/401/content/application~1json/schema", "schema": { "title": "GetClientUsage401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1client~1usage/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1usage/get/responses/403/content/application~1json/schema", "schema": { "title": "GetClientUsage403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1client~1usage/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1usage/get/responses/429/content/application~1json/schema", "schema": { "title": "GetClientUsage429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1usage/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1usage/get/responses/500/content/application~1json/schema", "schema": { "title": "GetClientUsage500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1client~1usage/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1usage/get/responses/503/content/application~1json/schema", "schema": { "title": "GetClientUsage503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1client~1usage/get" }, { "operationId": "createVinRedirectSession", "method": "POST", "path": "/vin/redirect-sessions", "tags": [ "VIN" ], "summary": "Create a browser redirect for the vehicle lookup", "description": "**Service description**\n\nCreates a short-lived browser session for a VIN lookup. The API key remains in the customer system; the browser uses only the returned `redirectUrl`. On completion or cancellation, the user is returned to the validated `returnUrl` with the documented status parameters.\n\n**Usage and legal notice**\n\nThe paid service consists solely of the technical comparison or analysis and delivery of the result. Rights in the result are granted only to the extent provided by the agreement. Use of the result is governed by the agreement and applicable law. Results may be incomplete, outdated or incorrect and must be independently verified before technical, commercial or legal use.\n\nBy submitting a request, the user confirms that they are authorised to transmit and process the VIN and associated data and, where personal data is involved, have a valid legal basis. Only data necessary for the specific purpose may be submitted.\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1redirect-sessions/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1vin~1redirect-sessions/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VinRedirectSessionRequest", "schemaPointer": "#/components/schemas/VinRedirectSessionRequest", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "vin": "TAPSANDBX00000001", "returnUrl": "https://client.example/vin/callback", "state": "opaque-client-state" } } ] } ] }, "responses": [ { "status": "201", "description": "Redirect session created", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1redirect-sessions/post/responses/201", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VinRedirectSessionResponse", "schemaPointer": "#/components/schemas/VinRedirectSessionResponse", "exampleNames": [ "sandbox", "documented" ], "examples": [ { "name": "sandbox", "value": { "redirectUrl": "https://redirect.example.invalid/session/sandbox", "expiresAt": "2026-01-01T00:00:00+00:00" } }, { "name": "documented", "value": { "redirectUrl": "https://redirect.example.invalid/session/sandbox", "expiresAt": "2026-01-01T00:10:00+00:00" } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid VIN, returnUrl or state", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1redirect-sessions/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1redirect-sessions/post/responses/400/content/application~1json/schema", "schema": { "title": "CreateVinRedirectSession400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vin~1redirect-sessions/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1redirect-sessions/post/responses/401/content/application~1json/schema", "schema": { "title": "CreateVinRedirectSession401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1vin~1redirect-sessions/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1redirect-sessions/post/responses/403/content/application~1json/schema", "schema": { "title": "CreateVinRedirectSession403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vin~1redirect-sessions/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1redirect-sessions/post/responses/409/content/application~1json/schema", "schema": { "title": "CreateVinRedirectSession409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vin~1redirect-sessions/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1redirect-sessions/post/responses/429/content/application~1json/schema", "schema": { "title": "CreateVinRedirectSession429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1redirect-sessions/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1redirect-sessions/post/responses/500/content/application~1json/schema", "schema": { "title": "CreateVinRedirectSession500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1vin~1redirect-sessions/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1redirect-sessions/post/responses/503/content/application~1json/schema", "schema": { "title": "CreateVinRedirectSession503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vin~1redirect-sessions/post" }, { "operationId": "getVehicleByVin", "method": "GET", "path": "/vin/{vin}/vehicle", "tags": [ "VIN" ], "summary": "Compare vehicle data by VIN", "description": "**Service description**\n\nLooks up a VIN using the selected numeric value. If a browser flow is required, the API responds with `redirect_required`; otherwise it returns the documented vehicle data or a domain-level no-result response. A successful lookup includes a stable `tapiId`.\n\n**Usage and legal notice**\n\nThe paid service consists solely of the technical comparison or analysis and delivery of the result. Rights in the result are granted only to the extent provided by the agreement. Use of the result is governed by the agreement and applicable law. Results may be incomplete, outdated or incorrect and must be independently verified before technical, commercial or legal use.\n\nBy submitting a request, the user confirms that they are authorised to transmit and process the VIN and associated data and, where personal data is involved, have a valid legal basis. Only data necessary for the specific purpose may be submitted.\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "Vehicle identification number that the user must be authorised to transmit and process.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1vehicle/get/parameters/0/schema", "schema": { "type": "string" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "TAPSANDBX00000001" } ], "openApiPointer": "#/paths/~1vin~1{vin}~1vehicle/get/parameters/0" }, { "name": "country", "in": "query", "required": false, "description": "Two-letter country code used for market and regional context.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1vehicle/get/parameters/1/schema", "schema": { "type": "string", "default": "de" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "de" } ], "openApiPointer": "#/paths/~1vin~1{vin}~1vehicle/get/parameters/1" }, { "name": "provider", "in": "query", "required": false, "description": "Optional numeric selection agreed by contract; the default value is `1`.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1vehicle/get/parameters/2/schema", "schema": { "type": "integer", "enum": [ 1, 2, 3 ], "default": 1 }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": 2 } ], "openApiPointer": "#/paths/~1vin~1{vin}~1vehicle/get/parameters/2" }, { "name": "includeEquipments", "in": "query", "required": false, "description": "Controls whether determined equipment attributes are returned.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1vehicle/get/parameters/3/schema", "schema": { "type": "boolean", "default": true }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": true } ], "openApiPointer": "#/paths/~1vin~1{vin}~1vehicle/get/parameters/3" }, { "name": "includeColors", "in": "query", "required": false, "description": "Controls whether determined colour information is returned.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1vehicle/get/parameters/4/schema", "schema": { "type": "boolean", "default": true }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": true } ], "openApiPointer": "#/paths/~1vin~1{vin}~1vehicle/get/parameters/4" }, { "name": "includeTechnical", "in": "query", "required": false, "description": "Controls whether determined technical data is returned.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1vehicle/get/parameters/5/schema", "schema": { "type": "boolean", "default": true }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": true } ], "openApiPointer": "#/paths/~1vin~1{vin}~1vehicle/get/parameters/5" } ], "requestBody": null, "responses": [ { "status": "200", "description": "Determined vehicle data", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1vehicle/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VinVehicleResponse", "schemaPointer": "#/components/schemas/VinVehicleResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "vin": "TAPSANDBX00000001", "tapiId": "5b1a1000-0000-4000-8000-000000000001", "provider": 2, "incomplete": false, "displayName": "Sandbox Kompaktwagen 1.5 TSI", "constructionDate": "2021-06-01", "kTypes": [ 900001, 900002 ], "natCodes": [ "SBX0000001" ], "platform": "SBX-PLATFORM-1", "equipmentsCategorized": [ { "category": { "sign": "equipment", "name": "Equipment" }, "equipments": [ { "id": "SBX10124", "name": "Sandbox Klimaautomatik", "manufacturerCodes": [ "SBXAH1" ], "equipmentKind": null, "availability": "option_paid", "isPackage": false, "harmonizedCodes": [ { "code": "00759998", "name": "Automatic Air Condition" } ], "listPrice": { "net": 222, "gross": 240, "currency": "EUR" }, "availabilityPeriod": { "from": "2020-10-12", "until": "2021-07-15" }, "popularity": 2, "type": null } ] } ], "manufacturerOrderCodes": { "matched": [ { "orderCode": "SBX1Z0", "name": "Sandbox Klimaautomatik" } ], "unmatched": [ { "orderCode": "SBX9XY", "name": "Sandbox unbekannte Option" } ] }, "dates": { "production": "2021-06-01", "delivery": "2021-07-20", "firstRegistration": "2021-08-02", "modelYear": 2021 } } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1vehicle/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1vehicle/get/responses/400/content/application~1json/schema", "schema": { "title": "GetVehicleByVin400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported", "invalid_country", "invalid_provider" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_not_supported", "invalid_country", "invalid_provider" ], "examples": [ { "name": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } }, { "name": "invalid_country", "value": { "error": "invalid_country", "message": "country must be a two-letter ISO 3166-1 code" } }, { "name": "invalid_provider", "value": { "error": "invalid_provider", "message": "provider is not a supported selection value" } } ] } ], "errorCodes": [ "idempotency_key_not_supported", "invalid_country", "invalid_provider" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vin~1{vin}~1vehicle/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1vehicle/get/responses/401/content/application~1json/schema", "schema": { "title": "GetVehicleByVin401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1vehicle/get/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1vehicle/get/responses/402/content/application~1json/schema", "schema": { "title": "GetVehicleByVin402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1vin~1{vin}~1vehicle/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1vehicle/get/responses/403/content/application~1json/schema", "schema": { "title": "GetVehicleByVin403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "404", "description": "Vehicle not found", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1vehicle/get/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1vehicle/get/responses/404/content/application~1json/schema", "schema": { "title": "GetVehicleByVin404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found", "vehicle_not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "not_found", "vehicle_not_found" ], "examples": [ { "name": "not_found", "value": { "error": "not_found", "message": "No record matches the given identifier" } }, { "name": "vehicle_not_found", "value": { "error": "vehicle_not_found", "message": "No vehicle is known for this identifier" } } ] } ], "errorCodes": [ "not_found", "vehicle_not_found" ] }, { "status": "409", "description": "Redirect flow required", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1vehicle/get/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1vehicle/get/responses/409/content/application~1json/schema", "schema": { "title": "GetVehicleByVin409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "redirect_required" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "redirect_required", "message": "The VIN has to be confirmed through a redirect session first" } } ] } ], "errorCodes": [ "redirect_required" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vin~1{vin}~1vehicle/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1vehicle/get/responses/429/content/application~1json/schema", "schema": { "title": "GetVehicleByVin429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1vehicle/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1vehicle/get/responses/500/content/application~1json/schema", "schema": { "title": "GetVehicleByVin500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1vehicle/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1vehicle/get/responses/503/content/application~1json/schema", "schema": { "title": "GetVehicleByVin503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "vin_service_unavailable", "service_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "vin_service_unavailable", "service_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "vin_service_unavailable", "value": { "error": "vin_service_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable", "vin_service_unavailable" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vin~1{vin}~1vehicle/get" }, { "operationId": "getPartsByVin", "method": "GET", "path": "/vin/{vin}/parts", "tags": [ "VIN" ], "summary": "Compare parts assignments by VIN", "description": "**Service description**\n\nReturns available part assignments for a VIN. A conflicting explicit selection value returns `vin_provider_mismatch`. The API either responds directly with `200` or accepts processing with `202`, `Location` and `Retry-After`. `matchLevel` describes the scope of the result.\n\n**Usage and legal notice**\n\nThe paid service consists solely of the technical comparison or analysis and delivery of the result. Rights in the result are granted only to the extent provided by the agreement. Use of the result is governed by the agreement and applicable law. Results may be incomplete, outdated or incorrect and must be independently verified before technical, commercial or legal use.\n\nBy submitting a request, the user confirms that they are authorised to transmit and process the VIN and associated data and, where personal data is involved, have a valid legal basis. Only data necessary for the specific purpose may be submitted.\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "Vehicle identification number that the user must be authorised to transmit and process.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1parts/get/parameters/0/schema", "schema": { "type": "string" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "TAPSANDBX00000001" } ], "openApiPointer": "#/paths/~1vin~1{vin}~1parts/get/parameters/0" }, { "name": "country", "in": "query", "required": false, "description": "Two-letter country code used for market and regional context.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1parts/get/parameters/1/schema", "schema": { "type": "string", "default": "de" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "de" } ], "openApiPointer": "#/paths/~1vin~1{vin}~1parts/get/parameters/1" }, { "name": "provider", "in": "query", "required": false, "description": "Optional numeric selection agreed by contract; the default value is `1`.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1parts/get/parameters/2/schema", "schema": { "type": "integer", "enum": [ 1, 2, 3 ], "default": 1 }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": 1 } ], "openApiPointer": "#/paths/~1vin~1{vin}~1parts/get/parameters/2" } ], "requestBody": null, "responses": [ { "status": "200", "description": "Determined VIN parts assignments", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1parts/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VinPartsResponse", "schemaPointer": "#/components/schemas/VinPartsResponse", "exampleNames": [ "vehicleSpecificBestAvailable", "vehicleTypeCandidates", "sandbox" ], "examples": [ { "name": "vehicleSpecificBestAvailable", "value": { "vin": "WVWZZZ1JZXW000001", "tapiId": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "provider": 1, "matchLevel": "vehicle_specific_best_available", "allCategorySigns": [ "ST", "KO" ], "missingCategories": [], "parts": [ { "number": "1J0807417A", "numberUnformatted": "1J0807417A", "name": "Stoßfänger", "category": "ST", "manufacturer": { "id": "VW", "name": "Volkswagen" }, "amount": 1, "tapiGenArt": "TGA-000001", "vdi": [] } ] } }, { "name": "vehicleTypeCandidates", "value": { "vin": "WVWZZZ1JZXW000001", "tapiId": "a2b7c1d4-8e35-4f21-9c07-13ab5e9d2f68", "provider": 2, "matchLevel": "vehicle_type_candidates", "allCategorySigns": [ "ST" ], "missingCategories": [ "KO" ], "parts": [ { "number": "1J0807417A", "name": "Stoßfänger", "category": "ST", "manufacturer": { "id": "VW", "name": "Volkswagen" }, "amount": 1, "tapiGenArt": "TGA-000001", "vdi": [] }, { "number": "1J0807417B", "name": "Stoßfänger", "category": "ST", "manufacturer": { "id": "VW", "name": "Volkswagen" }, "amount": 1, "tapiGenArt": "TGA-000001", "vdi": [] } ] } }, { "name": "sandbox", "value": { "vin": "TAPSANDBX00000001", "tapiId": "5b1a1000-0000-4000-8000-000000000001", "provider": 2, "matchLevel": "vehicle_type_candidates", "allCategorySigns": [ "ST", "BR" ], "missingCategories": [], "parts": [ { "number": "SBX0001A", "numberUnformatted": "SBX0001A", "name": "Sandbox Stoßfänger vorn", "nameAddition": null, "category": "ST", "manufacturer": { "id": "SBX", "name": "Sandbox Motors" }, "amount": 1, "price": 142.5, "tapiGenArt": "TGA-000001", "vdi": [ "VDI4081_900001" ] } ] } } ] } ], "errorCodes": [] }, { "status": "202", "description": "Documented HTTP 202 response.", "headers": [ "Location", "Retry-After", "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1parts/get/responses/202", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VinPartsJobResponse", "schemaPointer": "#/components/schemas/VinPartsJobResponse", "exampleNames": [ "accepted" ], "examples": [ { "name": "accepted", "value": { "jobId": "6955b900-0100-459b-a0e2-e8fee6b51c20", "status": "queued", "statusUrl": "https://api.tapinomahub.com/vin/parts/jobs/6955b900-0100-459b-a0e2-e8fee6b51c20", "vin": "TAPSANDBX00000001", "provider": 1, "retryAfterSeconds": 3, "createdAt": "2026-01-01T00:00:00+00:00" } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1parts/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1parts/get/responses/400/content/application~1json/schema", "schema": { "title": "GetPartsByVin400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported", "invalid_country", "invalid_provider" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_not_supported", "invalid_country", "invalid_provider" ], "examples": [ { "name": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } }, { "name": "invalid_country", "value": { "error": "invalid_country", "message": "country must be a two-letter ISO 3166-1 code" } }, { "name": "invalid_provider", "value": { "error": "invalid_provider", "message": "provider is not a supported selection value" } } ] } ], "errorCodes": [ "idempotency_key_not_supported", "invalid_country", "invalid_provider" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vin~1{vin}~1parts/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1parts/get/responses/401/content/application~1json/schema", "schema": { "title": "GetPartsByVin401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1parts/get/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1parts/get/responses/402/content/application~1json/schema", "schema": { "title": "GetPartsByVin402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1vin~1{vin}~1parts/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1parts/get/responses/403/content/application~1json/schema", "schema": { "title": "GetPartsByVin403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "404", "description": "Not found", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1parts/get/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1parts/get/responses/404/content/application~1json/schema", "schema": { "title": "GetPartsByVin404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found", "vehicle_not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "not_found", "vehicle_not_found" ], "examples": [ { "name": "not_found", "value": { "error": "not_found", "message": "No record matches the given identifier" } }, { "name": "vehicle_not_found", "value": { "error": "vehicle_not_found", "message": "No vehicle is known for this identifier" } } ] } ], "errorCodes": [ "not_found", "vehicle_not_found" ] }, { "status": "409", "description": "Documented HTTP 409 response.", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1parts/get/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1parts/get/responses/409/content/application~1json/schema", "schema": { "title": "GetPartsByVin409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "vin_provider_mismatch" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "vin_provider_mismatch", "message": "The VIN is associated with a different selection value than requested" } } ] } ], "errorCodes": [ "vin_provider_mismatch" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vin~1{vin}~1parts/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1parts/get/responses/429/content/application~1json/schema", "schema": { "title": "GetPartsByVin429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1parts/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1parts/get/responses/500/content/application~1json/schema", "schema": { "title": "GetPartsByVin500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1parts/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1parts/get/responses/503/content/application~1json/schema", "schema": { "title": "GetPartsByVin503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "vin_service_unavailable", "service_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "vin_service_unavailable", "service_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "vin_service_unavailable", "value": { "error": "vin_service_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable", "vin_service_unavailable" ] } ], "supportsIdempotencyKey": false, "asynchronous": true, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vin~1{vin}~1parts/get" }, { "operationId": "getVinPartsJob", "method": "GET", "path": "/vin/parts/jobs/{jobId}", "tags": [ "VIN" ], "summary": "Get the status of a VIN parts lookup", "description": "**Service description**\n\nReturns the documented status and, once complete, the result of a previously accepted VIN parts lookup. Observe `Retry-After` while it is running.\n\n**Usage and legal notice**\n\nThe paid service consists solely of the technical comparison or analysis and delivery of the result. Rights in the result are granted only to the extent provided by the agreement. Use of the result is governed by the agreement and applicable law. Results may be incomplete, outdated or incorrect and must be independently verified before technical, commercial or legal use.\n\nBy submitting a request, the user confirms that they are authorised to transmit and process the VIN and associated data and, where personal data is involved, have a valid legal basis. Only data necessary for the specific purpose may be submitted.\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "Job ID returned by the associated 202 response.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1parts~1jobs~1{jobId}/get/parameters/0/schema", "schema": { "type": "string", "format": "uuid" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6955b900-0100-459b-a0e2-e8fee6b51c20" } ], "openApiPointer": "#/paths/~1vin~1parts~1jobs~1{jobId}/get/parameters/0" } ], "requestBody": null, "responses": [ { "status": "200", "description": "Current job status, including the result on success", "headers": [ "Retry-After", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1parts~1jobs~1{jobId}/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VinPartsJobResponse", "schemaPointer": "#/components/schemas/VinPartsJobResponse", "exampleNames": [ "sandbox", "succeeded", "failed" ], "examples": [ { "name": "sandbox", "value": { "jobId": "6955b900-0100-459b-a0e2-e8fee6b51c20", "status": "queued", "statusUrl": "https://api.tapinomahub.com/vin/parts/jobs/6955b900-0100-459b-a0e2-e8fee6b51c20", "vin": "TAPSANDBX00000001", "provider": 1, "retryAfterSeconds": 3, "createdAt": "2026-01-01T00:00:00+00:00" } }, { "name": "succeeded", "value": { "jobId": "0e57bb6e-7262-4c15-bc1d-75fb8c72fd2f", "status": "succeeded", "statusUrl": "https://api.tapinomahub.com/vin/parts/jobs/0e57bb6e-7262-4c15-bc1d-75fb8c72fd2f", "vin": "WVWZZZ1JZXW000001", "provider": 1, "createdAt": "2026-08-31T12:00:00+00:00", "completedAt": "2026-08-31T12:01:00+00:00", "result": { "vin": "WVWZZZ1JZXW000001", "tapiId": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "provider": 1, "matchLevel": "vehicle_specific_best_available", "allCategorySigns": [ "ST", "KO" ], "missingCategories": [], "parts": [ { "number": "1J0807417A", "numberUnformatted": "1J0807417A", "name": "Stoßfänger", "category": "ST", "manufacturer": { "id": "VW", "name": "Volkswagen" }, "amount": 1, "tapiGenArt": "TGA-000001", "vdi": [] } ] } } }, { "name": "failed", "value": { "jobId": "4c0ac7a1-c09d-4e91-8a7a-857963978adc", "status": "failed", "statusUrl": "https://api.tapinomahub.com/vin/parts/jobs/4c0ac7a1-c09d-4e91-8a7a-857963978adc", "vin": "WVWZZZ1JZXW000001", "provider": 1, "createdAt": "2026-08-31T12:00:00+00:00", "startedAt": "2026-08-31T12:00:05+00:00", "completedAt": "2026-08-31T12:01:00+00:00", "error": { "code": "vin_service_unavailable", "message": "The service is temporarily unavailable." } } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [], "openApiPointer": "#/paths/~1vin~1parts~1jobs~1{jobId}/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1parts~1jobs~1{jobId}/get/responses/400/content/application~1json/schema", "schema": { "title": "GetVinPartsJob400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } ] } ], "errorCodes": [ "idempotency_key_not_supported" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vin~1parts~1jobs~1{jobId}/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1parts~1jobs~1{jobId}/get/responses/401/content/application~1json/schema", "schema": { "title": "GetVinPartsJob401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1vin~1parts~1jobs~1{jobId}/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1parts~1jobs~1{jobId}/get/responses/403/content/application~1json/schema", "schema": { "title": "GetVinPartsJob403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "404", "description": "Job not found or not assigned to the authenticated client", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1parts~1jobs~1{jobId}/get/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1parts~1jobs~1{jobId}/get/responses/404/content/application~1json/schema", "schema": { "title": "GetVinPartsJob404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found", "vin_parts_job_not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "not_found", "vin_parts_job_not_found" ], "examples": [ { "name": "not_found", "value": { "error": "not_found", "message": "No record matches the given identifier" } }, { "name": "vin_parts_job_not_found", "value": { "error": "vin_parts_job_not_found", "message": "No parts job exists under this jobId" } } ] } ], "errorCodes": [ "not_found", "vin_parts_job_not_found" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vin~1parts~1jobs~1{jobId}/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1parts~1jobs~1{jobId}/get/responses/429/content/application~1json/schema", "schema": { "title": "GetVinPartsJob429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1parts~1jobs~1{jobId}/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1parts~1jobs~1{jobId}/get/responses/500/content/application~1json/schema", "schema": { "title": "GetVinPartsJob500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1vin~1parts~1jobs~1{jobId}/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1parts~1jobs~1{jobId}/get/responses/503/content/application~1json/schema", "schema": { "title": "GetVinPartsJob503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "vin_service_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced", "vin_service_unavailable" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } }, { "name": "vin_service_unavailable", "value": { "error": "vin_service_unavailable", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "vin_service_unavailable" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vin~1parts~1jobs~1{jobId}/get" }, { "operationId": "checkVinCart", "method": "POST", "path": "/vin/cart-check", "tags": [ "VIN" ], "summary": "Check an OE cart against a VIN", "description": "**Service description**\n\nChecks a list of one to 30 OE positions against the submitted VIN. `mode=type` checks at vehicle-type level; `mode=vehicle` checks the specific vehicle. The response preserves input order and duplicates.\\n\\n`fits=true` identifies a determined match. `fits=false` identifies that no match was determined. When `complete=false`, a negative item result must not be treated as a definitive exclusion. If a vehicle check cannot finish immediately, the API returns `202`; after completion, the supplied status endpoint returns the same result shape.\n\n**Usage and legal notice**\n\nThe paid service consists solely of the technical comparison or analysis and delivery of the result. Rights in the result are granted only to the extent provided by the agreement. Use of the result is governed by the agreement and applicable law. Results may be incomplete, outdated or incorrect and must be independently verified before technical, commercial or legal use.\n\nBy submitting a request, the user confirms that they are authorised to transmit and process the VIN and associated data and, where personal data is involved, have a valid legal basis. Only data necessary for the specific purpose may be submitted.\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1cart-check/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1vin~1cart-check/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VinCartCheckRequest", "schemaPointer": "#/components/schemas/VinCartCheckRequest", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "vin": "TAPSANDBX00000001", "country": "de", "mode": "vehicle", "oeNumbers": [ "SBX0001A", "SBX0002B" ] } } ] } ] }, "responses": [ { "status": "200", "description": "VIN cart check result", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1cart-check/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VinCartCheckResult", "schemaPointer": "#/components/schemas/VinCartCheckResult", "exampleNames": [ "completeList", "incompleteList", "sandbox" ], "examples": [ { "name": "completeList", "value": { "vin": "WVWZZZ1JZXW000001", "mode": "type", "complete": true, "results": [ { "oe": "1J0807417A", "fits": true }, { "oe": "5Q0919275C", "fits": false } ] } }, { "name": "incompleteList", "value": { "vin": "WVWZZZ1JZXW000001", "mode": "vehicle", "complete": false, "results": [ { "oe": "1J0807417A", "fits": true }, { "oe": "5Q0919275C", "fits": false } ] } }, { "name": "sandbox", "value": { "vin": "TAPSANDBX00000001", "mode": "type", "complete": true, "results": [] } } ] } ], "errorCodes": [] }, { "status": "202", "description": "Cart check accepted for processing", "headers": [ "Location", "Retry-After", "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1cart-check/post/responses/202", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VinCartCheckJobResponse", "schemaPointer": "#/components/schemas/VinCartCheckJobResponse", "exampleNames": [ "accepted" ], "examples": [ { "name": "accepted", "value": { "jobId": "6955b900-0200-466b-93c4-5b51907e8d94", "status": "queued", "statusUrl": "https://api.tapinomahub.com/vin/cart-check/jobs/6955b900-0200-466b-93c4-5b51907e8d94", "vin": "TAPSANDBX00000001", "mode": "vehicle", "retryAfterSeconds": 3, "createdAt": "2026-01-01T00:00:00+00:00" } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid VIN, mode or OE list", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1cart-check/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1cart-check/post/responses/400/content/application~1json/schema", "schema": { "title": "CheckVinCart400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_country", "invalid_idempotency_key", "invalid_mode", "invalid_oe_number", "invalid_oe_numbers", "invalid_vin", "too_many_oe_numbers" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_country", "invalid_idempotency_key", "invalid_mode", "invalid_oe_number", "invalid_oe_numbers", "invalid_vin", "too_many_oe_numbers" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_country", "value": { "error": "invalid_country", "message": "country must be a two-letter ISO 3166-1 code" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } }, { "name": "invalid_mode", "value": { "error": "invalid_mode", "message": "mode must be one of the documented values" } }, { "name": "invalid_oe_number", "value": { "error": "invalid_oe_number", "message": "oeNumber must not be empty" } }, { "name": "invalid_oe_numbers", "value": { "error": "invalid_oe_numbers", "message": "oeNumbers must contain at least one usable number" } }, { "name": "invalid_vin", "value": { "error": "invalid_vin", "message": "vin must be 17 characters and must not contain I, O or Q" } }, { "name": "too_many_oe_numbers", "value": { "error": "too_many_oe_numbers", "message": "oeNumbers exceeds the maximum number of entries per request" } } ] } ], "errorCodes": [ "bad_request", "invalid_country", "invalid_idempotency_key", "invalid_mode", "invalid_oe_number", "invalid_oe_numbers", "invalid_vin", "too_many_oe_numbers" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vin~1cart-check/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1cart-check/post/responses/401/content/application~1json/schema", "schema": { "title": "CheckVinCart401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1cart-check/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1cart-check/post/responses/402/content/application~1json/schema", "schema": { "title": "CheckVinCart402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1vin~1cart-check/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1cart-check/post/responses/403/content/application~1json/schema", "schema": { "title": "CheckVinCart403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "404", "description": "Not found", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1cart-check/post/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1cart-check/post/responses/404/content/application~1json/schema", "schema": { "title": "CheckVinCart404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "vehicle_not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "vehicle_not_found", "message": "No vehicle is known for this identifier" } } ] } ], "errorCodes": [ "vehicle_not_found" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vin~1cart-check/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1cart-check/post/responses/409/content/application~1json/schema", "schema": { "title": "CheckVinCart409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vin~1cart-check/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1cart-check/post/responses/429/content/application~1json/schema", "schema": { "title": "CheckVinCart429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1cart-check/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1cart-check/post/responses/500/content/application~1json/schema", "schema": { "title": "CheckVinCart500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1cart-check/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1cart-check/post/responses/503/content/application~1json/schema", "schema": { "title": "CheckVinCart503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "vin_service_unavailable", "service_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "vin_service_unavailable", "service_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "vin_service_unavailable", "value": { "error": "vin_service_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable", "vin_service_unavailable" ] } ], "supportsIdempotencyKey": true, "asynchronous": true, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vin~1cart-check/post" }, { "operationId": "getVinCartCheckJob", "method": "GET", "path": "/vin/cart-check/jobs/{jobId}", "tags": [ "VIN" ], "summary": "Get the status of a VIN cart check", "description": "**Service description**\n\nReturns the current state of a previously accepted vehicle cart check. While the status is `queued` or `running`, the client should observe `Retry-After`. On `succeeded`, `result` contains only the cart check with OE numbers and boolean results. On `failed`, any charge for the original cart-check request is refunded automatically. Status polling is part of the paid original service and creates no second order.\n\n**Usage and legal notice**\n\nThe paid service consists solely of the technical comparison or analysis and delivery of the result. Rights in the result are granted only to the extent provided by the agreement. Use of the result is governed by the agreement and applicable law. Results may be incomplete, outdated or incorrect and must be independently verified before technical, commercial or legal use.\n\nBy submitting a request, the user confirms that they are authorised to transmit and process the VIN and associated data and, where personal data is involved, have a valid legal basis. Only data necessary for the specific purpose may be submitted.\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "Job ID returned by the associated 202 response.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1cart-check~1jobs~1{jobId}/get/parameters/0/schema", "schema": { "type": "string", "format": "uuid" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6955b900-0200-466b-93c4-5b51907e8d94" } ], "openApiPointer": "#/paths/~1vin~1cart-check~1jobs~1{jobId}/get/parameters/0" } ], "requestBody": null, "responses": [ { "status": "200", "description": "Current job status, including the check result on success", "headers": [ "Retry-After", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1cart-check~1jobs~1{jobId}/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VinCartCheckJobResponse", "schemaPointer": "#/components/schemas/VinCartCheckJobResponse", "exampleNames": [ "sandbox", "failed" ], "examples": [ { "name": "sandbox", "value": { "jobId": "6955b900-0200-466b-93c4-5b51907e8d94", "status": "queued", "statusUrl": "https://api.tapinomahub.com/vin/cart-check/jobs/6955b900-0200-466b-93c4-5b51907e8d94", "vin": "TAPSANDBX00000001", "mode": "vehicle", "retryAfterSeconds": 3, "createdAt": "2026-01-01T00:00:00+00:00" } }, { "name": "failed", "value": { "jobId": "5d1bd8b2-d1ae-4fa2-9b8b-968074089bed", "status": "failed", "statusUrl": "https://api.tapinomahub.com/vin/cart-check/jobs/5d1bd8b2-d1ae-4fa2-9b8b-968074089bed", "vin": "WVWZZZ1JZXW000001", "mode": "vehicle", "createdAt": "2026-08-31T12:00:00+00:00", "startedAt": "2026-08-31T12:00:05+00:00", "completedAt": "2026-08-31T12:01:00+00:00", "error": { "code": "vin_service_unavailable", "message": "The service is temporarily unavailable." } } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [], "openApiPointer": "#/paths/~1vin~1cart-check~1jobs~1{jobId}/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1cart-check~1jobs~1{jobId}/get/responses/400/content/application~1json/schema", "schema": { "title": "GetVinCartCheckJob400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } ] } ], "errorCodes": [ "idempotency_key_not_supported" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vin~1cart-check~1jobs~1{jobId}/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1cart-check~1jobs~1{jobId}/get/responses/401/content/application~1json/schema", "schema": { "title": "GetVinCartCheckJob401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1vin~1cart-check~1jobs~1{jobId}/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1cart-check~1jobs~1{jobId}/get/responses/403/content/application~1json/schema", "schema": { "title": "GetVinCartCheckJob403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "404", "description": "Job not found or not assigned to the authenticated client", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1cart-check~1jobs~1{jobId}/get/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1cart-check~1jobs~1{jobId}/get/responses/404/content/application~1json/schema", "schema": { "title": "GetVinCartCheckJob404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found", "vin_cart_check_job_not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "not_found", "vin_cart_check_job_not_found" ], "examples": [ { "name": "not_found", "value": { "error": "not_found", "message": "No record matches the given identifier" } }, { "name": "vin_cart_check_job_not_found", "value": { "error": "vin_cart_check_job_not_found", "message": "No cart check job exists under this jobId" } } ] } ], "errorCodes": [ "not_found", "vin_cart_check_job_not_found" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vin~1cart-check~1jobs~1{jobId}/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1cart-check~1jobs~1{jobId}/get/responses/429/content/application~1json/schema", "schema": { "title": "GetVinCartCheckJob429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1cart-check~1jobs~1{jobId}/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1cart-check~1jobs~1{jobId}/get/responses/500/content/application~1json/schema", "schema": { "title": "GetVinCartCheckJob500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1vin~1cart-check~1jobs~1{jobId}/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1cart-check~1jobs~1{jobId}/get/responses/503/content/application~1json/schema", "schema": { "title": "GetVinCartCheckJob503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vin~1cart-check~1jobs~1{jobId}/get" }, { "operationId": "getOePart", "method": "GET", "path": "/parts/oe/{oeNumber}", "tags": [ "Parts" ], "summary": "Compare OE part name, fitment, comparison numbers and replacement chain", "description": "**Service description**\n\nLooks up an OE part number. For a confirmed match, the response contains the normalised number, part data, optional classifications, vehicle assignments, reference and comparison numbers grouped by manufacturer, the same numbers consolidated in `referenceNumbers.oe_oem_reference_numbers`, and documented replacement edges. `tapiGenArt` can be `null` and `vdi` can be empty without blocking the confirmed base match. Reference numbers, vehicle assignments and replacement edges each have their own meaning; one field is not derived from another. They do not guarantee interchangeability or fit.\n\n**Usage and legal notice**\n\nThe paid service consists solely of the technical comparison or analysis and delivery of the result. Rights in the result are granted only to the extent provided by the agreement. Use of the result is governed by the agreement and applicable law. Results may be incomplete, outdated or incorrect and must be independently verified before technical, commercial or legal use.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "oeNumber", "in": "path", "required": true, "description": "OE part number compared with available reference information.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/parameters/0/schema", "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "SBX0001A" } ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/parameters/0" }, { "name": "manufacturer", "in": "query", "required": false, "description": "Optional manufacturer context for the request.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/parameters/1/schema", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "SANDBOX MOTORS" } ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/parameters/1" } ], "requestBody": null, "responses": [ { "status": "200", "description": "Determined OE part information", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/PartOeResponse", "schemaPointer": "#/components/schemas/PartOeResponse", "exampleNames": [ "documented", "sandbox", "withoutReplacement", "withoutTapiGenArt" ], "examples": [ { "name": "documented", "value": { "oeNumber": "5Q0919275C", "normalizedOeNumber": "5Q0919275C", "tapiGenArt": "TGA-000001", "vdi": [ "VDI4081_900001" ], "part": { "number": "5Q0919275C", "manufacturer": "Volkswagen", "name": "Abstand-Sensor vorne seitlich aussen", "listPrice": { "amount": 199, "currency": "EUR", "country": "DE", "isNet": true } }, "fitment": [ { "vehicleTypeKey": "104561", "criteria": [ "Aerodynamikpaket" ] }, { "vehicleTypeKey": "104562", "criteria": [] } ], "replacementChain": [ { "from": "5Q0919275B", "to": "5Q0919275C" } ], "references": [ { "manufacturer": "Volkswagen", "numbers": [ "5Q0919275B", "5Q0919275C" ] } ], "referenceNumbers": { "oe_oem_reference_numbers": [ "5Q0919275B", "5Q0919275C" ] } } }, { "name": "sandbox", "value": { "oeNumber": "SBX0001A", "normalizedOeNumber": "SBX0001A", "tapiGenArt": "TGA-000001", "vdi": [ "VDI4081_900001" ], "part": { "number": "SBX0001A", "manufacturer": "Sandbox Motors", "name": "Sandbox Stoßfänger vorn", "listPrice": { "amount": 299, "currency": "EUR", "country": "DE", "isNet": false } }, "fitment": [ { "vehicleTypeKey": "900001", "criteria": [] } ], "replacementChain": [ { "from": "SBX0001A", "to": "SBX0001B" } ], "references": [ { "manufacturer": "Sandbox Motors", "numbers": [ "SBX0001B" ] } ], "referenceNumbers": { "oe_oem_reference_numbers": [ "SBX0001A", "SBX0001B" ] } } }, { "name": "withoutReplacement", "value": { "oeNumber": "1K0615301M", "normalizedOeNumber": "1K0615301M", "tapiGenArt": "TGA-000002", "vdi": [], "part": { "number": "1K0615301M", "manufacturer": "Volkswagen", "name": "Bremsscheibe", "listPrice": null }, "fitment": [], "replacementChain": [], "references": [], "referenceNumbers": { "oe_oem_reference_numbers": [ "1K0615301M" ] } } }, { "name": "withoutTapiGenArt", "value": { "oeNumber": "5Q0919275CGRU", "normalizedOeNumber": "5Q0919275CGRU", "tapiGenArt": null, "vdi": [ "VDI4081_11275" ], "part": { "number": "5Q0919275CGRU", "manufacturer": null, "name": "Geber", "listPrice": null }, "fitment": [], "replacementChain": [], "references": [], "referenceNumbers": { "oe_oem_reference_numbers": [ "5Q0919275CGRU" ] } } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid OE part number or manufacturer", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/responses/400/content/application~1json/schema", "schema": { "title": "GetOePart400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported", "invalid_manufacturer", "invalid_oe_number" ] }, "message": { "type": "string" } } }, "exampleNames": [ "invalid_manufacturer_type", "invalid_manufacturer_length", "invalid_oe_number_length", "invalid_oe_number_format" ], "examples": [ { "name": "invalid_manufacturer_type", "value": { "error": "invalid_manufacturer", "message": "manufacturer must be a string" } }, { "name": "invalid_manufacturer_length", "value": { "error": "invalid_manufacturer", "message": "manufacturer must not exceed 100 characters" } }, { "name": "invalid_oe_number_length", "value": { "error": "invalid_oe_number", "message": "oeNumber must be between 1 and 128 characters" } }, { "name": "invalid_oe_number_format", "value": { "error": "invalid_oe_number", "message": "oeNumber is not a valid OE number" } } ] } ], "errorCodes": [ "idempotency_key_not_supported", "invalid_manufacturer", "invalid_oe_number" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/responses/401/content/application~1json/schema", "schema": { "title": "GetOePart401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/responses/402/content/application~1json/schema", "schema": { "title": "GetOePart402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/responses/403/content/application~1json/schema", "schema": { "title": "GetOePart403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "404", "description": "OE part not found", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/responses/404/content/application~1json/schema", "schema": { "title": "GetOePart404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found", "oe_part_not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "not_found", "oe_part_not_found" ], "examples": [ { "name": "not_found", "value": { "error": "not_found", "message": "No record matches the given identifier" } }, { "name": "oe_part_not_found", "value": { "error": "oe_part_not_found", "message": "No part is known for this OE number" } } ] } ], "errorCodes": [ "not_found", "oe_part_not_found" ] }, { "status": "422", "description": "Ambiguous OE part number", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/responses/422", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/responses/422/content/application~1json/schema", "schema": { "title": "GetOePart422Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "ambiguous_oe_number" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "ambiguous_oe_number", "message": "The OE number could not be resolved uniquely" } } ] } ], "errorCodes": [ "ambiguous_oe_number" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/responses/429/content/application~1json/schema", "schema": { "title": "GetOePart429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/responses/500/content/application~1json/schema", "schema": { "title": "GetOePart500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}/get/responses/503/content/application~1json/schema", "schema": { "title": "GetOePart503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "parts_service_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "parts_service_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "parts_service_unavailable", "value": { "error": "parts_service_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "parts_service_unavailable" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}/get" }, { "operationId": "getOeAftermarketReferences", "method": "GET", "path": "/parts/oe/{oeNumber}/aftermarket-references", "tags": [ "Parts" ], "summary": "Determine aftermarket references for an OE number", "description": "**Service description**\n\nCompares the submitted OE part number and returns determined aftermarket references. A reference does not guarantee technical compatibility, interchangeability, fit or suitability and must be independently verified before use. If no references are available, the successful response contains an empty list.\n\n**Usage and legal notice**\n\nThe paid service consists solely of the technical comparison or analysis and delivery of the result. Rights in the result are granted only to the extent provided by the agreement. Use of the result is governed by the agreement and applicable law. Results may be incomplete, outdated or incorrect and must be independently verified before technical, commercial or legal use.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "oeNumber", "in": "path", "required": true, "description": "OE part number compared with available reference information.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/parameters/0/schema", "schema": { "type": "string", "minLength": 1 }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "SBX0001A" } ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/parameters/0" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of entries in the response, 1 to 500. Without it the endpoint returns the complete list as before. Each page is a separate call and is charged like a call.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/parameters/1/schema", "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": 100 } ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/parameters/1" }, { "name": "offset", "in": "query", "required": false, "description": "Number of entries to skip; only allowed together with `limit`. `count` stays the total in every response, the length of the page is in `page.returned`.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/parameters/2/schema", "schema": { "type": "integer", "minimum": 0 }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": 0 } ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/parameters/2" } ], "requestBody": null, "responses": [ { "status": "200", "description": "Determined aftermarket references", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/AftermarketReferencesResponse", "schemaPointer": "#/components/schemas/AftermarketReferencesResponse", "exampleNames": [ "documented", "sandbox" ], "examples": [ { "name": "documented", "value": { "oeNumber": "6RD615301", "aftermarketReferences": [ { "partNumber": "DF2803", "normalizedPartNumber": "DF2803", "manufacturer": "TRW" }, { "partNumber": "15830C", "normalizedPartNumber": "15830C", "manufacturer": "MAPCO" } ], "count": 2 } }, { "name": "sandbox", "value": { "oeNumber": "SBX0001A", "aftermarketReferences": [], "count": 0 } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid OE part number", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/responses/400/content/application~1json/schema", "schema": { "title": "GetOeAftermarketReferences400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported", "invalid_oe_number", "invalid_query_parameter" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_not_supported", "invalid_oe_number", "invalid_query_parameter" ], "examples": [ { "name": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } }, { "name": "invalid_oe_number", "value": { "error": "invalid_oe_number", "message": "oeNumber must not be empty" } }, { "name": "invalid_query_parameter", "value": { "error": "invalid_query_parameter", "message": "A query parameter has the wrong type or format" } } ] } ], "errorCodes": [ "idempotency_key_not_supported", "invalid_oe_number", "invalid_query_parameter" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/responses/401/content/application~1json/schema", "schema": { "title": "GetOeAftermarketReferences401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/responses/402/content/application~1json/schema", "schema": { "title": "GetOeAftermarketReferences402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/responses/403/content/application~1json/schema", "schema": { "title": "GetOeAftermarketReferences403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "404", "description": "Not found", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/responses/404/content/application~1json/schema", "schema": { "title": "GetOeAftermarketReferences404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "oe_part_not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "oe_part_not_found", "message": "No part is known for this OE number" } } ] } ], "errorCodes": [ "oe_part_not_found" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/responses/429/content/application~1json/schema", "schema": { "title": "GetOeAftermarketReferences429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/responses/500/content/application~1json/schema", "schema": { "title": "GetOeAftermarketReferences500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get/responses/503/content/application~1json/schema", "schema": { "title": "GetOeAftermarketReferences503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "parts_service_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "parts_service_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "parts_service_unavailable", "value": { "error": "parts_service_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "parts_service_unavailable" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1aftermarket-references/get" }, { "operationId": "getPartSeo", "method": "GET", "path": "/parts/oe/{oeNumber}/seo", "tags": [ "Parts" ], "summary": "Optimise an eBay or marketplace article (SEO enrichment)", "description": "Optimises the article for the OE part number in the selected marketplace and language. `marketplaceId` selects the marketplace; the documented values are the eBay marketplaces `EBAY_AT` through `EBAY_US`, with `EBAY_DE` as the default. The response contains the article title for the eBay headline in `content.ebayTitle` (at most 80 characters), the marketplace category in `categoryId`, the item specifics in `itemSpecifics`, search keywords in `keywords`, the product naming in `product`, and the shop SEO text in `content`. The result must be independently checked for accuracy and permissibility before publication; it is publication content, never a fitment statement.\n\n**Usage and legal notice**\n\nThe paid service consists solely of the technical comparison or analysis and delivery of the result. Rights in the result are granted only to the extent provided by the agreement. Use of the result is governed by the agreement and applicable law. Results may be incomplete, outdated or incorrect and must be independently verified before technical, commercial or legal use.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "oeNumber", "in": "path", "required": true, "description": "OE part number compared with available reference information.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/parameters/0/schema", "schema": { "type": "string", "minLength": 3, "maxLength": 64 }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "5Q0919275C" } ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/parameters/0" }, { "name": "marketplaceId", "in": "query", "required": false, "description": "Public parameter `marketplaceId` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/parameters/1/schema", "schema": { "type": "string", "default": "EBAY_DE", "enum": [ "EBAY_AT", "EBAY_AU", "EBAY_BE", "EBAY_CA", "EBAY_CH", "EBAY_DE", "EBAY_ES", "EBAY_FR", "EBAY_GB", "EBAY_HK", "EBAY_IE", "EBAY_IT", "EBAY_NL", "EBAY_PL", "EBAY_SG", "EBAY_US" ] }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "EBAY_DE" } ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/parameters/1" }, { "name": "language", "in": "query", "required": false, "description": "ISO 639-1 language code for generated content.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/parameters/2/schema", "schema": { "type": "string", "enum": [ "de", "en", "fr", "es", "it", "nl", "pl", "zh" ] }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "de" } ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/parameters/2" }, { "name": "vehicleType", "in": "query", "required": false, "description": "Public parameter `vehicleType` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/parameters/3/schema", "schema": { "type": "string", "default": "car", "enum": [ "car", "motorcycle" ] }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/parameters/3" } ], "requestBody": null, "responses": [ { "status": "200", "description": "Generated SEO data", "headers": [ "Retry-After", "X-Tapinoma-Billing-Source", "X-Tapinoma-Live-Available-At", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/PartSeoResponse", "schemaPointer": "#/components/schemas/PartSeoResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "oeNumber": "SBX0001A", "marketplaceId": "SANDBOX", "language": "de", "vehicleType": "car", "categoryId": null, "product": { "manufacturer": null, "name": "", "nameAddition": null }, "content": { "title": "Front bumper — sandbox", "ebayTitle": "sandbox stossfaenger SBX0001A", "metaTitle": "Stoßfänger vorne Sandbox", "metaDescription": "Synthetischer Sandbox-Datensatz zur Integration; keine echten Marktinhalte.", "h1": "Stoßfänger vorne Sandbox", "slug": "stossfaenger-vorne-sandbox", "bulletPoints": [ "Sandbox-Datensatz", "Nur zu Integrationszwecken" ] }, "keywords": [ "sandbox", "stossfaenger" ], "itemSpecifics": [] } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/responses/400/content/application~1json/schema", "schema": { "title": "GetPartSeo400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "conflicting_query_parameters", "idempotency_key_not_supported", "invalid_marketplace_id", "invalid_oe_number", "invalid_query_parameter", "unsupported_marketplace_language", "unsupported_query_parameter" ] }, "message": { "type": "string" } } }, "exampleNames": [ "conflicting_query_parameters", "idempotency_key_not_supported", "invalid_marketplace_id", "invalid_oe_number", "invalid_query_parameter", "unsupported_marketplace_language", "unsupported_query_parameter" ], "examples": [ { "name": "conflicting_query_parameters", "value": { "error": "conflicting_query_parameters", "message": "Two query parameters of this request contradict each other" } }, { "name": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } }, { "name": "invalid_marketplace_id", "value": { "error": "invalid_marketplace_id", "message": "marketplaceId is not a supported marketplace" } }, { "name": "invalid_oe_number", "value": { "error": "invalid_oe_number", "message": "oeNumber must not be empty" } }, { "name": "invalid_query_parameter", "value": { "error": "invalid_query_parameter", "message": "A query parameter has the wrong type or format" } }, { "name": "unsupported_marketplace_language", "value": { "error": "unsupported_marketplace_language", "message": "The marketplace does not support the requested language" } }, { "name": "unsupported_query_parameter", "value": { "error": "unsupported_query_parameter", "message": "The request contains a query parameter this endpoint does not accept" } } ] } ], "errorCodes": [ "conflicting_query_parameters", "idempotency_key_not_supported", "invalid_marketplace_id", "invalid_oe_number", "invalid_query_parameter", "unsupported_marketplace_language", "unsupported_query_parameter" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/responses/401/content/application~1json/schema", "schema": { "title": "GetPartSeo401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/responses/402/content/application~1json/schema", "schema": { "title": "GetPartSeo402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/responses/403/content/application~1json/schema", "schema": { "title": "GetPartSeo403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "404", "description": "No exact match was found; commercial treatment follows the terms shown when ordering and agreed in the contract", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/PartSeoNoMatchResponse", "schemaPointer": "#/components/schemas/PartSeoNoMatchResponse", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "seo_no_exact_match", "message": "No exact match was found for the requested OE number", "oeNumber": "5Q0919275C", "marketplaceId": "EBAY_DE", "language": "de", "vehicleType": "car" } } ] } ], "errorCodes": [ "seo_no_exact_match" ] }, { "status": "429", "description": "Documented HTTP 429 response.", "headers": [ "Retry-After", "X-Tapinoma-Billing-Source", "X-Tapinoma-Live-Available-At", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/responses/429/content/application~1json/schema", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "rate_limit_exceeded", "client_request_in_progress" ], "description": "Stable code for a request-rate or per-Client concurrency rejection." } } } ] }, { "$ref": "#/components/schemas/SeoLivePausedResponse" } ] }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "seo_live_requests_paused", "message": "Live marketplace enrichment is temporarily paused", "liveAvailability": { "status": "PAUSED", "reason": "RATE_LIMIT_REACHED", "availableAt": "2026-08-18T14:05:00+00:00", "retryAfterSeconds": 86400 } } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded", "seo_live_requests_paused" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/responses/500/content/application~1json/schema", "schema": { "title": "GetPartSeo500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get/responses/503/content/application~1json/schema", "schema": { "title": "GetPartSeo503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "seo_service_unavailable", "service_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "seo_service_unavailable", "service_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "seo_service_unavailable", "value": { "error": "seo_service_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "seo_service_unavailable", "service_unavailable" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1seo/get" }, { "operationId": "extractRegistrationDocument", "method": "POST", "path": "/scanner/document/registration", "tags": [ "Scanner" ], "summary": "Extract a vehicle registration document", "description": "**Service description**\n\nAnalyses a vehicle registration document provided by file URL as an image or PDF and returns detected, structured document and vehicle fields.\n\n**Usage and legal notice**\n\nOnly `standard` is currently available for personal documents. Processing levels that are not offered must not be selected.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.\n\n**Response format**\n\nProduction and sandbox use the same 200 response contract and the same lowerCamelCase field structure. The named examples differ only in their example values.\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1registration/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1scanner~1document~1registration/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1registration/post/requestBody/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "anyOf": [ { "required": [ "fileUrl" ] }, { "required": [ "imageUrl" ] } ], "properties": { "fileUrl": { "type": "string", "format": "uri", "description": "Publicly accessible URL of a document that the user is authorised to transmit and process.", "example": "https://example.com/registration-document.pdf" }, "imageUrl": { "type": "string", "format": "uri", "deprecated": true, "description": "Publicly accessible URL of an image that the user is authorised to transmit and process.", "example": "https://example.com/registration-document.jpg" }, "quality": { "$ref": "#/components/schemas/SensitiveDocumentQuality" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "fileUrl": "https://example.com/registration-document.pdf", "quality": "standard" } } ] } ] }, "responses": [ { "status": "200", "description": "Vehicle document analysed", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1registration/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/RegistrationDocumentEnvelopeResponse", "schemaPointer": "#/components/schemas/RegistrationDocumentEnvelopeResponse", "exampleNames": [ "production", "sandbox" ], "examples": [ { "name": "production", "value": { "status": "ok", "data": { "registrationNumber": "B-AB 1234", "documentNumber": "AB123456789", "issuingAuthority": "Berlin", "issuedDate": "2024-05-14", "owner": { "nameOrCompany": "Muster GmbH", "givenNames": null, "address": "Musterstraße 1, 10115 Berlin" }, "inspection": { "nextInspectionMonthYear": "05/2026", "lastInspectionDate": "2024-05-14", "inspectionPlace": "Berlin" }, "vehicle": { "vin": "WVWZZZ1KZAW000000", "hsn": "0603", "tsn": "BMQ", "brand": "VOLKSWAGEN", "modelCode": "1K", "commercialName": "GOLF", "vehicleClass": "M1", "bodyType": "Schräghecklimousine", "fuel": "Benzin", "displacementCc": "1390", "powerKw": "90", "co2GPerKm": "144", "emissionsClass": "EURO 5", "permissibleTotalMassF1": "1960", "permissibleTotalMassF2": "1960", "unladenMassKg": "1344", "axleLoads": [ "7.1: 1050", "7.2: 1010" ], "allowedTrailerMassBraked": "1400", "allowedTrailerMassUnbraked": "670", "seatsTotal": "5", "seatsDriverIncluded": "5", "tireSizes": [ "195/65 R15 91H" ] }, "technicalDetailsRaw": { "rawTableLines": [ "P.1 1390", "P.2 90" ] }, "codesAndNotes": { "pCodes": [ "P.1", "P.2" ], "eTypeApproval": "e1*2007/46*0001", "otherNotes": null }, "rawTextLines": [ "ZULASSUNGSBESCHEINIGUNG TEIL I" ], "notes": null } } }, { "name": "sandbox", "value": { "status": "ok", "data": { "registrationNumber": "SBX-TE 999", "documentNumber": "SBX0000000001", "issuingAuthority": "Sandbox", "issuedDate": "2021-06-01", "owner": { "nameOrCompany": null, "givenNames": null, "address": null }, "inspection": { "nextInspectionMonthYear": null, "lastInspectionDate": null, "inspectionPlace": null }, "vehicle": { "vin": "TAPSANDBX00000001", "hsn": "9999", "tsn": "SBX1", "brand": "Sandbox Motors", "modelCode": null, "commercialName": "Modell A", "vehicleClass": null, "bodyType": null, "fuel": null, "displacementCc": null, "powerKw": null, "co2GPerKm": null, "emissionsClass": null, "permissibleTotalMassF1": null, "permissibleTotalMassF2": null, "unladenMassKg": null, "axleLoads": null, "allowedTrailerMassBraked": null, "allowedTrailerMassUnbraked": null, "seatsTotal": null, "seatsDriverIncluded": null, "tireSizes": null }, "technicalDetailsRaw": { "rawTableLines": null }, "codesAndNotes": { "pCodes": null, "eTypeApproval": null, "otherNotes": null }, "rawTextLines": null, "notes": null } } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1registration/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1registration/post/responses/400/content/application~1json/schema", "schema": { "title": "ExtractRegistrationDocument400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1scanner~1document~1registration/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1registration/post/responses/401/content/application~1json/schema", "schema": { "title": "ExtractRegistrationDocument401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1registration/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1registration/post/responses/402/content/application~1json/schema", "schema": { "title": "ExtractRegistrationDocument402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1scanner~1document~1registration/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1registration/post/responses/403/content/application~1json/schema", "schema": { "title": "ExtractRegistrationDocument403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1document~1registration/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1registration/post/responses/409/content/application~1json/schema", "schema": { "title": "ExtractRegistrationDocument409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1document~1registration/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1registration/post/responses/429/content/application~1json/schema", "schema": { "title": "ExtractRegistrationDocument429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1registration/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1registration/post/responses/500/content/application~1json/schema", "schema": { "title": "ExtractRegistrationDocument500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1registration/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1registration/post/responses/503/content/application~1json/schema", "schema": { "title": "ExtractRegistrationDocument503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "service_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1scanner~1document~1registration/post" }, { "operationId": "extractRegistrationDocumentLegacyPath", "method": "POST", "path": "/scanner/registration-document", "tags": [ "Scanner" ], "summary": "Extract a registration document (deprecated path)", "description": "**Service description**\n\nExtract a registration document (deprecated path). The request and response follow the schemas documented below.\n\n**Usage and legal notice**\n\nOnly `standard` is currently available for personal documents. Processing levels that are not offered must not be selected.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.\n\n**Response format**\n\nProduction and sandbox use the same 200 response contract and the same lowerCamelCase field structure. The named examples differ only in their example values.\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1registration-document/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1scanner~1registration-document/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1registration-document/post/requestBody/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "anyOf": [ { "required": [ "fileUrl" ] }, { "required": [ "imageUrl" ] } ], "properties": { "fileUrl": { "type": "string", "format": "uri", "description": "Publicly accessible URL of a document that the user is authorised to transmit and process.", "example": "https://example.com/registration-document.pdf" }, "imageUrl": { "type": "string", "format": "uri", "deprecated": true, "description": "Publicly accessible URL of an image that the user is authorised to transmit and process.", "example": "https://example.com/registration-document.jpg" }, "quality": { "$ref": "#/components/schemas/SensitiveDocumentQuality" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "fileUrl": "https://example.com/registration-document.pdf", "quality": "standard" } } ] } ] }, "responses": [ { "status": "200", "description": "Vehicle document analysed", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1registration-document/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/RegistrationDocumentEnvelopeResponse", "schemaPointer": "#/components/schemas/RegistrationDocumentEnvelopeResponse", "exampleNames": [ "production", "sandbox" ], "examples": [ { "name": "production", "value": { "status": "ok", "data": { "registrationNumber": "B-AB 1234", "documentNumber": "AB123456789", "issuingAuthority": "Berlin", "issuedDate": "2024-05-14", "owner": { "nameOrCompany": "Muster GmbH", "givenNames": null, "address": "Musterstraße 1, 10115 Berlin" }, "inspection": { "nextInspectionMonthYear": "05/2026", "lastInspectionDate": "2024-05-14", "inspectionPlace": "Berlin" }, "vehicle": { "vin": "WVWZZZ1KZAW000000", "hsn": "0603", "tsn": "BMQ", "brand": "VOLKSWAGEN", "modelCode": "1K", "commercialName": "GOLF", "vehicleClass": "M1", "bodyType": "Schräghecklimousine", "fuel": "Benzin", "displacementCc": "1390", "powerKw": "90", "co2GPerKm": "144", "emissionsClass": "EURO 5", "permissibleTotalMassF1": "1960", "permissibleTotalMassF2": "1960", "unladenMassKg": "1344", "axleLoads": [ "7.1: 1050", "7.2: 1010" ], "allowedTrailerMassBraked": "1400", "allowedTrailerMassUnbraked": "670", "seatsTotal": "5", "seatsDriverIncluded": "5", "tireSizes": [ "195/65 R15 91H" ] }, "technicalDetailsRaw": { "rawTableLines": [ "P.1 1390", "P.2 90" ] }, "codesAndNotes": { "pCodes": [ "P.1", "P.2" ], "eTypeApproval": "e1*2007/46*0001", "otherNotes": null }, "rawTextLines": [ "ZULASSUNGSBESCHEINIGUNG TEIL I" ], "notes": null } } }, { "name": "sandbox", "value": { "status": "ok", "data": { "registrationNumber": "SBX-TE 999", "documentNumber": "SBX0000000001", "issuingAuthority": "Sandbox", "issuedDate": "2021-06-01", "owner": { "nameOrCompany": null, "givenNames": null, "address": null }, "inspection": { "nextInspectionMonthYear": null, "lastInspectionDate": null, "inspectionPlace": null }, "vehicle": { "vin": "TAPSANDBX00000001", "hsn": "9999", "tsn": "SBX1", "brand": "Sandbox Motors", "modelCode": null, "commercialName": "Modell A", "vehicleClass": null, "bodyType": null, "fuel": null, "displacementCc": null, "powerKw": null, "co2GPerKm": null, "emissionsClass": null, "permissibleTotalMassF1": null, "permissibleTotalMassF2": null, "unladenMassKg": null, "axleLoads": null, "allowedTrailerMassBraked": null, "allowedTrailerMassUnbraked": null, "seatsTotal": null, "seatsDriverIncluded": null, "tireSizes": null }, "technicalDetailsRaw": { "rawTableLines": null }, "codesAndNotes": { "pCodes": null, "eTypeApproval": null, "otherNotes": null }, "rawTextLines": null, "notes": null } } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1registration-document/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1registration-document/post/responses/400/content/application~1json/schema", "schema": { "title": "ExtractRegistrationDocumentLegacyPath400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1scanner~1registration-document/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1registration-document/post/responses/401/content/application~1json/schema", "schema": { "title": "ExtractRegistrationDocumentLegacyPath401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1registration-document/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1registration-document/post/responses/402/content/application~1json/schema", "schema": { "title": "ExtractRegistrationDocumentLegacyPath402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1scanner~1registration-document/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1registration-document/post/responses/403/content/application~1json/schema", "schema": { "title": "ExtractRegistrationDocumentLegacyPath403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1registration-document/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1registration-document/post/responses/409/content/application~1json/schema", "schema": { "title": "ExtractRegistrationDocumentLegacyPath409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1registration-document/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1registration-document/post/responses/429/content/application~1json/schema", "schema": { "title": "ExtractRegistrationDocumentLegacyPath429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1registration-document/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1registration-document/post/responses/500/content/application~1json/schema", "schema": { "title": "ExtractRegistrationDocumentLegacyPath500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1registration-document/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1registration-document/post/responses/503/content/application~1json/schema", "schema": { "title": "ExtractRegistrationDocumentLegacyPath503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "service_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1scanner~1registration-document/post" }, { "operationId": "extractInternationalRegistrationDocument", "method": "POST", "path": "/scanner/document/registration/international", "tags": [ "Scanner" ], "summary": "Extract international vehicle registration documents", "description": "**Service description**\n\nExtract international vehicle registration documents. The request and response follow the schemas documented below.\n\n**Usage and legal notice**\n\nOnly `standard` is currently available for personal documents. Processing levels that are not offered must not be selected.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.\n\n**Field mapping and downloads**\n\nThe 34-column preview maps the canonical response fields to the codes printed by the 32 country profiles. National supplementary fields for Germany, Switzerland and the United Kingdom are included in the complete downloads.\n\n[Download Markdown](https://docs.tapinomahub.com/mappings/vehicle-registration-field-mapping.md) · [Download CSV](https://docs.tapinomahub.com/mappings/vehicle-registration-field-mapping.csv) · [Download JSON](https://docs.tapinomahub.com/mappings/vehicle-registration-field-mapping.json)\n\n[Preview](#vehicle-registration-fields)\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1registration~1international/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1scanner~1document~1registration~1international/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1registration~1international/post/requestBody/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "anyOf": [ { "required": [ "fileUrl" ] }, { "required": [ "imageUrl" ] }, { "required": [ "imageURL" ] } ], "properties": { "fileUrl": { "type": "string", "format": "uri", "description": "Publicly accessible URL of a document that the user is authorised to transmit and process.", "example": "https://example.com/registration-document.pdf" }, "imageUrl": { "type": "string", "format": "uri", "deprecated": true, "description": "Publicly accessible URL of an image that the user is authorised to transmit and process." }, "imageURL": { "type": "string", "format": "uri", "deprecated": true, "description": "Compatibility alias for fileUrl." }, "quality": { "$ref": "#/components/schemas/SensitiveDocumentQuality" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "fileUrl": "https://example.com/registration-document.pdf", "quality": "standard" } } ] } ] }, "responses": [ { "status": "200", "description": "Vehicle document analysed", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1registration~1international/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/RegistrationDocumentV2Response", "schemaPointer": "#/components/schemas/RegistrationDocumentV2Response", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "format": "tapinoma.vehicle-registration.v2", "document": { "countryCode": "DE", "countryName": "Germany", "profile": "eu-1999-37-ec", "variantId": "de-eu-1999-37-ec-part_i", "documentType": "Registration Certificate Part I", "documentPart": "part_i", "documentVersion": "current harmonized layout", "sourceLanguages": [ "de" ] }, "registration": { "registrationNumber": "SBX-TE 999", "documentNumber": "SBX0000000001", "issuingAuthority": "Sandbox Registration Authority", "firstRegistrationDate": "2021-05-18", "registrationDate": "2021-06-01" }, "holder": { "nameOrCompany": null, "givenNames": null, "address": null, "ownershipStatus": null }, "inspection": { "validUntil": "2027-06", "lastInspectionDate": null, "inspectionPlace": null }, "vehicle": { "vin": "TAPSANDBX00000001", "chassisNumber": null, "make": "Sandbox Motors", "type": "SBX-TYPE", "variant": "A", "version": "1", "commercialDescription": "Model A", "category": "M1", "bodyType": "hatchback", "fuelType": "petrol", "colour": "silver", "engineCapacityCc": "1498", "maximumNetPowerKw": "110", "maximumTechnicallyPermissibleMassKg": "1980", "maximumPermissibleMassKg": "1980", "massInServiceKg": "1420", "maximumBrakedTrailerMassKg": "1500", "maximumUnbrakedTrailerMassKg": "750", "seatsIncludingDriver": "5", "standingPlaces": null, "typeApprovalNumber": "e1*2020/001*0001", "carbonDioxideEmissionsGPerKm": "118", "environmentalCategory": "Euro 6" }, "fields": [ { "scope": "document", "code": "document:title", "sourceCode": null, "name": "Document title", "value": "Registration Certificate Part I", "sourceValue": "Zulassungsbescheinigung Teil I" }, { "scope": "harmonized", "code": "A", "sourceCode": "A", "name": "Registration number", "value": "SBX-TE 999", "sourceValue": null }, { "scope": "harmonized", "code": "P.3", "sourceCode": "P.3", "name": "Fuel type or power source", "value": "petrol", "sourceValue": "BENZIN" }, { "scope": "harmonized", "code": "D.2.variant", "sourceCode": "D.2", "name": "Variant", "value": "A", "sourceValue": null }, { "scope": "national", "code": "2.1", "sourceCode": "2.1", "name": "German manufacturer key number (HSN)", "value": "9999", "sourceValue": null } ], "warnings": [] } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1registration~1international/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1registration~1international/post/responses/400/content/application~1json/schema", "schema": { "title": "ExtractInternationalRegistrationDocument400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1scanner~1document~1registration~1international/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1registration~1international/post/responses/401/content/application~1json/schema", "schema": { "title": "ExtractInternationalRegistrationDocument401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1registration~1international/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1registration~1international/post/responses/402/content/application~1json/schema", "schema": { "title": "ExtractInternationalRegistrationDocument402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1scanner~1document~1registration~1international/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1registration~1international/post/responses/403/content/application~1json/schema", "schema": { "title": "ExtractInternationalRegistrationDocument403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1document~1registration~1international/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1registration~1international/post/responses/409/content/application~1json/schema", "schema": { "title": "ExtractInternationalRegistrationDocument409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1document~1registration~1international/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1registration~1international/post/responses/429/content/application~1json/schema", "schema": { "title": "ExtractInternationalRegistrationDocument429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Document analysis failed", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1registration~1international/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1registration~1international/post/responses/500/content/application~1json/schema", "schema": { "title": "ExtractInternationalRegistrationDocument500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1registration~1international/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1registration~1international/post/responses/503/content/application~1json/schema", "schema": { "title": "ExtractInternationalRegistrationDocument503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "service_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1scanner~1document~1registration~1international/post" }, { "operationId": "extractInternationalRegistrationDocumentLegacyPath", "method": "POST", "path": "/scanner/registration-document/v2", "tags": [ "Scanner" ], "summary": "Extract an international registration document (deprecated path)", "description": "**Service description**\n\nExtract an international registration document (deprecated path). The request and response follow the schemas documented below.\n\n**Usage and legal notice**\n\nOnly `standard` is currently available for personal documents. Processing levels that are not offered must not be selected.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.\n\n**Field mapping and downloads**\n\nThe 34-column preview maps the canonical response fields to the codes printed by the 32 country profiles. National supplementary fields for Germany, Switzerland and the United Kingdom are included in the complete downloads.\n\n[Download Markdown](https://docs.tapinomahub.com/mappings/vehicle-registration-field-mapping.md) · [Download CSV](https://docs.tapinomahub.com/mappings/vehicle-registration-field-mapping.csv) · [Download JSON](https://docs.tapinomahub.com/mappings/vehicle-registration-field-mapping.json)\n\n[Preview](#vehicle-registration-fields)\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1registration-document~1v2/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1scanner~1registration-document~1v2/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1registration-document~1v2/post/requestBody/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "anyOf": [ { "required": [ "fileUrl" ] }, { "required": [ "imageUrl" ] }, { "required": [ "imageURL" ] } ], "properties": { "fileUrl": { "type": "string", "format": "uri", "description": "Publicly accessible URL of a document that the user is authorised to transmit and process.", "example": "https://example.com/registration-document.pdf" }, "imageUrl": { "type": "string", "format": "uri", "deprecated": true, "description": "Publicly accessible URL of an image that the user is authorised to transmit and process." }, "imageURL": { "type": "string", "format": "uri", "deprecated": true, "description": "Compatibility alias for fileUrl." }, "quality": { "$ref": "#/components/schemas/SensitiveDocumentQuality" } } }, "exampleNames": [], "examples": [] } ] }, "responses": [ { "status": "200", "description": "Vehicle document analysed", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1registration-document~1v2/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/RegistrationDocumentV2Response", "schemaPointer": "#/components/schemas/RegistrationDocumentV2Response", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "format": "tapinoma.vehicle-registration.v2", "document": { "countryCode": "DE", "countryName": "Germany", "profile": "eu-1999-37-ec", "variantId": "de-eu-1999-37-ec-part_i", "documentType": "Registration Certificate Part I", "documentPart": "part_i", "documentVersion": "current harmonized layout", "sourceLanguages": [ "de" ] }, "registration": { "registrationNumber": "SBX-TE 999", "documentNumber": "SBX0000000001", "issuingAuthority": "Sandbox Registration Authority", "firstRegistrationDate": "2021-05-18", "registrationDate": "2021-06-01" }, "holder": { "nameOrCompany": null, "givenNames": null, "address": null, "ownershipStatus": null }, "inspection": { "validUntil": "2027-06", "lastInspectionDate": null, "inspectionPlace": null }, "vehicle": { "vin": "TAPSANDBX00000001", "chassisNumber": null, "make": "Sandbox Motors", "type": "SBX-TYPE", "variant": "A", "version": "1", "commercialDescription": "Model A", "category": "M1", "bodyType": "hatchback", "fuelType": "petrol", "colour": "silver", "engineCapacityCc": "1498", "maximumNetPowerKw": "110", "maximumTechnicallyPermissibleMassKg": "1980", "maximumPermissibleMassKg": "1980", "massInServiceKg": "1420", "maximumBrakedTrailerMassKg": "1500", "maximumUnbrakedTrailerMassKg": "750", "seatsIncludingDriver": "5", "standingPlaces": null, "typeApprovalNumber": "e1*2020/001*0001", "carbonDioxideEmissionsGPerKm": "118", "environmentalCategory": "Euro 6" }, "fields": [ { "scope": "document", "code": "document:title", "sourceCode": null, "name": "Document title", "value": "Registration Certificate Part I", "sourceValue": "Zulassungsbescheinigung Teil I" }, { "scope": "harmonized", "code": "A", "sourceCode": "A", "name": "Registration number", "value": "SBX-TE 999", "sourceValue": null }, { "scope": "harmonized", "code": "P.3", "sourceCode": "P.3", "name": "Fuel type or power source", "value": "petrol", "sourceValue": "BENZIN" }, { "scope": "harmonized", "code": "D.2.variant", "sourceCode": "D.2", "name": "Variant", "value": "A", "sourceValue": null }, { "scope": "national", "code": "2.1", "sourceCode": "2.1", "name": "German manufacturer key number (HSN)", "value": "9999", "sourceValue": null } ], "warnings": [] } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1registration-document~1v2/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1registration-document~1v2/post/responses/400/content/application~1json/schema", "schema": { "title": "ExtractInternationalRegistrationDocumentLegacyPath400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1scanner~1registration-document~1v2/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1registration-document~1v2/post/responses/401/content/application~1json/schema", "schema": { "title": "ExtractInternationalRegistrationDocumentLegacyPath401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1registration-document~1v2/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1registration-document~1v2/post/responses/402/content/application~1json/schema", "schema": { "title": "ExtractInternationalRegistrationDocumentLegacyPath402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1scanner~1registration-document~1v2/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1registration-document~1v2/post/responses/403/content/application~1json/schema", "schema": { "title": "ExtractInternationalRegistrationDocumentLegacyPath403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1registration-document~1v2/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1registration-document~1v2/post/responses/409/content/application~1json/schema", "schema": { "title": "ExtractInternationalRegistrationDocumentLegacyPath409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1registration-document~1v2/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1registration-document~1v2/post/responses/429/content/application~1json/schema", "schema": { "title": "ExtractInternationalRegistrationDocumentLegacyPath429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Document analysis failed", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1registration-document~1v2/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1registration-document~1v2/post/responses/500/content/application~1json/schema", "schema": { "title": "ExtractInternationalRegistrationDocumentLegacyPath500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1registration-document~1v2/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1registration-document~1v2/post/responses/503/content/application~1json/schema", "schema": { "title": "ExtractInternationalRegistrationDocumentLegacyPath503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "service_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1scanner~1registration-document~1v2/post" }, { "operationId": "extractLabelText", "method": "POST", "path": "/scanner/label/basic", "tags": [ "Scanner" ], "summary": "Detect text on a label", "description": "**Service description**\n\nDetect text on a label. The request and response follow the schemas documented below.\n\n**Usage and legal notice**\n\nFor endpoints with quality levels, `standard` is the default. Billing for `standard`, `enhanced` and `maximum` is governed exclusively by the contractually agreed terms. The levels may differ in processing scope and response time.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1basic/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1scanner~1label~1basic/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1basic/post/requestBody/content/application~1json/schema", "schema": { "type": "object", "required": [ "imageUrl" ], "properties": { "imageUrl": { "type": "string", "description": "Publicly accessible URL of an image that the user is authorised to transmit and process.", "format": "uri" }, "quality": { "$ref": "#/components/schemas/ScannerQuality" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "imageUrl": "https://example.com/label.jpg", "quality": "standard" } } ] } ] }, "responses": [ { "status": "200", "description": "Basic label analysis", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1label~1basic/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/LabelBasicResponse", "schemaPointer": "#/components/schemas/LabelBasicResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "hasPartNumber": true, "where": { "onLabel": false, "onPart": false } } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1label~1basic/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1basic/post/responses/400/content/application~1json/schema", "schema": { "title": "ExtractLabelText400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key", "invalid_json" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key", "invalid_json" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } }, { "name": "invalid_json", "value": { "error": "invalid_json", "message": "The request body is not valid JSON" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key", "invalid_json" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1scanner~1label~1basic/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1basic/post/responses/401/content/application~1json/schema", "schema": { "title": "ExtractLabelText401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1label~1basic/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1basic/post/responses/402/content/application~1json/schema", "schema": { "title": "ExtractLabelText402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1scanner~1label~1basic/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1basic/post/responses/403/content/application~1json/schema", "schema": { "title": "ExtractLabelText403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1label~1basic/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1basic/post/responses/409/content/application~1json/schema", "schema": { "title": "ExtractLabelText409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1label~1basic/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1basic/post/responses/429/content/application~1json/schema", "schema": { "title": "ExtractLabelText429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1label~1basic/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1basic/post/responses/500/content/application~1json/schema", "schema": { "title": "ExtractLabelText500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1label~1basic/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1basic/post/responses/503/content/application~1json/schema", "schema": { "title": "ExtractLabelText503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "service_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1scanner~1label~1basic/post" }, { "operationId": "extractLabelPartNumbers", "method": "POST", "path": "/scanner/label/extract-partnumbers", "tags": [ "Scanner" ], "summary": "Extract part numbers from a label", "description": "**Service description**\n\nAnalyses a label image and returns detected part and reference numbers in structured form.\n\n**Usage and legal notice**\n\nFor endpoints with quality levels, `standard` is the default. Billing for `standard`, `enhanced` and `maximum` is governed exclusively by the contractually agreed terms. The levels may differ in processing scope and response time.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.\n\n**Response format**\n\nProduction and sandbox use the same 200 response contract and the same lowerCamelCase field structure. The named examples differ only in their example values.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1extract-partnumbers/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1scanner~1label~1extract-partnumbers/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/LabelExtractPartNumbersRequest", "schemaPointer": "#/components/schemas/LabelExtractPartNumbersRequest", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "imageUrl": "https://example.com/label.jpg", "quality": "enhanced" } } ] } ] }, "responses": [ { "status": "200", "description": "Extracted part numbers", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1label~1extract-partnumbers/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/LabelExtractPartNumbersResponse", "schemaPointer": "#/components/schemas/LabelExtractPartNumbersResponse", "exampleNames": [ "production", "sandbox" ], "examples": [ { "name": "production", "value": { "partNumbers": [ "5Q0959655AA", "3G0907530AC" ] } }, { "name": "sandbox", "value": { "partNumbers": [ "SBX0001A", "SBX0002B" ] } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1label~1extract-partnumbers/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1extract-partnumbers/post/responses/400/content/application~1json/schema", "schema": { "title": "ExtractLabelPartNumbers400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1scanner~1label~1extract-partnumbers/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1extract-partnumbers/post/responses/401/content/application~1json/schema", "schema": { "title": "ExtractLabelPartNumbers401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1label~1extract-partnumbers/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1extract-partnumbers/post/responses/402/content/application~1json/schema", "schema": { "title": "ExtractLabelPartNumbers402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1scanner~1label~1extract-partnumbers/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1extract-partnumbers/post/responses/403/content/application~1json/schema", "schema": { "title": "ExtractLabelPartNumbers403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1label~1extract-partnumbers/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1extract-partnumbers/post/responses/409/content/application~1json/schema", "schema": { "title": "ExtractLabelPartNumbers409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1label~1extract-partnumbers/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1extract-partnumbers/post/responses/429/content/application~1json/schema", "schema": { "title": "ExtractLabelPartNumbers429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1label~1extract-partnumbers/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1extract-partnumbers/post/responses/500/content/application~1json/schema", "schema": { "title": "ExtractLabelPartNumbers500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1label~1extract-partnumbers/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1extract-partnumbers/post/responses/503/content/application~1json/schema", "schema": { "title": "ExtractLabelPartNumbers503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "service_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1scanner~1label~1extract-partnumbers/post" }, { "operationId": "extractLabelDetails", "method": "POST", "path": "/scanner/label/extract-all", "tags": [ "Scanner" ], "summary": "Extract all detectable label information", "description": "**Service description**\n\nAnalyses a label image and returns all structured information detected with sufficient confidence.\n\n**Usage and legal notice**\n\nFor endpoints with quality levels, `standard` is the default. Billing for `standard`, `enhanced` and `maximum` is governed exclusively by the contractually agreed terms. The levels may differ in processing scope and response time.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.\n\n**Response format**\n\nProduction and sandbox use the same 200 response contract and the same lowerCamelCase field structure. The named examples differ only in their example values.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1extract-all/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1scanner~1label~1extract-all/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1extract-all/post/requestBody/content/application~1json/schema", "schema": { "type": "object", "properties": { "imageUrl": { "type": "string", "description": "Publicly accessible URL of an image that the user is authorised to transmit and process.", "format": "uri" }, "quality": { "$ref": "#/components/schemas/ScannerQuality" }, "imageURL": { "type": "string", "format": "uri", "deprecated": true, "description": "Deprecated alias for imageUrl; new integrations should use imageUrl." } }, "additionalProperties": false, "anyOf": [ { "required": [ "imageUrl" ] }, { "required": [ "imageURL" ] } ] }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "imageUrl": "https://example.com/label.jpg", "quality": "maximum" } } ] } ] }, "responses": [ { "status": "200", "description": "Full label extraction", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1label~1extract-all/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/LabelExtractAllEnvelopeResponse", "schemaPointer": "#/components/schemas/LabelExtractAllEnvelopeResponse", "exampleNames": [ "production", "sandbox" ], "examples": [ { "name": "production", "value": { "status": "ok", "data": { "primaryPartNumber": "5Q0959655AA", "otherPartNumbers": [ "3G0907530AC" ], "manufacturer": "Continental", "notes": [ "12 V" ] } } }, { "name": "sandbox", "value": { "status": "ok", "data": { "primaryPartNumber": "SBX0001A", "otherPartNumbers": [ "SBX0002B" ], "manufacturer": "Sandbox Motors", "notes": [ "sandbox_fixture" ] } } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1label~1extract-all/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1extract-all/post/responses/400/content/application~1json/schema", "schema": { "title": "ExtractLabelDetails400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1scanner~1label~1extract-all/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1extract-all/post/responses/401/content/application~1json/schema", "schema": { "title": "ExtractLabelDetails401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1label~1extract-all/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1extract-all/post/responses/402/content/application~1json/schema", "schema": { "title": "ExtractLabelDetails402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1scanner~1label~1extract-all/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1extract-all/post/responses/403/content/application~1json/schema", "schema": { "title": "ExtractLabelDetails403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1label~1extract-all/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1extract-all/post/responses/409/content/application~1json/schema", "schema": { "title": "ExtractLabelDetails409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1label~1extract-all/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1extract-all/post/responses/429/content/application~1json/schema", "schema": { "title": "ExtractLabelDetails429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1label~1extract-all/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1extract-all/post/responses/500/content/application~1json/schema", "schema": { "title": "ExtractLabelDetails500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1label~1extract-all/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1label~1extract-all/post/responses/503/content/application~1json/schema", "schema": { "title": "ExtractLabelDetails503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "service_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1scanner~1label~1extract-all/post" }, { "operationId": "extractCalculationDocument", "method": "POST", "path": "/scanner/document/calculation", "tags": [ "Scanner" ], "summary": "Extract a repair calculation including equipment", "description": "**Service description**\n\nExtract a repair calculation including equipment. The request and response follow the schemas documented below.\n\n**Usage and legal notice**\n\nOnly `standard` is currently available for personal documents. Processing levels that are not offered must not be selected.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1calculation/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1scanner~1document~1calculation/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1calculation/post/requestBody/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "fileUrl" ], "properties": { "fileUrl": { "type": "string", "format": "uri", "description": "Publicly accessible URL of a document that the user is authorised to transmit and process.", "example": "https://example.com/document.pdf" }, "quality": { "$ref": "#/components/schemas/SensitiveDocumentQuality" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "fileUrl": "https://example.com/gutachten.pdf", "quality": "standard" } } ] } ] }, "responses": [ { "status": "200", "description": "Document analysed successfully", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1calculation/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/DocumentCalculationResponse", "schemaPointer": "#/components/schemas/DocumentCalculationResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "documentType": "repair_cost_calculation", "documentSubType": "Repair calculation", "source": { "language": "de" }, "document": { "referenceNumber": null, "orderNumber": null, "reportDate": null, "incidentDate": null, "inspectionDate": null }, "vehicle": { "vin": null, "licensePlate": null, "manufacturer": null, "model": null, "type": null, "firstRegistration": null, "mileageKm": null, "fuelType": null, "powerKw": null, "color": null }, "equipment": [ { "codes": [], "name": "Longlife-Service", "equipmentKind": "standard", "availability": "series", "isPackage": null, "category": null, "sourceSection": "Serienausstattung", "listPrice": { "net": null, "gross": null, "currency": null }, "quantity": null, "sourcePage": 1 }, { "codes": [], "name": "Ablage- und Gepäckraum-Paket", "equipmentKind": "special", "availability": "option_price_unknown", "isPackage": true, "category": null, "sourceSection": "Sonderausstattung", "listPrice": { "net": null, "gross": null, "currency": null }, "quantity": null, "sourcePage": 1 }, { "codes": [], "name": "Fußgänger-Schutzsystem", "equipmentKind": "special", "availability": "option_price_unknown", "isPackage": null, "category": null, "sourceSection": "Sonderausstattung", "listPrice": { "net": null, "gross": null, "currency": null }, "quantity": null, "sourcePage": 2 } ], "financials": { "partsTotal": null, "laborTotal": null, "paintTotal": null, "repairNet": null, "vatAmount": null, "repairGross": null, "replacementValue": null, "residualValue": null, "differenceOfValues": null, "currency": null, "partsSubtotal": null, "partsAdjustments": [] }, "repairAssessment": { "economicallyRepairable": null, "technicallyRepairable": null, "immobilizationDays": null }, "parts": [], "labor": [], "paint": [], "notes": [ "sandbox_fixture" ] } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1calculation/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1calculation/post/responses/400/content/application~1json/schema", "schema": { "title": "ExtractCalculationDocument400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key", "invalid_request" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key", "invalid_request" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } }, { "name": "invalid_request", "value": { "error": "invalid_request", "message": "The request is missing a required field" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key", "invalid_request" ] }, { "status": "401", "description": "API key missing or invalid", "headers": [], "openApiPointer": "#/paths/~1scanner~1document~1calculation/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1calculation/post/responses/401/content/application~1json/schema", "schema": { "title": "ExtractCalculationDocument401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1calculation/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1calculation/post/responses/402/content/application~1json/schema", "schema": { "title": "ExtractCalculationDocument402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1scanner~1document~1calculation/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1calculation/post/responses/403/content/application~1json/schema", "schema": { "title": "ExtractCalculationDocument403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1document~1calculation/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1calculation/post/responses/409/content/application~1json/schema", "schema": { "title": "ExtractCalculationDocument409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1document~1calculation/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1calculation/post/responses/429/content/application~1json/schema", "schema": { "title": "ExtractCalculationDocument429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Document analysis failed", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1calculation/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1calculation/post/responses/500/content/application~1json/schema", "schema": { "title": "ExtractCalculationDocument500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1calculation/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1calculation/post/responses/503/content/application~1json/schema", "schema": { "title": "ExtractCalculationDocument503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1scanner~1document~1calculation/post" }, { "operationId": "extractDocument", "method": "POST", "path": "/scanner/document/extract", "tags": [ "Scanner" ], "summary": "Extract calculation data (deprecated path)", "description": "**Service description**\n\nExtract calculation data (deprecated path). The request and response follow the schemas documented below.\n\n**Usage and legal notice**\n\nOnly `standard` is currently available for personal documents. Processing levels that are not offered must not be selected.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1extract/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1scanner~1document~1extract/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1extract/post/requestBody/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "fileUrl" ], "properties": { "fileUrl": { "type": "string", "format": "uri", "description": "Publicly accessible URL of a document that the user is authorised to transmit and process.", "example": "https://example.com/document.pdf" }, "quality": { "$ref": "#/components/schemas/SensitiveDocumentQuality" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "fileUrl": "https://example.com/gutachten.pdf", "quality": "standard" } } ] } ] }, "responses": [ { "status": "200", "description": "Document analysed successfully", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1extract/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/DocumentExtractionResponse", "schemaPointer": "#/components/schemas/DocumentExtractionResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "documentType": "sandbox_document", "documentSubType": null, "source": { "language": "de" }, "document": { "referenceNumber": null, "orderNumber": null, "reportDate": null, "incidentDate": null, "inspectionDate": null }, "vehicle": { "vin": null, "licensePlate": null, "manufacturer": null, "model": null, "type": null, "firstRegistration": null, "mileageKm": null, "fuelType": null, "powerKw": null, "color": null }, "financials": { "partsTotal": null, "laborTotal": null, "paintTotal": null, "repairNet": null, "vatAmount": null, "repairGross": null, "replacementValue": null, "residualValue": null, "differenceOfValues": null, "currency": null, "partsSubtotal": null, "partsAdjustments": [] }, "repairAssessment": { "economicallyRepairable": null, "technicallyRepairable": null, "immobilizationDays": null }, "parts": [], "labor": [], "paint": [], "notes": [ "sandbox_fixture" ] } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1extract/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1extract/post/responses/400/content/application~1json/schema", "schema": { "title": "ExtractDocument400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key", "invalid_request" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key", "invalid_request" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } }, { "name": "invalid_request", "value": { "error": "invalid_request", "message": "The request is missing a required field" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key", "invalid_request" ] }, { "status": "401", "description": "API key missing or invalid", "headers": [], "openApiPointer": "#/paths/~1scanner~1document~1extract/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1extract/post/responses/401/content/application~1json/schema", "schema": { "title": "ExtractDocument401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1extract/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1extract/post/responses/402/content/application~1json/schema", "schema": { "title": "ExtractDocument402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1scanner~1document~1extract/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1extract/post/responses/403/content/application~1json/schema", "schema": { "title": "ExtractDocument403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1document~1extract/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1extract/post/responses/409/content/application~1json/schema", "schema": { "title": "ExtractDocument409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1document~1extract/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1extract/post/responses/429/content/application~1json/schema", "schema": { "title": "ExtractDocument429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Document analysis failed", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1extract/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1extract/post/responses/500/content/application~1json/schema", "schema": { "title": "ExtractDocument500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1extract/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1extract/post/responses/503/content/application~1json/schema", "schema": { "title": "ExtractDocument503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1scanner~1document~1extract/post" }, { "operationId": "extractVehicleDocument", "method": "POST", "path": "/scanner/document/vehicle", "tags": [ "Scanner" ], "summary": "Extract vehicle data and equipment from a document", "description": "**Service description**\n\nExtract vehicle data and equipment from a document. The request and response follow the schemas documented below.\n\n**Usage and legal notice**\n\nOnly `standard` is currently available for personal documents. Processing levels that are not offered must not be selected.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1vehicle/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1scanner~1document~1vehicle/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1vehicle/post/requestBody/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "fileUrl" ], "properties": { "fileUrl": { "type": "string", "format": "uri", "example": "https://example.com/vehicle-order.pdf", "description": "Publicly accessible URL of a document that the user is authorised to transmit and process." }, "quality": { "$ref": "#/components/schemas/SensitiveDocumentQuality" }, "includeSensitiveData": { "type": "boolean", "default": false, "example": false, "description": "The public schema defines the meaning and format of `includeSensitiveData`." } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "fileUrl": "https://example.com/vehicle-order.pdf", "quality": "standard", "includeSensitiveData": false } } ] } ] }, "responses": [ { "status": "200", "description": "Document analysed successfully", "headers": [ "Cache-Control", "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1vehicle/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VehicleDocumentExtractionResponse", "schemaPointer": "#/components/schemas/VehicleDocumentExtractionResponse", "exampleNames": [ "sandbox", "sensitiveOptInSandbox" ], "examples": [ { "name": "sandbox", "value": { "schemaVersion": "1.0", "document": { "type": "vehicle_order", "title": null, "number": null, "date": null, "language": "de", "pageCount": 8 }, "vehicle": { "vin": "TAPSANDBX00000001", "displayName": "Sandbox Motors Modell A Elektro", "manufacturer": "Sandbox Motors", "model": "Modell A Elektro", "modelCode": "SBX-MODEL-01", "mainTypeGroup": "SBX-A", "type": "SBX-A1", "variant": "Testvariante", "manufacturerVariantCode": "SBX-VARIANT-01", "condition": "new", "bodyType": "SUV", "doors": 5, "seats": 5, "mileageKm": 0, "modelYear": 2099, "productionDate": "2098-12", "firstRegistration": null, "constructionPeriod": { "from": "2098-01", "until": null }, "powertrain": { "type": "electric", "fuelType": "electricity", "powerKw": 150, "powerPs": 204, "displacementCcm": null, "engineDescription": "Synthetischer Sandbox-Elektroantrieb", "engineCodes": [ { "codeSystem": "engine_code", "value": "SBX-E01", "normalizedValue": "SBXE01" } ], "driveType": "all-wheel drive", "emissionClass": "zero-emission vehicle" }, "transmission": { "type": "automatic", "description": "Single-speed transmission", "gears": 1, "codes": [ { "codeSystem": "transmission_code", "value": "SBX-AT1", "normalizedValue": "SBXAT1" } ] }, "energy": { "fuelConsumptionCombinedLPer100Km": null, "energyConsumptionCombinedKwhPer100Km": 20, "electricRangeCombinedKm": 400, "electricRangeCityKm": 450, "co2EmissionsCombinedGPerKm": 0, "co2Class": "A", "acceleration0To100Seconds": 8 }, "colors": [ { "type": "exterior", "name": "Sandboxblau Metallic", "codes": [ { "codeSystem": "paint_code", "value": "SBX-BLUE", "normalizedValue": "SBXBLUE" } ] }, { "type": "interior", "name": "Sandboxgrau", "codes": [ { "codeSystem": "color_code", "value": "SBX-GREY", "normalizedValue": "SBXGREY" } ] } ], "identifiers": [ { "codeSystem": "model_code", "value": "SBX-MODEL-01", "normalizedValue": "SBXMODEL01" }, { "codeSystem": "manufacturer_variant_code", "value": "SBX-VARIANT-01", "normalizedValue": "SBXVARIANT01" }, { "codeSystem": "kba_hsn", "value": "9999", "normalizedValue": "9999" }, { "codeSystem": "kba_tsn", "value": "SBX", "normalizedValue": "SBX" } ], "kba": { "hsn": "9999", "tsn": "SBX" } }, "equipment": [ { "codes": [ { "codeSystem": "manufacturer_order", "value": "SBX-EQP-001", "normalizedValue": "SBXEQP001" } ], "name": "Sandbox-Standardpaket", "equipmentKind": "standard", "availability": "series", "isPackage": false, "category": "Sandbox-Kategorie A", "sourceSection": "Serienausstattung", "listPrice": { "net": null, "gross": null, "currency": null }, "quantity": 1, "sourcePage": 2 }, { "codes": [ { "codeSystem": "manufacturer_order", "value": "SBX-EQP-002", "normalizedValue": "SBXEQP002" } ], "name": "Sandbox-Optionspaket", "equipmentKind": "special", "availability": "option_paid", "isPackage": false, "category": "Sandbox-Kategorie B", "sourceSection": "Sonderausstattung", "listPrice": { "net": 100, "gross": 119, "currency": "EUR" }, "quantity": 1, "sourcePage": 4 } ], "sensitiveData": { "included": false, "persons": [], "bankAccounts": [], "contract": { "contractNumber": null, "customerNumber": null, "contractType": null, "status": null, "signedDate": null, "startDate": null, "endDate": null, "durationMonths": null, "annualMileageKm": null, "totalMileageKm": null, "monthlyRate": { "net": null, "gross": null, "currency": null }, "totalAmount": { "net": null, "gross": null, "currency": null }, "paymentTerms": null, "fields": [] } }, "warnings": [] } }, { "name": "sensitiveOptInSandbox", "value": { "schemaVersion": "1.0", "document": { "type": "vehicle_order", "title": "Sandbox Fahrzeugbestellung", "number": "SBX-ORDER-0001", "date": "2099-01-01", "language": "de", "pageCount": 8 }, "vehicle": { "vin": "TAPSANDBX00000001", "displayName": "Sandbox Motors Modell A Elektro", "manufacturer": "Sandbox Motors", "model": "Modell A Elektro", "modelCode": "SBX-MODEL-01", "mainTypeGroup": "SBX-A", "type": "SBX-A1", "variant": "Testvariante", "manufacturerVariantCode": "SBX-VARIANT-01", "condition": "new", "bodyType": "SUV", "doors": 5, "seats": 5, "mileageKm": 0, "modelYear": 2099, "productionDate": "2098-12", "firstRegistration": null, "constructionPeriod": { "from": "2098-01", "until": null }, "powertrain": { "type": "electric", "fuelType": "electricity", "powerKw": 150, "powerPs": 204, "displacementCcm": null, "engineDescription": "Synthetischer Sandbox-Elektroantrieb", "engineCodes": [ { "codeSystem": "engine_code", "value": "SBX-E01", "normalizedValue": "SBXE01" } ], "driveType": "all-wheel drive", "emissionClass": "zero-emission vehicle" }, "transmission": { "type": "automatic", "description": "Single-speed transmission", "gears": 1, "codes": [ { "codeSystem": "transmission_code", "value": "SBX-AT1", "normalizedValue": "SBXAT1" } ] }, "energy": { "fuelConsumptionCombinedLPer100Km": null, "energyConsumptionCombinedKwhPer100Km": 20, "electricRangeCombinedKm": 400, "electricRangeCityKm": 450, "co2EmissionsCombinedGPerKm": 0, "co2Class": "A", "acceleration0To100Seconds": 8 }, "colors": [ { "type": "exterior", "name": "Sandboxblau Metallic", "codes": [ { "codeSystem": "paint_code", "value": "SBX-BLUE", "normalizedValue": "SBXBLUE" } ] }, { "type": "interior", "name": "Sandboxgrau", "codes": [ { "codeSystem": "color_code", "value": "SBX-GREY", "normalizedValue": "SBXGREY" } ] } ], "identifiers": [ { "codeSystem": "model_code", "value": "SBX-MODEL-01", "normalizedValue": "SBXMODEL01" }, { "codeSystem": "manufacturer_variant_code", "value": "SBX-VARIANT-01", "normalizedValue": "SBXVARIANT01" }, { "codeSystem": "kba_hsn", "value": "9999", "normalizedValue": "9999" }, { "codeSystem": "kba_tsn", "value": "SBX", "normalizedValue": "SBX" } ], "kba": { "hsn": "9999", "tsn": "SBX" } }, "equipment": [ { "codes": [ { "codeSystem": "manufacturer_order", "value": "SBX-EQP-001", "normalizedValue": "SBXEQP001" } ], "name": "Sandbox-Standardpaket", "equipmentKind": "standard", "availability": "series", "isPackage": false, "category": "Sandbox-Kategorie A", "sourceSection": "Serienausstattung", "listPrice": { "net": null, "gross": null, "currency": null }, "quantity": 1, "sourcePage": 2 }, { "codes": [ { "codeSystem": "manufacturer_order", "value": "SBX-EQP-002", "normalizedValue": "SBXEQP002" } ], "name": "Sandbox-Optionspaket", "equipmentKind": "special", "availability": "option_paid", "isPackage": false, "category": "Sandbox-Kategorie B", "sourceSection": "Sonderausstattung", "listPrice": { "net": 100, "gross": 119, "currency": "EUR" }, "quantity": 1, "sourcePage": 4 } ], "sensitiveData": { "included": true, "persons": [ { "role": "customer", "name": "Sandbox Testperson", "company": "Sandbox Handels GmbH", "email": "fahrzeug@sandbox.invalid", "phone": "+00 000 000000", "address": { "fullText": "Sandboxstrasse 1, 00000 Sandboxstadt", "street": "Sandboxstrasse", "houseNumber": "1", "postalCode": "00000", "city": "Sandboxstadt", "country": "Testland" }, "sourcePage": 1 } ], "bankAccounts": [ { "accountHolder": "Sandbox Handels GmbH", "iban": "DE00000000000000000000", "bic": "SBXTEST0XXX", "bankName": "Sandbox Bank", "sourcePage": 7 } ], "contract": { "contractNumber": "SBX-CONTRACT-0001", "customerNumber": "SBX-CUSTOMER-0001", "contractType": "sandbox_contract", "status": "test", "signedDate": null, "startDate": "2099-02-01", "endDate": "2102-01-31", "durationMonths": 36, "annualMileageKm": 12000, "totalMileageKm": 36000, "monthlyRate": { "net": 100, "gross": 119, "currency": "EUR" }, "totalAmount": { "net": 3600, "gross": 4284, "currency": "EUR" }, "paymentTerms": "sandbox monthly", "fields": [ { "label": "Special payment", "value": "0.00 EUR", "sourcePage": 3 } ] } }, "warnings": [] } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "Cache-Control", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1vehicle/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1vehicle/post/responses/400/content/application~1json/schema", "schema": { "title": "ExtractVehicleDocument400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "idempotency_key_not_supported", "invalid_idempotency_key", "invalid_request" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "idempotency_key_not_supported", "invalid_idempotency_key", "invalid_request" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } }, { "name": "invalid_request", "value": { "error": "invalid_request", "message": "The request is missing a required field" } } ] } ], "errorCodes": [ "bad_request", "idempotency_key_not_supported", "invalid_idempotency_key", "invalid_request" ] }, { "status": "401", "description": "API key is missing", "headers": [ "Cache-Control" ], "openApiPointer": "#/paths/~1scanner~1document~1vehicle/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1vehicle/post/responses/401/content/application~1json/schema", "schema": { "title": "ExtractVehicleDocument401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "Cache-Control", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1vehicle/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1vehicle/post/responses/402/content/application~1json/schema", "schema": { "title": "ExtractVehicleDocument402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [ "Cache-Control" ], "openApiPointer": "#/paths/~1scanner~1document~1vehicle/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1vehicle/post/responses/403/content/application~1json/schema", "schema": { "title": "ExtractVehicleDocument403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Cache-Control", "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1document~1vehicle/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1vehicle/post/responses/409/content/application~1json/schema", "schema": { "title": "ExtractVehicleDocument409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Cache-Control", "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1document~1vehicle/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1vehicle/post/responses/429/content/application~1json/schema", "schema": { "title": "ExtractVehicleDocument429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Document analysis failed", "headers": [ "Cache-Control", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1vehicle/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1vehicle/post/responses/500/content/application~1json/schema", "schema": { "title": "ExtractVehicleDocument500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "Cache-Control", "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1document~1vehicle/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1document~1vehicle/post/responses/503/content/application~1json/schema", "schema": { "title": "ExtractVehicleDocument503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1scanner~1document~1vehicle/post" }, { "operationId": "extractVehicleDocumentLegacyPath", "method": "POST", "path": "/scanner/vehicle-document/extract", "tags": [ "Scanner" ], "summary": "Extract vehicle data (deprecated path)", "description": "**Service description**\n\nExtract vehicle data (deprecated path). The request and response follow the schemas documented below.\n\n**Usage and legal notice**\n\nOnly `standard` is currently available for personal documents. Processing levels that are not offered must not be selected.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1vehicle-document~1extract/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1scanner~1vehicle-document~1extract/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1vehicle-document~1extract/post/requestBody/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "fileUrl" ], "properties": { "fileUrl": { "type": "string", "format": "uri", "example": "https://example.com/vehicle-order.pdf", "description": "Publicly accessible URL of a document that the user is authorised to transmit and process." }, "quality": { "$ref": "#/components/schemas/SensitiveDocumentQuality" }, "includeSensitiveData": { "type": "boolean", "default": false, "example": false, "description": "The public schema defines the meaning and format of `includeSensitiveData`." } } }, "exampleNames": [], "examples": [] } ] }, "responses": [ { "status": "200", "description": "Document analysed successfully", "headers": [ "Cache-Control", "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1vehicle-document~1extract/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VehicleDocumentExtractionResponse", "schemaPointer": "#/components/schemas/VehicleDocumentExtractionResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "schemaVersion": "1.0", "document": { "type": "vehicle_order", "title": null, "number": null, "date": null, "language": "de", "pageCount": 8 }, "vehicle": { "vin": "TAPSANDBX00000001", "displayName": "Sandbox Motors Modell A Elektro", "manufacturer": "Sandbox Motors", "model": "Modell A Elektro", "modelCode": "SBX-MODEL-01", "mainTypeGroup": "SBX-A", "type": "SBX-A1", "variant": "Testvariante", "manufacturerVariantCode": "SBX-VARIANT-01", "condition": "new", "bodyType": "SUV", "doors": 5, "seats": 5, "mileageKm": 0, "modelYear": 2099, "productionDate": "2098-12", "firstRegistration": null, "constructionPeriod": { "from": "2098-01", "until": null }, "powertrain": { "type": "electric", "fuelType": "electricity", "powerKw": 150, "powerPs": 204, "displacementCcm": null, "engineDescription": "Synthetischer Sandbox-Elektroantrieb", "engineCodes": [ { "codeSystem": "engine_code", "value": "SBX-E01", "normalizedValue": "SBXE01" } ], "driveType": "all-wheel drive", "emissionClass": "zero-emission vehicle" }, "transmission": { "type": "automatic", "description": "Single-speed transmission", "gears": 1, "codes": [ { "codeSystem": "transmission_code", "value": "SBX-AT1", "normalizedValue": "SBXAT1" } ] }, "energy": { "fuelConsumptionCombinedLPer100Km": null, "energyConsumptionCombinedKwhPer100Km": 20, "electricRangeCombinedKm": 400, "electricRangeCityKm": 450, "co2EmissionsCombinedGPerKm": 0, "co2Class": "A", "acceleration0To100Seconds": 8 }, "colors": [ { "type": "exterior", "name": "Sandboxblau Metallic", "codes": [ { "codeSystem": "paint_code", "value": "SBX-BLUE", "normalizedValue": "SBXBLUE" } ] }, { "type": "interior", "name": "Sandboxgrau", "codes": [ { "codeSystem": "color_code", "value": "SBX-GREY", "normalizedValue": "SBXGREY" } ] } ], "identifiers": [ { "codeSystem": "model_code", "value": "SBX-MODEL-01", "normalizedValue": "SBXMODEL01" }, { "codeSystem": "manufacturer_variant_code", "value": "SBX-VARIANT-01", "normalizedValue": "SBXVARIANT01" }, { "codeSystem": "kba_hsn", "value": "9999", "normalizedValue": "9999" }, { "codeSystem": "kba_tsn", "value": "SBX", "normalizedValue": "SBX" } ], "kba": { "hsn": "9999", "tsn": "SBX" } }, "equipment": [ { "codes": [ { "codeSystem": "manufacturer_order", "value": "SBX-EQP-001", "normalizedValue": "SBXEQP001" } ], "name": "Sandbox-Standardpaket", "equipmentKind": "standard", "availability": "series", "isPackage": false, "category": "Sandbox-Kategorie A", "sourceSection": "Serienausstattung", "listPrice": { "net": null, "gross": null, "currency": null }, "quantity": 1, "sourcePage": 2 }, { "codes": [ { "codeSystem": "manufacturer_order", "value": "SBX-EQP-002", "normalizedValue": "SBXEQP002" } ], "name": "Sandbox-Optionspaket", "equipmentKind": "special", "availability": "option_paid", "isPackage": false, "category": "Sandbox-Kategorie B", "sourceSection": "Sonderausstattung", "listPrice": { "net": 100, "gross": 119, "currency": "EUR" }, "quantity": 1, "sourcePage": 4 } ], "sensitiveData": { "included": false, "persons": [], "bankAccounts": [], "contract": { "contractNumber": null, "customerNumber": null, "contractType": null, "status": null, "signedDate": null, "startDate": null, "endDate": null, "durationMonths": null, "annualMileageKm": null, "totalMileageKm": null, "monthlyRate": { "net": null, "gross": null, "currency": null }, "totalAmount": { "net": null, "gross": null, "currency": null }, "paymentTerms": null, "fields": [] } }, "warnings": [] } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "Cache-Control", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1vehicle-document~1extract/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1vehicle-document~1extract/post/responses/400/content/application~1json/schema", "schema": { "title": "ExtractVehicleDocumentLegacyPath400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "idempotency_key_not_supported", "invalid_idempotency_key", "invalid_request" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "idempotency_key_not_supported", "invalid_idempotency_key", "invalid_request" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } }, { "name": "invalid_request", "value": { "error": "invalid_request", "message": "The request is missing a required field" } } ] } ], "errorCodes": [ "bad_request", "idempotency_key_not_supported", "invalid_idempotency_key", "invalid_request" ] }, { "status": "401", "description": "API key is missing", "headers": [ "Cache-Control" ], "openApiPointer": "#/paths/~1scanner~1vehicle-document~1extract/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1vehicle-document~1extract/post/responses/401/content/application~1json/schema", "schema": { "title": "ExtractVehicleDocumentLegacyPath401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "Cache-Control", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1vehicle-document~1extract/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1vehicle-document~1extract/post/responses/402/content/application~1json/schema", "schema": { "title": "ExtractVehicleDocumentLegacyPath402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [ "Cache-Control" ], "openApiPointer": "#/paths/~1scanner~1vehicle-document~1extract/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1vehicle-document~1extract/post/responses/403/content/application~1json/schema", "schema": { "title": "ExtractVehicleDocumentLegacyPath403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Cache-Control", "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1vehicle-document~1extract/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1vehicle-document~1extract/post/responses/409/content/application~1json/schema", "schema": { "title": "ExtractVehicleDocumentLegacyPath409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Cache-Control", "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1vehicle-document~1extract/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1vehicle-document~1extract/post/responses/429/content/application~1json/schema", "schema": { "title": "ExtractVehicleDocumentLegacyPath429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Document analysis failed", "headers": [ "Cache-Control", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1vehicle-document~1extract/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1vehicle-document~1extract/post/responses/500/content/application~1json/schema", "schema": { "title": "ExtractVehicleDocumentLegacyPath500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "Cache-Control", "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1vehicle-document~1extract/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1vehicle-document~1extract/post/responses/503/content/application~1json/schema", "schema": { "title": "ExtractVehicleDocumentLegacyPath503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1scanner~1vehicle-document~1extract/post" }, { "operationId": "translatePartName", "method": "GET", "path": "/translation/translations", "tags": [ "Translation" ], "summary": "Translate one individual part designation", "description": "**Service description**\n\nTranslate one individual part designation. The request and response follow the schemas documented below.\n\n**Usage and legal notice**\n\nOnly one individual part designation is permitted per request. Titles or headings, product or offer titles, descriptions, sentences, lists, multiple part designations and any other content are prohibited. The user must be authorised to transmit and process the submitted designation.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "sourceLanguage", "in": "query", "required": true, "description": "Language of the single submitted part designation.", "schemaRef": null, "schemaPointer": "#/paths/~1translation~1translations/get/parameters/0/schema", "schema": { "type": "string", "maxLength": 20, "example": "de" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "de" } ], "openApiPointer": "#/paths/~1translation~1translations/get/parameters/0" }, { "name": "text", "in": "query", "required": true, "description": "Exactly one individual part designation. No titles, sentences, descriptions, lists or multiple part designations.", "schemaRef": null, "schemaPointer": "#/paths/~1translation~1translations/get/parameters/1/schema", "schema": { "type": "string", "maxLength": 1000, "example": "Bremsscheibe" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "Stoßfänger vorne" } ], "openApiPointer": "#/paths/~1translation~1translations/get/parameters/1" } ], "requestBody": null, "responses": [ { "status": "200", "description": "Part designation translations", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1translation~1translations/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/TranslationResponse", "schemaPointer": "#/components/schemas/TranslationResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "en": "Sandbox front bumper", "fr": "Pare-chocs avant sandbox", "es": "Parachoques delantero sandbox", "it": "Paraurti anteriore sandbox" } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1translation~1translations/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1translation~1translations/get/responses/400/content/application~1json/schema", "schema": { "title": "TranslatePartName400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported", "source_language_required", "source_language_too_long", "text_required", "text_too_long" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_not_supported", "source_language_required", "source_language_too_long", "text_required", "text_too_long" ], "examples": [ { "name": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } }, { "name": "source_language_required", "value": { "error": "source_language_required", "message": "sourceLanguage is required because the text language could not be detected" } }, { "name": "source_language_too_long", "value": { "error": "source_language_too_long", "message": "sourceLanguage must be a two-letter language code" } }, { "name": "text_required", "value": { "error": "text_required", "message": "text must not be empty" } }, { "name": "text_too_long", "value": { "error": "text_too_long", "message": "text exceeds the maximum length for this endpoint" } } ] } ], "errorCodes": [ "idempotency_key_not_supported", "source_language_required", "source_language_too_long", "text_required", "text_too_long" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1translation~1translations/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1translation~1translations/get/responses/401/content/application~1json/schema", "schema": { "title": "TranslatePartName401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1translation~1translations/get/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1translation~1translations/get/responses/402/content/application~1json/schema", "schema": { "title": "TranslatePartName402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1translation~1translations/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1translation~1translations/get/responses/403/content/application~1json/schema", "schema": { "title": "TranslatePartName403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1translation~1translations/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1translation~1translations/get/responses/429/content/application~1json/schema", "schema": { "title": "TranslatePartName429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [], "openApiPointer": "#/paths/~1translation~1translations/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1translation~1translations/get/responses/500/content/application~1json/schema", "schema": { "title": "TranslatePartName500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1translation~1translations/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1translation~1translations/get/responses/503/content/application~1json/schema", "schema": { "title": "TranslatePartName503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "service_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1translation~1translations/get" }, { "operationId": "listPlans", "method": "GET", "path": "/client/plans", "tags": [ "Client Admin" ], "summary": "List available standard and custom plans", "description": "**Service description**\n\nReturns the standard and custom plans visible to the authenticated master client, including endpoint configuration.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [], "requestBody": null, "responses": [ { "status": "200", "description": "Plan list", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1plans/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1plans/get/responses/200/content/application~1json/schema", "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } } } }, "exampleNames": [], "examples": [] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [], "openApiPointer": "#/paths/~1client~1plans/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1plans/get/responses/400/content/application~1json/schema", "schema": { "title": "ListPlans400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } ] } ], "errorCodes": [ "idempotency_key_not_supported" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1client~1plans/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1plans/get/responses/401/content/application~1json/schema", "schema": { "title": "ListPlans401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "Only master clients may manage plans", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1plans/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1plans/get/responses/403/content/application~1json/schema", "schema": { "title": "ListPlans403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "forbidden", "invalid_api_key", "sandbox_endpoint_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "forbidden", "invalid_api_key", "sandbox_endpoint_unavailable" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } }, { "name": "sandbox_endpoint_unavailable", "value": { "error": "sandbox_endpoint_unavailable", "message": "This endpoint has no sandbox fixture; use a production key" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "forbidden", "invalid_api_key", "sandbox_endpoint_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1client~1plans/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1plans/get/responses/429/content/application~1json/schema", "schema": { "title": "ListPlans429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1plans/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1plans/get/responses/500/content/application~1json/schema", "schema": { "title": "ListPlans500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1client~1plans/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1plans/get/responses/503/content/application~1json/schema", "schema": { "title": "ListPlans503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1client~1plans/get" }, { "operationId": "listSponsorshipGrants", "method": "GET", "path": "/client/sponsorship-grants", "tags": [ "Client Admin" ], "summary": "List Hub sponsorships issued by the ERP", "description": "**Service description**\n\nReturns all active and historical sponsorship grants issued by the authenticated ERP or master client. A grant expressly lets another tapinoma client use the sponsor’s plan and price conditions for selected endpoints in the `hub` channel. Any active client can be the beneficiary, a sub-user included.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [], "requestBody": null, "responses": [ { "status": "200", "description": "Sponsorship grants", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/SponsorshipGrantListResponse", "schemaPointer": "#/components/schemas/SponsorshipGrantListResponse", "exampleNames": [ "documented" ], "examples": [ { "name": "documented", "value": { "sponsorshipGrants": [ { "id": 15, "reference": "erp-customer-4711", "sponsor": { "clientId": 1001, "name": "ERP Integrator AG" }, "beneficiary": { "clientId": 4711, "name": "Werkstatt Nord GmbH" }, "endpointKeys": [ "vin.cart_check", "vin.parts", "vin.vehicle" ], "channels": [ "hub" ], "startsAt": "2026-08-16T00:00:00+02:00", "endsAt": null, "revokedAt": null, "active": true, "createdAt": "2026-08-15T14:03:27+00:00", "updatedAt": "2026-08-15T14:03:27+00:00" } ] } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [], "openApiPointer": "#/paths/~1client~1sponsorship-grants/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants/get/responses/400/content/application~1json/schema", "schema": { "title": "ListSponsorshipGrants400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } ] } ], "errorCodes": [ "idempotency_key_not_supported" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1client~1sponsorship-grants/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants/get/responses/401/content/application~1json/schema", "schema": { "title": "ListSponsorshipGrants401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "Not authorised to manage outgoing grants", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants/get/responses/403/content/application~1json/schema", "schema": { "title": "ListSponsorshipGrants403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "forbidden", "invalid_api_key", "sandbox_endpoint_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "forbidden", "invalid_api_key", "sandbox_endpoint_unavailable" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } }, { "name": "sandbox_endpoint_unavailable", "value": { "error": "sandbox_endpoint_unavailable", "message": "This endpoint has no sandbox fixture; use a production key" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "forbidden", "invalid_api_key", "sandbox_endpoint_unavailable" ] }, { "status": "404", "description": "Not found", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants/get/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants/get/responses/404/content/application~1json/schema", "schema": { "title": "ListSponsorshipGrants404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "not_found", "message": "No record matches the given identifier" } } ] } ], "errorCodes": [ "not_found" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants/get/responses/429/content/application~1json/schema", "schema": { "title": "ListSponsorshipGrants429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants/get/responses/500/content/application~1json/schema", "schema": { "title": "ListSponsorshipGrants500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1client~1sponsorship-grants/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants/get/responses/503/content/application~1json/schema", "schema": { "title": "ListSponsorshipGrants503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1client~1sponsorship-grants/get" }, { "operationId": "listReceivedSponsorshipGrants", "method": "GET", "path": "/client/sponsorship-grants/received", "tags": [ "Client Admin" ], "summary": "List sponsorships received by the current client", "description": "**Service description**\n\nList sponsorships received by the current client. The request and response follow the schemas documented below.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [], "requestBody": null, "responses": [ { "status": "200", "description": "Sponsorship grants", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1received/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/SponsorshipGrantListResponse", "schemaPointer": "#/components/schemas/SponsorshipGrantListResponse", "exampleNames": [ "documented" ], "examples": [ { "name": "documented", "value": { "sponsorshipGrants": [ { "id": 15, "reference": "erp-customer-4711", "sponsor": { "clientId": 1001, "name": "ERP Integrator AG" }, "beneficiary": { "clientId": 4711, "name": "Werkstatt Nord GmbH" }, "endpointKeys": [ "vin.cart_check", "vin.parts", "vin.vehicle" ], "channels": [ "hub" ], "startsAt": "2026-08-16T00:00:00+02:00", "endsAt": null, "revokedAt": null, "active": true, "createdAt": "2026-08-15T14:03:27+00:00", "updatedAt": "2026-08-15T14:03:27+00:00" } ] } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1received/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1received/get/responses/400/content/application~1json/schema", "schema": { "title": "ListReceivedSponsorshipGrants400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } ] } ], "errorCodes": [ "idempotency_key_not_supported" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1received/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1received/get/responses/401/content/application~1json/schema", "schema": { "title": "ListReceivedSponsorshipGrants401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "Invalid API key", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1received/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1received/get/responses/403/content/application~1json/schema", "schema": { "title": "ListReceivedSponsorshipGrants403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key", "sandbox_endpoint_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key", "sandbox_endpoint_unavailable" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } }, { "name": "sandbox_endpoint_unavailable", "value": { "error": "sandbox_endpoint_unavailable", "message": "This endpoint has no sandbox fixture; use a production key" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key", "sandbox_endpoint_unavailable" ] }, { "status": "404", "description": "Not found", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1received/get/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1received/get/responses/404/content/application~1json/schema", "schema": { "title": "ListReceivedSponsorshipGrants404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "not_found", "message": "No record matches the given identifier" } } ] } ], "errorCodes": [ "not_found" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1received/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1received/get/responses/429/content/application~1json/schema", "schema": { "title": "ListReceivedSponsorshipGrants429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1received/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1received/get/responses/500/content/application~1json/schema", "schema": { "title": "ListReceivedSponsorshipGrants500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1received/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1received/get/responses/503/content/application~1json/schema", "schema": { "title": "ListReceivedSponsorshipGrants503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1client~1sponsorship-grants~1received/get" }, { "operationId": "upsertSponsorshipGrant", "method": "PUT", "path": "/client/sponsorship-grants/{grantReference}", "tags": [ "Client Admin" ], "summary": "Actively issue or replace a Hub sponsorship", "description": "**Service description**\n\nIdempotently issues or replaces a sponsorship grant under the ERP-selected `grantReference`. The sponsor must actively trigger this operation with its API key. Only the trusted `hub` channel is currently supported; callers cannot select the channel through a request header. Usage and VIN entitlement remain assigned to the beneficiary client. The beneficiary pays first from its own plan and balance; only when neither carries the request does the sponsor step in with its plan and prices. If the sponsor releases the choice with `partnerTermsAllowed` and the beneficiary makes it through `PUT /client/sponsorship-grants/received/{grantReference}/billing-mode`, every covered request is billed on the sponsor terms instead and the beneficiary balance stays untouched; the beneficiary included quota still counts against it.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "grantReference", "in": "path", "required": true, "description": "Stable sponsor-selected reference for idempotent changes.", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put/parameters/0/schema", "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "erp-customer-4711" } ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put/parameters/0" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put/parameters/1/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put/parameters/1" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/SponsorshipGrantUpsertRequest", "schemaPointer": "#/components/schemas/SponsorshipGrantUpsertRequest", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "beneficiaryClientId": 4711, "endpointKeys": [ "vin.vehicle", "vin.parts", "vin.cart_check" ], "channels": [ "hub" ], "startsAt": "2026-08-16T00:00:00+02:00", "endsAt": null } } ] } ] }, "responses": [ { "status": "200", "description": "Sponsorship grant", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/SponsorshipGrantResponse", "schemaPointer": "#/components/schemas/SponsorshipGrantResponse", "exampleNames": [ "documented" ], "examples": [ { "name": "documented", "value": { "sponsorshipGrant": { "id": 15, "reference": "erp-customer-4711", "sponsor": { "clientId": 1001, "name": "ERP Integrator AG" }, "beneficiary": { "clientId": 4711, "name": "Werkstatt Nord GmbH" }, "endpointKeys": [ "vin.cart_check", "vin.parts", "vin.vehicle" ], "channels": [ "hub" ], "startsAt": "2026-08-16T00:00:00+02:00", "endsAt": null, "revokedAt": null, "active": true, "createdAt": "2026-08-15T14:03:27+00:00", "updatedAt": "2026-08-18T09:31:44+00:00" } } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid or non-executable sponsorship grant", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put/responses/400/content/application~1json/schema", "schema": { "title": "UpsertSponsorshipGrant400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put/responses/401/content/application~1json/schema", "schema": { "title": "UpsertSponsorshipGrant401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "Invalid or non-executable sponsorship grant", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put/responses/403/content/application~1json/schema", "schema": { "title": "UpsertSponsorshipGrant403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "forbidden", "invalid_api_key", "sandbox_endpoint_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "forbidden", "invalid_api_key", "sandbox_endpoint_unavailable" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } }, { "name": "sandbox_endpoint_unavailable", "value": { "error": "sandbox_endpoint_unavailable", "message": "This endpoint has no sandbox fixture; use a production key" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "forbidden", "invalid_api_key", "sandbox_endpoint_unavailable" ] }, { "status": "404", "description": "Invalid or non-executable sponsorship grant", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put/responses/404/content/application~1json/schema", "schema": { "title": "UpsertSponsorshipGrant404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "not_found", "message": "No record matches the given identifier" } } ] } ], "errorCodes": [ "not_found" ] }, { "status": "409", "description": "Invalid or non-executable sponsorship grant", "headers": [ "Retry-After", "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put/responses/409/content/application~1json/schema", "schema": { "title": "UpsertSponsorshipGrant409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable", "sponsorship_conflict" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable", "sponsorship_conflict" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } }, { "name": "sponsorship_conflict", "value": { "error": "sponsorship_conflict", "message": "A grant already exists under this grantReference with different terms" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable", "sponsorship_conflict" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put/responses/429/content/application~1json/schema", "schema": { "title": "UpsertSponsorshipGrant429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put/responses/500/content/application~1json/schema", "schema": { "title": "UpsertSponsorshipGrant500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put/responses/503/content/application~1json/schema", "schema": { "title": "UpsertSponsorshipGrant503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/put" }, { "operationId": "revokeSponsorshipGrant", "method": "DELETE", "path": "/client/sponsorship-grants/{grantReference}", "tags": [ "Client Admin" ], "summary": "Revoke a Hub sponsorship", "description": "**Service description**\n\nRevokes the grant identified by `grantReference` immediately for new Hub requests. Existing results and entitlements of the beneficiary client are not deleted.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "grantReference", "in": "path", "required": true, "description": "Stable sponsor-selected reference for idempotent changes.", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete/parameters/0/schema", "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "erp-customer-4711" } ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete/parameters/0" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete/parameters/1/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete/parameters/1" } ], "requestBody": null, "responses": [ { "status": "200", "description": "Sponsorship grant", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/SponsorshipGrantResponse", "schemaPointer": "#/components/schemas/SponsorshipGrantResponse", "exampleNames": [ "documented" ], "examples": [ { "name": "documented", "value": { "sponsorshipGrant": { "id": 15, "reference": "erp-customer-4711", "sponsor": { "clientId": 1001, "name": "ERP Integrator AG" }, "beneficiary": { "clientId": 4711, "name": "Werkstatt Nord GmbH" }, "endpointKeys": [ "vin.cart_check", "vin.parts", "vin.vehicle" ], "channels": [ "hub" ], "startsAt": "2026-08-16T00:00:00+02:00", "endsAt": null, "revokedAt": "2026-08-18T12:05:10+00:00", "active": false, "createdAt": "2026-08-15T14:03:27+00:00", "updatedAt": "2026-08-18T12:05:10+00:00" } } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete/responses/400/content/application~1json/schema", "schema": { "title": "RevokeSponsorshipGrant400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete/responses/401/content/application~1json/schema", "schema": { "title": "RevokeSponsorshipGrant401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "Invalid or non-executable sponsorship grant", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete/responses/403/content/application~1json/schema", "schema": { "title": "RevokeSponsorshipGrant403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "forbidden", "invalid_api_key", "sandbox_endpoint_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "forbidden", "invalid_api_key", "sandbox_endpoint_unavailable" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } }, { "name": "sandbox_endpoint_unavailable", "value": { "error": "sandbox_endpoint_unavailable", "message": "This endpoint has no sandbox fixture; use a production key" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "forbidden", "invalid_api_key", "sandbox_endpoint_unavailable" ] }, { "status": "404", "description": "Invalid or non-executable sponsorship grant", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete/responses/404/content/application~1json/schema", "schema": { "title": "RevokeSponsorshipGrant404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "not_found", "message": "No record matches the given identifier" } } ] } ], "errorCodes": [ "not_found" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete/responses/409/content/application~1json/schema", "schema": { "title": "RevokeSponsorshipGrant409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete/responses/429/content/application~1json/schema", "schema": { "title": "RevokeSponsorshipGrant429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete/responses/500/content/application~1json/schema", "schema": { "title": "RevokeSponsorshipGrant500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete/responses/503/content/application~1json/schema", "schema": { "title": "RevokeSponsorshipGrant503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1client~1sponsorship-grants~1{grantReference}/delete" }, { "operationId": "extractVinFromImage", "method": "POST", "path": "/scanner/vin/extract", "tags": [ "Scanner" ], "summary": "Extract a VIN from a vehicle image", "description": "**Service description**\n\nExtracts a visibly photographed, complete 17-character VIN from an image URL. Typical inputs include photographs through the windshield, identification plates, door-jamb labels and body stamps. When the complete VIN is not unambiguously readable, `vin` is returned as `null`.\n\n**Usage and legal notice**\n\nFor endpoints with quality levels, `standard` is the default. Billing for `standard`, `enhanced` and `maximum` is governed exclusively by the contractually agreed terms. The levels may differ in processing scope and response time.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1vin~1extract/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1scanner~1vin~1extract/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1vin~1extract/post/requestBody/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "imageUrl" ], "properties": { "imageUrl": { "type": "string", "format": "uri", "example": "https://example.com/vehicle-vin.jpg", "description": "Publicly accessible URL of an image that the user is authorised to transmit and process." }, "quality": { "$ref": "#/components/schemas/ScannerQuality" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "imageUrl": "https://example.com/vehicle-vin.jpg", "quality": "standard" } } ] } ] }, "responses": [ { "status": "200", "description": "VIN extracted", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1vin~1extract/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VinImageScanResponse", "schemaPointer": "#/components/schemas/VinImageScanResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "vin": "TAPSANDBX00000001" } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1vin~1extract/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1vin~1extract/post/responses/400/content/application~1json/schema", "schema": { "title": "ExtractVinFromImage400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1scanner~1vin~1extract/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1vin~1extract/post/responses/401/content/application~1json/schema", "schema": { "title": "ExtractVinFromImage401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1vin~1extract/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1vin~1extract/post/responses/402/content/application~1json/schema", "schema": { "title": "ExtractVinFromImage402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1scanner~1vin~1extract/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1vin~1extract/post/responses/403/content/application~1json/schema", "schema": { "title": "ExtractVinFromImage403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1vin~1extract/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1vin~1extract/post/responses/409/content/application~1json/schema", "schema": { "title": "ExtractVinFromImage409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1scanner~1vin~1extract/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1vin~1extract/post/responses/429/content/application~1json/schema", "schema": { "title": "ExtractVinFromImage429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "VIN extraction failed", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1vin~1extract/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1vin~1extract/post/responses/500/content/application~1json/schema", "schema": { "title": "ExtractVinFromImage500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1scanner~1vin~1extract/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1scanner~1vin~1extract/post/responses/503/content/application~1json/schema", "schema": { "title": "ExtractVinFromImage503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1scanner~1vin~1extract/post" }, { "operationId": "getVdiCatalog", "method": "GET", "path": "/vdi", "tags": [ "VDI" ], "summary": "Load the VDI 4081 catalog and its version", "description": "**Service description**\n\nReturns the published VDI 4081 catalog with its version, main groups and entries. OE assignments are not part of this endpoint.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of entries in the response, 1 to 500. Without it the endpoint returns the complete list as before. Each page is a separate call and is charged like a call.", "schemaRef": null, "schemaPointer": "#/paths/~1vdi/get/parameters/0/schema", "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": 100 } ], "openApiPointer": "#/paths/~1vdi/get/parameters/0" }, { "name": "offset", "in": "query", "required": false, "description": "Number of entries to skip; only allowed together with `limit`. `count` stays the total in every response, the length of the page is in `page.returned`.", "schemaRef": null, "schemaPointer": "#/paths/~1vdi/get/parameters/1/schema", "schema": { "type": "integer", "minimum": 0 }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": 0 } ], "openApiPointer": "#/paths/~1vdi/get/parameters/1" } ], "requestBody": null, "responses": [ { "status": "200", "description": "Current VDI 4081 catalogue", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vdi/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VdiCatalogResponse", "schemaPointer": "#/components/schemas/VdiCatalogResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "stand": { "catalogVersion": "5.7.1" }, "count": 1, "mainGroups": [ { "id": 1, "names": { "de": "Sandbox-Hauptgruppe", "en": "Sandbox main group" } } ], "entries": [ { "id": 900001, "code": "VDI4081_900001", "security": 0, "idExtension": "", "mainGroup": { "id": 1, "names": { "de": "Sandbox-Hauptgruppe", "en": "Sandbox main group" } }, "weight": 8.5, "name": "Stoßfänger vorne Sandbox", "nameEn": "Front bumper sandbox", "synonyms": [ "Frontstoßfänger Sandbox" ], "legacyId": null, "qualityGroup": null, "possibleInstallationLocations": [ "vorne" ], "possibleInstallationLocationsEn": [ "front" ], "filter": null, "shippingGroup": "S", "category2": null, "componentType": null } ] } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [], "openApiPointer": "#/paths/~1vdi/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vdi/get/responses/400/content/application~1json/schema", "schema": { "title": "GetVdiCatalog400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported", "invalid_query_parameter" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_not_supported", "invalid_query_parameter" ], "examples": [ { "name": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } }, { "name": "invalid_query_parameter", "value": { "error": "invalid_query_parameter", "message": "A query parameter has the wrong type or format" } } ] } ], "errorCodes": [ "idempotency_key_not_supported", "invalid_query_parameter" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vdi/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vdi/get/responses/401/content/application~1json/schema", "schema": { "title": "GetVdiCatalog401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vdi/get/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vdi/get/responses/402/content/application~1json/schema", "schema": { "title": "GetVdiCatalog402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1vdi/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vdi/get/responses/403/content/application~1json/schema", "schema": { "title": "GetVdiCatalog403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vdi/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vdi/get/responses/429/content/application~1json/schema", "schema": { "title": "GetVdiCatalog429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [], "openApiPointer": "#/paths/~1vdi/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vdi/get/responses/500/content/application~1json/schema", "schema": { "title": "GetVdiCatalog500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vdi/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vdi/get/responses/503/content/application~1json/schema", "schema": { "title": "GetVdiCatalog503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "vdi_catalog_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "vdi_catalog_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "vdi_catalog_unavailable", "value": { "error": "vdi_catalog_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "vdi_catalog_unavailable" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vdi/get" }, { "operationId": "normalizeOeNumber", "method": "GET", "path": "/parts/oe/normalize", "tags": [ "Parts" ], "summary": "Normalize and validate an OE number", "description": "**Service description**\n\nNormalises and validates an OE part number. The response distinguishes `matched`, `unresolved`, `ambiguous` and `invalid` and may contain documented replacement numbers.\n\n**Usage and legal notice**\n\nThe paid service consists solely of the technical comparison or analysis and delivery of the result. Rights in the result are granted only to the extent provided by the agreement. Use of the result is governed by the agreement and applicable law. Results may be incomplete, outdated or incorrect and must be independently verified before technical, commercial or legal use.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "oeNumber", "in": "query", "required": true, "description": "OE part number compared with available reference information.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1normalize/get/parameters/0/schema", "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "SBX 0001 A" } ], "openApiPointer": "#/paths/~1parts~1oe~1normalize/get/parameters/0" }, { "name": "manufacturer", "in": "query", "required": false, "description": "Optional manufacturer context for the request.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1normalize/get/parameters/1/schema", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "SANDBOX MOTORS" } ], "openApiPointer": "#/paths/~1parts~1oe~1normalize/get/parameters/1" } ], "requestBody": null, "responses": [ { "status": "200", "description": "OE normalisation result", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1normalize/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/OeNormalizationResponse", "schemaPointer": "#/components/schemas/OeNormalizationResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "version": "sandbox-oe-v1", "input": "SBX 0001 A", "manufacturer": "SANDBOX MOTORS", "status": "matched", "valid": true, "reasons": [], "lookupKey": "SBX0001A", "normalizedOeNumber": "SBX0001A", "matchRule": "sandbox_exact", "confidence": 1, "equivalentOeNumbers": [ "SBX0001B" ], "equivalentOeNumberCount": 1, "equivalentOeNumbersTruncated": false, "knownCandidates": [ { "value": "SBX0001A", "rule": "sandbox_exact", "manufacturers": [ "SANDBOX MOTORS" ] } ] } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid query parameter", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1normalize/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1normalize/get/responses/400/content/application~1json/schema", "schema": { "title": "NormalizeOeNumber400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported", "invalid_manufacturer", "invalid_oe_number", "invalid_query_parameter" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_not_supported", "invalid_manufacturer", "invalid_oe_number", "invalid_query_parameter" ], "examples": [ { "name": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } }, { "name": "invalid_manufacturer", "value": { "error": "invalid_manufacturer", "message": "manufacturer is not a known manufacturer" } }, { "name": "invalid_oe_number", "value": { "error": "invalid_oe_number", "message": "oeNumber must not be empty" } }, { "name": "invalid_query_parameter", "value": { "error": "invalid_query_parameter", "message": "A query parameter has the wrong type or format" } } ] } ], "errorCodes": [ "idempotency_key_not_supported", "invalid_manufacturer", "invalid_oe_number", "invalid_query_parameter" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1parts~1oe~1normalize/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1normalize/get/responses/401/content/application~1json/schema", "schema": { "title": "NormalizeOeNumber401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1normalize/get/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1normalize/get/responses/402/content/application~1json/schema", "schema": { "title": "NormalizeOeNumber402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1parts~1oe~1normalize/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1normalize/get/responses/403/content/application~1json/schema", "schema": { "title": "NormalizeOeNumber403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1parts~1oe~1normalize/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1normalize/get/responses/429/content/application~1json/schema", "schema": { "title": "NormalizeOeNumber429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1normalize/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1normalize/get/responses/500/content/application~1json/schema", "schema": { "title": "NormalizeOeNumber500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1normalize/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1normalize/get/responses/503/content/application~1json/schema", "schema": { "title": "NormalizeOeNumber503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "oe_normalizer_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "oe_normalizer_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "oe_normalizer_unavailable", "value": { "error": "oe_normalizer_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "oe_normalizer_unavailable" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1parts~1oe~1normalize/get" }, { "operationId": "getVehicleByTapiId", "method": "GET", "path": "/vehicles/{tapiId}", "tags": [ "Vehicles" ], "summary": "Get technical vehicle data by tapiId", "description": "**Service description**\n\nGet technical vehicle data by tapiId. The request and response follow the schemas documented below.\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "tapiId", "in": "path", "required": true, "description": "Stable vehicle reference from a VIN flow previously completed successfully for this client.", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1{tapiId}/get/parameters/0/schema", "schema": { "type": "string", "format": "uuid" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "5b1a1000-0000-4000-8000-000000000001" } ], "openApiPointer": "#/paths/~1vehicles~1{tapiId}/get/parameters/0" } ], "requestBody": null, "responses": [ { "status": "200", "description": "Determined vehicle data", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vehicles~1{tapiId}/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VehicleByTapiIdResponse", "schemaPointer": "#/components/schemas/VehicleByTapiIdResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "tapiId": "5b1a1000-0000-4000-8000-000000000001", "make": "Sandbox Motors", "model": "Modell A", "type": "1.5 TSI", "platform": "SBX-PLATFORM-1", "productionPeriod": "2020-03 - 2024-11", "productionFrom": "2020-03-01", "productionTo": "2024-11-30", "engineDescription": "1.5 TSI 110 kW", "displacementCcm": 1498, "powerKw": 110, "powerPs": 150, "hsnTsn": [ { "hsn": "9999", "tsn": "SBX1" } ], "technicalDetails": { "fuelType": "Benzin", "gearbox": "Schaltgetriebe", "driveType": "Frontantrieb", "doors": 5 }, "kTypes": [ 900001, 900002 ], "natCodes": [ "SBX0000001" ], "engineCodes": [ "SBXENG1" ], "transmissionCodes": [ "SBXTRM1" ], "colors": [ { "code": "SBX-SIL", "name": "Sandbox Silber", "type": "uni", "value": "#C0C0C0" } ], "updatedAt": "2026-01-01T00:00:00+00:00" } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [], "openApiPointer": "#/paths/~1vehicles~1{tapiId}/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1{tapiId}/get/responses/400/content/application~1json/schema", "schema": { "title": "GetVehicleByTapiId400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } ] } ], "errorCodes": [ "idempotency_key_not_supported" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vehicles~1{tapiId}/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1{tapiId}/get/responses/401/content/application~1json/schema", "schema": { "title": "GetVehicleByTapiId401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1vehicles~1{tapiId}/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1{tapiId}/get/responses/403/content/application~1json/schema", "schema": { "title": "GetVehicleByTapiId403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "404", "description": "Vehicle not found", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vehicles~1{tapiId}/get/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1{tapiId}/get/responses/404/content/application~1json/schema", "schema": { "title": "GetVehicleByTapiId404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found", "vehicle_not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "not_found", "vehicle_not_found" ], "examples": [ { "name": "not_found", "value": { "error": "not_found", "message": "No record matches the given identifier" } }, { "name": "vehicle_not_found", "value": { "error": "vehicle_not_found", "message": "No vehicle is known for this identifier" } } ] } ], "errorCodes": [ "not_found", "vehicle_not_found" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vehicles~1{tapiId}/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1{tapiId}/get/responses/429/content/application~1json/schema", "schema": { "title": "GetVehicleByTapiId429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vehicles~1{tapiId}/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1{tapiId}/get/responses/500/content/application~1json/schema", "schema": { "title": "GetVehicleByTapiId500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1vehicles~1{tapiId}/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1{tapiId}/get/responses/503/content/application~1json/schema", "schema": { "title": "GetVehicleByTapiId503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vehicles~1{tapiId}/get" }, { "operationId": "matchVehicleRecalls", "method": "GET", "path": "/recalls/vehicles/{vin}", "tags": [ "Recalls" ], "summary": "Recall match for a vehicle by VIN", "description": "**Service description**\n\nRecall match for a vehicle by VIN. The request and response follow the schemas documented below.\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "Vehicle identification number that the user must be authorised to transmit and process.", "schemaRef": null, "schemaPointer": "#/paths/~1recalls~1vehicles~1{vin}/get/parameters/0/schema", "schema": { "type": "string" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "TAPSANDBX00000001" } ], "openApiPointer": "#/paths/~1recalls~1vehicles~1{vin}/get/parameters/0" } ], "requestBody": null, "responses": [ { "status": "200", "description": "Match result for the vehicle", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1recalls~1vehicles~1{vin}/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/RecallVehicleMatchResponse", "schemaPointer": "#/components/schemas/RecallVehicleMatchResponse", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "vin": "TAPSANDBX00000001", "measures": [ { "reference": "12345R", "register": "kba", "publishedAt": "2025-07-01", "manufacturer": "Volkswagen", "tradeNames": [ "Golf VII" ], "buildPeriod": { "from": "2012-08-01", "until": "2019-12-31" }, "stopDrive": false, "component": "Airbag", "defect": { "de": "Der Gasgenerator des Fahrer-Airbags kann bersten.", "en": "The driver airbag gas generator can rupture.", "fr": "Le générateur de gaz de l'airbag conducteur peut éclater." }, "remedy": { "de": "Austausch des Airbag-Moduls.", "en": "Replacement of the airbag module.", "fr": "Remplacement du module d'airbag." }, "match": { "confidence": "strong", "matchedOn": [ "manufacturer", "model", "constructionPeriod" ] } } ], "measureCount": 1, "registers": [ { "register": "kba", "dataStand": "2026-08-15", "measureCount": 4180 } ], "notice": { "de": "Baureihenbezogene Auskunft aus den amtlichen Registern zum ausgewiesenen Datenstand. Ob ein einzelnes Fahrzeug betroffen und eine Massnahme dort erledigt ist, kann nur der Hersteller verbindlich beantworten. Ein leeres Ergebnis bedeutet ausschliesslich, dass der abgeglichene Datenbestand zum ausgewiesenen Stand keine Massnahmen enthaelt.", "en": "Series-level information from the official registers as of the stated data version. Only the manufacturer can confirm whether an individual vehicle is affected and whether a measure has been completed on it. An empty result means only that the matched data set contains no measures as of the stated version.", "fr": "Information au niveau de la série issue des registres officiels à la date de référence indiquée. Seul le constructeur peut confirmer si un véhicule précis est concerné et si une mesure y a été réalisée. Un résultat vide signifie uniquement que le jeu de données comparé ne contient aucune mesure à la date indiquée." } } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid VIN", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1recalls~1vehicles~1{vin}/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1recalls~1vehicles~1{vin}/get/responses/400/content/application~1json/schema", "schema": { "title": "MatchVehicleRecalls400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "idempotency_key_not_supported" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } ] } ], "errorCodes": [ "bad_request", "idempotency_key_not_supported" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1recalls~1vehicles~1{vin}/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1recalls~1vehicles~1{vin}/get/responses/401/content/application~1json/schema", "schema": { "title": "MatchVehicleRecalls401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1recalls~1vehicles~1{vin}/get/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1recalls~1vehicles~1{vin}/get/responses/402/content/application~1json/schema", "schema": { "title": "MatchVehicleRecalls402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1recalls~1vehicles~1{vin}/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1recalls~1vehicles~1{vin}/get/responses/403/content/application~1json/schema", "schema": { "title": "MatchVehicleRecalls403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "404", "description": "VIN cannot be resolved", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1recalls~1vehicles~1{vin}/get/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1recalls~1vehicles~1{vin}/get/responses/404/content/application~1json/schema", "schema": { "title": "MatchVehicleRecalls404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "vin_not_resolvable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "vin_not_resolvable", "message": "The VIN cannot be resolved to a vehicle series" } } ] } ], "errorCodes": [ "vin_not_resolvable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1recalls~1vehicles~1{vin}/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1recalls~1vehicles~1{vin}/get/responses/429/content/application~1json/schema", "schema": { "title": "MatchVehicleRecalls429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1recalls~1vehicles~1{vin}/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1recalls~1vehicles~1{vin}/get/responses/500/content/application~1json/schema", "schema": { "title": "MatchVehicleRecalls500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1recalls~1vehicles~1{vin}/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1recalls~1vehicles~1{vin}/get/responses/503/content/application~1json/schema", "schema": { "title": "MatchVehicleRecalls503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "recall_data_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "recall_data_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "recall_data_unavailable", "value": { "error": "recall_data_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "recall_data_unavailable" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1recalls~1vehicles~1{vin}/get" }, { "operationId": "matchPartRecalls", "method": "POST", "path": "/recalls/parts", "tags": [ "Recalls" ], "summary": "Recall match for a list of part numbers", "description": "**Service description**\n\nMatches up to 100 positions in one call against the recall and safety measures of the official registers. A position carries an OE number and optionally a vehicle context (`vehicle.make`, `vehicle.model`, build period). For the most reliable assignment, include the vehicle context when it is available. Each position states its status, measures and match confidence, together with the data version per register.\n\nIf no position can be assigned to a manufacturer, the call answers with `404`. Commercial treatment follows the terms shown before ordering and agreed in the contract. The information is series-level and is not a sales release.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1recalls~1parts/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1recalls~1parts/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/RecallPartsMatchRequest", "schemaPointer": "#/components/schemas/RecallPartsMatchRequest", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "positions": [ { "oeNumber": "SBX0001A", "reference": "pos-1", "vehicle": { "make": "Volkswagen", "model": "Golf VII", "productionFrom": 2012, "productionTo": 2019 } }, { "oeNumber": "SBX0002B", "reference": "pos-2" } ] } } ] } ] }, "responses": [ { "status": "200", "description": "Match result per position", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1recalls~1parts/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/RecallPartsMatchResponse", "schemaPointer": "#/components/schemas/RecallPartsMatchResponse", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "positions": [ { "oeNumber": "SBX0001A", "normalizedOeNumber": "SBX0001A", "reference": "pos-1", "status": "matched", "unresolvedReason": null, "measures": [ { "reference": "12345R", "register": "kba", "publishedAt": "2025-07-01", "manufacturer": "Volkswagen", "tradeNames": [ "Golf VII" ], "buildPeriod": { "from": "2012-08-01", "until": "2019-12-31" }, "stopDrive": false, "component": "Airbag", "defect": { "de": "Der Gasgenerator des Fahrer-Airbags kann bersten.", "en": "The driver airbag gas generator can rupture.", "fr": "Le générateur de gaz de l'airbag conducteur peut éclater." }, "remedy": { "de": "Austausch des Airbag-Moduls.", "en": "Replacement of the airbag module.", "fr": "Remplacement du module d'airbag." }, "match": { "confidence": "strong", "matchedOn": [ "manufacturer", "model", "constructionPeriod" ] } } ], "measureCount": 1 }, { "oeNumber": "SBX0002B", "normalizedOeNumber": "SBX0002B", "reference": "pos-2", "status": "no_measures", "unresolvedReason": null, "measures": [], "measureCount": 0 } ], "positionCount": 2, "resolvedCount": 2, "registers": [ { "register": "kba", "dataStand": "2026-08-15", "measureCount": 4180 } ], "notice": { "de": "Baureihenbezogene Auskunft aus den amtlichen Registern zum ausgewiesenen Datenstand. Ob ein einzelnes Fahrzeug betroffen und eine Massnahme dort erledigt ist, kann nur der Hersteller verbindlich beantworten. Ein leeres Ergebnis bedeutet ausschliesslich, dass der abgeglichene Datenbestand zum ausgewiesenen Stand keine Massnahmen enthaelt.", "en": "Series-level information from the official registers as of the stated data version. Only the manufacturer can confirm whether an individual vehicle is affected and whether a measure has been completed on it. An empty result means only that the matched data set contains no measures as of the stated version.", "fr": "Information au niveau de la série issue des registres officiels à la date de référence indiquée. Seul le constructeur peut confirmer si un véhicule précis est concerné et si une mesure y a été réalisée. Un résultat vide signifie uniquement que le jeu de données comparé ne contient aucune mesure à la date indiquée." } } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid position list", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1recalls~1parts/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1recalls~1parts/post/responses/400/content/application~1json/schema", "schema": { "title": "MatchPartRecalls400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key", "invalid_positions", "invalid_recall_position", "too_many_recall_positions" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key", "invalid_positions", "invalid_recall_position", "too_many_recall_positions" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } }, { "name": "invalid_positions", "value": { "error": "invalid_positions", "message": "positions must be a non-empty list" } }, { "name": "invalid_recall_position", "value": { "error": "invalid_recall_position", "message": "Every position needs an OE number or a vehicle make" } }, { "name": "too_many_recall_positions", "value": { "error": "too_many_recall_positions", "message": "A maximum of 100 positions is allowed per call" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key", "invalid_positions", "invalid_recall_position", "too_many_recall_positions" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1recalls~1parts/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1recalls~1parts/post/responses/401/content/application~1json/schema", "schema": { "title": "MatchPartRecalls401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1recalls~1parts/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1recalls~1parts/post/responses/402/content/application~1json/schema", "schema": { "title": "MatchPartRecalls402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1recalls~1parts/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1recalls~1parts/post/responses/403/content/application~1json/schema", "schema": { "title": "MatchPartRecalls403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "404", "description": "No position could be resolved", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1recalls~1parts/post/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1recalls~1parts/post/responses/404/content/application~1json/schema", "schema": { "title": "MatchPartRecalls404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "recall_positions_unresolvable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "recall_positions_unresolvable", "message": "None of the submitted positions could be resolved to a manufacturer" } } ] } ], "errorCodes": [ "recall_positions_unresolvable" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1recalls~1parts/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1recalls~1parts/post/responses/409/content/application~1json/schema", "schema": { "title": "MatchPartRecalls409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1recalls~1parts/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1recalls~1parts/post/responses/429/content/application~1json/schema", "schema": { "title": "MatchPartRecalls429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1recalls~1parts/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1recalls~1parts/post/responses/500/content/application~1json/schema", "schema": { "title": "MatchPartRecalls500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1recalls~1parts/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1recalls~1parts/post/responses/503/content/application~1json/schema", "schema": { "title": "MatchPartRecalls503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "recall_data_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "recall_data_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "recall_data_unavailable", "value": { "error": "recall_data_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "recall_data_unavailable" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1recalls~1parts/post" }, { "operationId": "getOePrice", "method": "GET", "path": "/parts/oe/{oeNumber}/price", "tags": [ "Intelligence" ], "summary": "Evaluate the price of an OE part", "description": "**Service description**\n\nReturns an indicative price evaluation for the OE part number and selected conditions. The output is not a binding purchase, sale or price guarantee.\n\n**Usage and legal notice**\n\nThe paid service consists solely of the technical comparison or analysis and delivery of the result. Rights in the result are granted only to the extent provided by the agreement. Use of the result is governed by the agreement and applicable law. Results may be incomplete, outdated or incorrect and must be independently verified before technical, commercial or legal use.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "oeNumber", "in": "path", "required": true, "description": "OE part number compared with available reference information.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/parameters/0/schema", "schema": { "type": "string" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "SBX0001A" } ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/parameters/0" }, { "name": "condition", "in": "query", "required": false, "description": "Part condition considered by the indicative price evaluation.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/parameters/1/schema", "schema": { "type": "string", "enum": [ "new", "used" ], "default": "used" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "used" } ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/parameters/1" }, { "name": "currency", "in": "query", "required": false, "description": "ISO 4217 currency code for monetary values in the response.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/parameters/2/schema", "schema": { "type": "string", "default": "EUR" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "EUR" } ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/parameters/2" }, { "name": "vehicleType", "in": "query", "required": false, "description": "Public parameter `vehicleType` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/parameters/3/schema", "schema": { "type": "string", "enum": [ "car", "motorcycle" ], "default": "car" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "car" } ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/parameters/3" } ], "requestBody": null, "responses": [ { "status": "200", "description": "Indicative price evaluation", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/PartPriceEvaluationResponse", "schemaPointer": "#/components/schemas/PartPriceEvaluationResponse", "exampleNames": [ "sandbox", "documented" ], "examples": [ { "name": "sandbox", "value": { "oeNumber": "SBX0001A", "currency": "EUR", "condition": "used", "result": "priced", "vehicleType": "car", "new": { "min": 168, "max": 340, "average": 244 }, "used": { "min": 89, "max": 219, "average": 142.5 }, "priceRecommendation": { "min": 89, "max": 219, "average": 142.5, "confidence": "MEDIUM" } } }, { "name": "documented", "value": { "oeNumber": "SBX0002B", "currency": "EUR", "condition": "used", "result": "priced", "vehicleType": "car", "new": { "min": 168, "max": 340, "average": 244 }, "used": { "min": 89, "max": 219, "average": 142.5 }, "priceRecommendation": { "min": 89, "max": 219, "average": 142.5, "confidence": "MEDIUM" } } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/responses/400/content/application~1json/schema", "schema": { "title": "GetOePrice400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } ] } ], "errorCodes": [ "idempotency_key_not_supported" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/responses/401/content/application~1json/schema", "schema": { "title": "GetOePrice401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/responses/402/content/application~1json/schema", "schema": { "title": "GetOePrice402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/responses/403/content/application~1json/schema", "schema": { "title": "GetOePrice403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "404", "description": "No price data available", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/responses/404/content/application~1json/schema", "schema": { "title": "GetOePrice404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "oe_part_not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "oe_part_not_found", "message": "No part is known for this OE number" } } ] } ], "errorCodes": [ "oe_part_not_found" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After", "X-Tapinoma-Billing-Source", "X-Tapinoma-Live-Available-At", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/responses/429/content/application~1json/schema", "schema": { "title": "GetOePrice429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/responses/500/content/application~1json/schema", "schema": { "title": "GetOePrice500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get/responses/503/content/application~1json/schema", "schema": { "title": "GetOePrice503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "service_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1parts~1oe~1{oeNumber}~1price/get" }, { "operationId": "describeDamageFromImages", "method": "POST", "path": "/vision/damage/describe", "tags": [ "Vision" ], "summary": "Describe damage from images", "description": "**Service description**\n\nAnalyses one to five images of the same damage on a vehicle or on an individual part and returns a condition description as text. The text follows a fixed skeleton of six sections in an unchanging order: part, deformation, scratches and scuffs, paint and corrosion, missing or damaged attachments, and other observations. A section without a finding is never dropped; it is explicitly reported as showing nothing, so the answer can be parsed reliably. `textQuality` governs only the wording inside the sections and never the skeleton. Only what is visible in the images is described; repair effort, cost and value are not part of the output. The text length is capped, and `truncated` reports when that cap was reached.\n\n**Usage and legal notice**\n\nFor endpoints with quality levels, `standard` is the default. Billing for `standard`, `enhanced` and `maximum` is governed exclusively by the contractually agreed terms. The levels may differ in processing scope and response time.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1damage~1describe/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1vision~1damage~1describe/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1damage~1describe/post/requestBody/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "imageUrls" ], "properties": { "imageUrls": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "string", "format": "uri" }, "description": "One to five publicly accessible image URLs of the same damage that the user is authorised to transmit and process.", "example": [ "https://example.com/schaden-1.jpg", "https://example.com/schaden-2.jpg" ] }, "quality": { "$ref": "#/components/schemas/ScannerQuality" }, "textQuality": { "$ref": "#/components/schemas/VisionTextQuality" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "imageUrls": [ "https://example.com/schaden-1.jpg", "https://example.com/schaden-2.jpg" ], "quality": "standard", "textQuality": "notes" } } ] } ] }, "responses": [ { "status": "200", "description": "Damage description generated", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1damage~1describe/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VisionDamageReportResponse", "schemaPointer": "#/components/schemas/VisionDamageReportResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "report": "# Schadensbeschreibung\n\n## Bauteil\n- Sandbox-Bauteil, ausgebaute Einzelteilaufnahme\n\n## Verformungen\n- keine erkennbar\n\n## Kratzer und Schrammen\n- horizontale Schleifspur im unteren Drittel, mittlere Tiefe\n\n## Lack und Korrosion\n- Lackdurchschliff an der unteren Kante, Grundierung sichtbar\n- kein Rostansatz erkennbar\n\n## Fehlende oder beschädigte Anbauteile\n- keine erkennbar\n\n## Sonstige Auffälligkeiten\n- Fixture-Antwort der Sandbox, kein Ergebnis einer Bildanalyse\n", "format": "tapinoma.damage-report.v1", "truncated": false } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1damage~1describe/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1damage~1describe/post/responses/400/content/application~1json/schema", "schema": { "title": "DescribeDamageFromImages400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vision~1damage~1describe/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1damage~1describe/post/responses/401/content/application~1json/schema", "schema": { "title": "DescribeDamageFromImages401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1damage~1describe/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1damage~1describe/post/responses/402/content/application~1json/schema", "schema": { "title": "DescribeDamageFromImages402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1vision~1damage~1describe/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1damage~1describe/post/responses/403/content/application~1json/schema", "schema": { "title": "DescribeDamageFromImages403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1damage~1describe/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1damage~1describe/post/responses/409/content/application~1json/schema", "schema": { "title": "DescribeDamageFromImages409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1damage~1describe/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1damage~1describe/post/responses/429/content/application~1json/schema", "schema": { "title": "DescribeDamageFromImages429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Damage analysis failed", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1damage~1describe/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1damage~1describe/post/responses/500/content/application~1json/schema", "schema": { "title": "DescribeDamageFromImages500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1damage~1describe/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1damage~1describe/post/responses/503/content/application~1json/schema", "schema": { "title": "DescribeDamageFromImages503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vision~1damage~1describe/post" }, { "operationId": "gradePartQualityFromImages", "method": "POST", "path": "/vision/part/quality", "tags": [ "Vision" ], "summary": "Determine a part quality grade from images", "description": "**Service description**\n\nAnalyses one to three images of the same used part and returns a quality grade of `A`, `B` or `C` together with the criteria it rests on. It is based on visual inspection alone; a function, noise or measurement test cannot be carried out on images, which is what `visualOnly` permanently indicates. Where no reliable statement is possible, `gradable` is `false`, `grade` stays `null` and `reason` states why. Anything limiting the assessment, such as soiling, image framing or lighting, is reported in `limitations`.\n\n**Usage and legal notice**\n\nFor endpoints with quality levels, `standard` is the default. Billing for `standard`, `enhanced` and `maximum` is governed exclusively by the contractually agreed terms. The levels may differ in processing scope and response time.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1quality/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1vision~1part~1quality/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1quality/post/requestBody/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "imageUrls" ], "properties": { "imageUrls": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "string", "format": "uri" }, "description": "One to three publicly accessible image URLs of the same part that the user is authorised to transmit and process.", "example": [ "https://example.com/tuer-aussen.jpg", "https://example.com/tuer-innen.jpg" ] }, "quality": { "$ref": "#/components/schemas/ScannerQuality" }, "partType": { "type": "string", "maxLength": 120, "description": "Optional part designation supplied as context.", "example": "Fahrertür" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "imageUrls": [ "https://example.com/tuer-aussen.jpg", "https://example.com/tuer-innen.jpg" ], "quality": "standard", "partType": "Fahrertür" } } ] } ] }, "responses": [ { "status": "200", "description": "Quality grade determined", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1quality/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VisionPartQualityResponse", "schemaPointer": "#/components/schemas/VisionPartQualityResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "format": "tapinoma.part-quality.v1", "gradable": true, "grade": "B", "reason": null, "partCategory": "karosserie", "partName": "Sandbox-Bauteil", "criteria": [ { "key": "gebrauchsspuren", "rating": "leicht", "observation": "aus der Nähe erkennbare Spuren im unteren Drittel" }, { "key": "korrosion", "rating": "keine", "observation": "kein Rostansatz erkennbar" }, { "key": "verformung", "rating": "keine", "observation": "Kanten und Flächen ohne Verzug" }, { "key": "kratzer", "rating": "leicht", "observation": "einzelne flache Kratzer an der Unterkante" }, { "key": "lackzustand", "rating": "leicht", "observation": "kleiner Lackdurchschliff an der Unterkante" }, { "key": "vollstaendigkeit", "rating": "keine", "observation": "Anbauteile vollständig" }, { "key": "verschmutzung", "rating": "leicht", "observation": "abwaschbarer Staub" } ], "reworkEffort": "bis_30_min", "refinishEffort": "anschleifen_lackieren", "limitations": [ "Fixture-Antwort der Sandbox, kein Ergebnis einer Bildanalyse" ], "summary": "Light wear and a small paint abrasion, with no corrosion or deformation. This results in grade B.", "visualOnly": true } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1quality/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1quality/post/responses/400/content/application~1json/schema", "schema": { "title": "GradePartQualityFromImages400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vision~1part~1quality/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1quality/post/responses/401/content/application~1json/schema", "schema": { "title": "GradePartQualityFromImages401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1quality/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1quality/post/responses/402/content/application~1json/schema", "schema": { "title": "GradePartQualityFromImages402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1vision~1part~1quality/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1quality/post/responses/403/content/application~1json/schema", "schema": { "title": "GradePartQualityFromImages403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1part~1quality/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1quality/post/responses/409/content/application~1json/schema", "schema": { "title": "GradePartQualityFromImages409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1part~1quality/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1quality/post/responses/429/content/application~1json/schema", "schema": { "title": "GradePartQualityFromImages429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Quality assessment failed", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1quality/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1quality/post/responses/500/content/application~1json/schema", "schema": { "title": "GradePartQualityFromImages500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1quality/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1quality/post/responses/503/content/application~1json/schema", "schema": { "title": "GradePartQualityFromImages503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vision~1part~1quality/post" }, { "operationId": "removePartBackground", "method": "POST", "path": "/vision/part/remove/bg", "tags": [ "Vision" ], "summary": "Remove the background from a part photo", "description": "**Service description**\n\nRemove the background from a part photo. The request and response follow the schemas documented below.\n\n**Usage and legal notice**\n\nFor endpoints with quality levels, `standard` is the default. Billing for `standard`, `enhanced` and `maximum` is governed exclusively by the contractually agreed terms. The levels may differ in processing scope and response time.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1remove~1bg/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1vision~1part~1remove~1bg/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1remove~1bg/post/requestBody/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "imageUrl" ], "properties": { "imageUrl": { "type": "string", "format": "uri", "description": "Publicly accessible URL of an image that the user is authorised to transmit and process.", "example": "https://example.com/stossfaenger.jpg" }, "quality": { "$ref": "#/components/schemas/ScannerQuality" }, "background": { "type": "string", "enum": [ "transparent", "white" ], "default": "transparent", "description": "Desired background. `transparent` returns a PNG with an alpha channel; `white` returns a PNG on pure white. The default is `transparent`: white can be added later, but cannot be removed from an opaque image." }, "partType": { "type": "string", "maxLength": 120, "description": "Optional part designation supplied as context.", "example": "Stoßfänger vorn" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "imageUrl": "https://example.com/stossfaenger.jpg", "quality": "standard", "background": "transparent", "partType": "Stoßfänger vorn" } } ] } ] }, "responses": [ { "status": "200", "description": "Cutout created", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1remove~1bg/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VisionCutoutResponse", "schemaPointer": "#/components/schemas/VisionCutoutResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "format": "tapinoma.cutout.v1", "subject": "part", "quality": "standard", "background": "transparent", "found": true, "label": "Sandbox-Bauteil", "imageUrl": "https://sandbox.invalid/vision/background-removal/sandbox-part/cutout.png", "mediaType": "image/png", "width": 1600, "height": 1200, "coverage": { "areaShare": 0.42, "touchesImageEdge": false, "cropped": false }, "sourcePixelsPreserved": true, "limitations": [ "Fixture-Antwort der Sandbox, kein Ergebnis einer Bildanalyse" ] } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1remove~1bg/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1remove~1bg/post/responses/400/content/application~1json/schema", "schema": { "title": "RemovePartBackground400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vision~1part~1remove~1bg/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1remove~1bg/post/responses/401/content/application~1json/schema", "schema": { "title": "RemovePartBackground401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1remove~1bg/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1remove~1bg/post/responses/402/content/application~1json/schema", "schema": { "title": "RemovePartBackground402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1vision~1part~1remove~1bg/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1remove~1bg/post/responses/403/content/application~1json/schema", "schema": { "title": "RemovePartBackground403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1part~1remove~1bg/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1remove~1bg/post/responses/409/content/application~1json/schema", "schema": { "title": "RemovePartBackground409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1part~1remove~1bg/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1remove~1bg/post/responses/429/content/application~1json/schema", "schema": { "title": "RemovePartBackground429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Background removal failed", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1remove~1bg/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1remove~1bg/post/responses/500/content/application~1json/schema", "schema": { "title": "RemovePartBackground500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1remove~1bg/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1remove~1bg/post/responses/503/content/application~1json/schema", "schema": { "title": "RemovePartBackground503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vision~1part~1remove~1bg/post" }, { "operationId": "removeVehicleBackground", "method": "POST", "path": "/vision/vehicle/remove/bg", "tags": [ "Vision" ], "summary": "Remove the background from a vehicle photo", "description": "**Service description**\n\nRemove the background from a vehicle photo. The request and response follow the schemas documented below.\n\n**Usage and legal notice**\n\nFor endpoints with quality levels, `standard` is the default. Billing for `standard`, `enhanced` and `maximum` is governed exclusively by the contractually agreed terms. The levels may differ in processing scope and response time.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1vehicle~1remove~1bg/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1vision~1vehicle~1remove~1bg/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1vehicle~1remove~1bg/post/requestBody/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "imageUrl" ], "properties": { "imageUrl": { "type": "string", "format": "uri", "description": "Publicly accessible URL of an image that the user is authorised to transmit and process.", "example": "https://example.com/fahrzeug-hof.jpg" }, "quality": { "$ref": "#/components/schemas/ScannerQuality" }, "background": { "type": "string", "enum": [ "transparent", "white" ], "default": "transparent", "description": "Desired background. `transparent` returns a PNG with an alpha channel; `white` returns a PNG on pure white. The default is `transparent`: white can be added later, but cannot be removed from an opaque image." } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "imageUrl": "https://example.com/fahrzeug-hof.jpg", "quality": "standard", "background": "white" } } ] } ] }, "responses": [ { "status": "200", "description": "Cutout created", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1vehicle~1remove~1bg/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VisionCutoutResponse", "schemaPointer": "#/components/schemas/VisionCutoutResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "format": "tapinoma.cutout.v1", "subject": "vehicle", "quality": "standard", "background": "transparent", "found": true, "label": "Sandbox-Fahrzeug", "imageUrl": "https://sandbox.invalid/vision/background-removal/sandbox-vehicle/cutout.png", "mediaType": "image/png", "width": 1600, "height": 1067, "coverage": { "areaShare": 0.61, "touchesImageEdge": true, "cropped": false }, "sourcePixelsPreserved": true, "limitations": [ "Fixture-Antwort der Sandbox, kein Ergebnis einer Bildanalyse" ] } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1vehicle~1remove~1bg/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1vehicle~1remove~1bg/post/responses/400/content/application~1json/schema", "schema": { "title": "RemoveVehicleBackground400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vision~1vehicle~1remove~1bg/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1vehicle~1remove~1bg/post/responses/401/content/application~1json/schema", "schema": { "title": "RemoveVehicleBackground401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1vehicle~1remove~1bg/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1vehicle~1remove~1bg/post/responses/402/content/application~1json/schema", "schema": { "title": "RemoveVehicleBackground402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1vision~1vehicle~1remove~1bg/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1vehicle~1remove~1bg/post/responses/403/content/application~1json/schema", "schema": { "title": "RemoveVehicleBackground403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1vehicle~1remove~1bg/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1vehicle~1remove~1bg/post/responses/409/content/application~1json/schema", "schema": { "title": "RemoveVehicleBackground409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1vehicle~1remove~1bg/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1vehicle~1remove~1bg/post/responses/429/content/application~1json/schema", "schema": { "title": "RemoveVehicleBackground429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Background removal failed", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1vehicle~1remove~1bg/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1vehicle~1remove~1bg/post/responses/500/content/application~1json/schema", "schema": { "title": "RemoveVehicleBackground500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1vehicle~1remove~1bg/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1vehicle~1remove~1bg/post/responses/503/content/application~1json/schema", "schema": { "title": "RemoveVehicleBackground503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vision~1vehicle~1remove~1bg/post" }, { "operationId": "chooseSponsorshipBillingMode", "method": "PUT", "path": "/client/sponsorship-grants/received/{grantReference}/billing-mode", "tags": [ "Client Admin" ], "summary": "Choose the terms of a received sponsorship", "description": "**Service description**\n\nThe beneficiary chooses whether to bill on its own terms or on the sponsor terms. `partner` requires the sponsor to have released the choice with `partnerTermsAllowed`; without that release the endpoint answers 403. Under `partner` the own balance stays untouched and is no longer reported, and an endpoint outside the grant is refused with 402 `partner_terms_not_covered` instead of being silently self-paid. Contract-included control calls and the beneficiary own administration under `/client/` are exempt, so the choice stays reversible at any time. Withdrawing the release drops the choice with it.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "grantReference", "in": "path", "required": true, "description": "Stable sponsor-selected reference for idempotent changes.", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put/parameters/0/schema", "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put/parameters/0" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put/parameters/1/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put/parameters/1" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/SponsorshipBillingModeRequest", "schemaPointer": "#/components/schemas/SponsorshipBillingModeRequest", "exampleNames": [], "examples": [] } ] }, "responses": [ { "status": "200", "description": "Sponsorship grant", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/SponsorshipGrantResponse", "schemaPointer": "#/components/schemas/SponsorshipGrantResponse", "exampleNames": [ "documented" ], "examples": [ { "name": "documented", "value": { "sponsorshipGrant": { "id": 15, "reference": "erp-customer-4711", "sponsor": { "clientId": 1001, "name": "ERP Integrator AG" }, "beneficiary": { "clientId": 4711, "name": "Werkstatt Nord GmbH" }, "endpointKeys": [ "vin.cart_check", "vin.parts", "vin.vehicle" ], "channels": [ "hub" ], "startsAt": "2026-01-01T00:00:00+00:00", "endsAt": null, "revokedAt": null, "active": true, "partnerTermsAllowed": true, "partnerTermsChosen": true, "partnerTermsActive": true, "beneficiaryMonthlyCapCents": 50000, "createdAt": "2026-01-01T00:00:00+00:00", "updatedAt": "2026-01-05T09:12:00+00:00" } } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid or non-executable sponsorship grant", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put/responses/400/content/application~1json/schema", "schema": { "title": "ChooseSponsorshipBillingMode400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put/responses/401/content/application~1json/schema", "schema": { "title": "ChooseSponsorshipBillingMode401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "Invalid or non-executable sponsorship grant", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put/responses/403/content/application~1json/schema", "schema": { "title": "ChooseSponsorshipBillingMode403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "forbidden", "invalid_api_key", "sandbox_endpoint_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "forbidden", "invalid_api_key", "sandbox_endpoint_unavailable" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } }, { "name": "sandbox_endpoint_unavailable", "value": { "error": "sandbox_endpoint_unavailable", "message": "This endpoint has no sandbox fixture; use a production key" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "forbidden", "invalid_api_key", "sandbox_endpoint_unavailable" ] }, { "status": "404", "description": "Invalid or non-executable sponsorship grant", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put/responses/404/content/application~1json/schema", "schema": { "title": "ChooseSponsorshipBillingMode404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "not_found", "message": "No record matches the given identifier" } } ] } ], "errorCodes": [ "not_found" ] }, { "status": "409", "description": "Invalid or non-executable sponsorship grant", "headers": [ "Retry-After", "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put/responses/409/content/application~1json/schema", "schema": { "title": "ChooseSponsorshipBillingMode409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "ambiguous_grant_reference", "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "ambiguous_grant_reference", "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "ambiguous_grant_reference", "value": { "error": "ambiguous_grant_reference", "message": "Several sponsors use this reference for you; name sponsorClientId" } }, { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "ambiguous_grant_reference", "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put/responses/429/content/application~1json/schema", "schema": { "title": "ChooseSponsorshipBillingMode429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put/responses/500/content/application~1json/schema", "schema": { "title": "ChooseSponsorshipBillingMode500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put/responses/503/content/application~1json/schema", "schema": { "title": "ChooseSponsorshipBillingMode503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1client~1sponsorship-grants~1received~1{grantReference}~1billing-mode/put" }, { "operationId": "generatePartImagesFromOeNumber", "method": "POST", "path": "/vision/part/generate", "tags": [ "Vision" ], "summary": "Generate product images from an OE number", "description": "**Service description**\n\nGenerate product images from an OE number. The request and response follow the schemas documented below.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Caller-selected key for a successful response retained for 24 hours. Reusing it returns the documented replay without another charge.", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1generate/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1vision~1part~1generate/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VisionPartGenerationRequest", "schemaPointer": "#/components/schemas/VisionPartGenerationRequest", "exampleNames": [], "examples": [] } ] }, "responses": [ { "status": "202", "description": "Generation job accepted", "headers": [ "Location", "Retry-After", "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1generate/post/responses/202", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VisionPartGenerationAccepted", "schemaPointer": "#/components/schemas/VisionPartGenerationAccepted", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "jobId": "123e4567-e89b-42d3-a456-426614174000", "status": "queued", "statusUrl": "https://api.tapinomahub.com/vision/part/generation-jobs/123e4567-e89b-42d3-a456-426614174000", "oeNumber": "5G0807221S", "createdAt": "2026-01-01T00:00:00+00:00", "retryAfterSeconds": 5 } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [], "openApiPointer": "#/paths/~1vision~1part~1generate/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1generate/post/responses/400/content/application~1json/schema", "schema": { "title": "generatePartImagesFromOeNumber400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key missing", "headers": [], "openApiPointer": "#/paths/~1vision~1part~1generate/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1generate/post/responses/401/content/application~1json/schema", "schema": { "title": "generatePartImagesFromOeNumber401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "missing_api_key" ], "examples": [ { "name": "missing_api_key", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient credit", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1generate/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1generate/post/responses/402/content/application~1json/schema", "schema": { "title": "generatePartImagesFromOeNumber402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "API key invalid or endpoint not enabled", "headers": [], "openApiPointer": "#/paths/~1vision~1part~1generate/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1generate/post/responses/403/content/application~1json/schema", "schema": { "title": "generatePartImagesFromOeNumber403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier idempotent request", "headers": [ "Retry-After", "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1generate/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1generate/post/responses/409/content/application~1json/schema", "schema": { "title": "generatePartImagesFromOeNumber409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or another request is active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1part~1generate/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1generate/post/responses/429/content/application~1json/schema", "schema": { "title": "generatePartImagesFromOeNumber429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Processing failed", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1generate/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1generate/post/responses/500/content/application~1json/schema", "schema": { "title": "generatePartImagesFromOeNumber500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "internal_error" ], "examples": [ { "name": "internal_error", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1generate/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1generate/post/responses/503/content/application~1json/schema", "schema": { "title": "generatePartImagesFromOeNumber503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": true, "asynchronous": true, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vision~1part~1generate/post" }, { "operationId": "getPartImageGenerationJob", "method": "GET", "path": "/vision/part/generation-jobs/{jobId}", "tags": [ "Vision" ], "summary": "Read product-image job status", "description": "**Service description**\n\nRead product-image job status. The request and response follow the schemas documented below.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": null, "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1generation-jobs~1{jobId}/get/parameters/0/schema", "schema": { "type": "string", "format": "uuid" }, "exampleNames": [], "examples": [], "openApiPointer": "#/paths/~1vision~1part~1generation-jobs~1{jobId}/get/parameters/0" } ], "requestBody": null, "responses": [ { "status": "200", "description": "Job status read", "headers": [ "Retry-After", "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1generation-jobs~1{jobId}/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VisionPartGenerationJobStatus", "schemaPointer": "#/components/schemas/VisionPartGenerationJobStatus", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "jobId": "123e4567-e89b-42d3-a456-426614174000", "status": "queued", "statusUrl": "https://api.tapinomahub.com/vision/part/generation-jobs/123e4567-e89b-42d3-a456-426614174000", "oeNumber": "5G0807221S", "createdAt": "2026-01-01T00:00:00+00:00", "retryAfterSeconds": 5 } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [], "openApiPointer": "#/paths/~1vision~1part~1generation-jobs~1{jobId}/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1generation-jobs~1{jobId}/get/responses/400/content/application~1json/schema", "schema": { "title": "GetPartImageGenerationJob400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } ] } ], "errorCodes": [ "idempotency_key_not_supported" ] }, { "status": "401", "description": "API key missing", "headers": [], "openApiPointer": "#/paths/~1vision~1part~1generation-jobs~1{jobId}/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1generation-jobs~1{jobId}/get/responses/401/content/application~1json/schema", "schema": { "title": "getPartImageGenerationJob401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "missing_api_key" ], "examples": [ { "name": "missing_api_key", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "API key invalid or endpoint not enabled", "headers": [], "openApiPointer": "#/paths/~1vision~1part~1generation-jobs~1{jobId}/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1generation-jobs~1{jobId}/get/responses/403/content/application~1json/schema", "schema": { "title": "getPartImageGenerationJob403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "404", "description": "Job not found", "headers": [], "openApiPointer": "#/paths/~1vision~1part~1generation-jobs~1{jobId}/get/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1generation-jobs~1{jobId}/get/responses/404/content/application~1json/schema", "schema": { "title": "getPartImageGenerationJob404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "vision_generation_job_not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "vision_generation_job_not_found" ], "examples": [ { "name": "vision_generation_job_not_found", "value": { "error": "vision_generation_job_not_found", "message": "Vision generation job not found" } } ] } ], "errorCodes": [ "vision_generation_job_not_found" ] }, { "status": "429", "description": "Rate limit exceeded or another request is active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1part~1generation-jobs~1{jobId}/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1generation-jobs~1{jobId}/get/responses/429/content/application~1json/schema", "schema": { "title": "getPartImageGenerationJob429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Processing failed", "headers": [], "openApiPointer": "#/paths/~1vision~1part~1generation-jobs~1{jobId}/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1generation-jobs~1{jobId}/get/responses/500/content/application~1json/schema", "schema": { "title": "getPartImageGenerationJob500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "internal_error" ], "examples": [ { "name": "internal_error", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1vision~1part~1generation-jobs~1{jobId}/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1generation-jobs~1{jobId}/get/responses/503/content/application~1json/schema", "schema": { "title": "GetPartImageGenerationJob503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vision~1part~1generation-jobs~1{jobId}/get" }, { "operationId": "classifyEndOfLifeVehicle", "method": "POST", "path": "/vision/vehicle/elv-classification", "tags": [ "Vision" ], "summary": "Classify a vehicle as an end-of-life vehicle from images", "description": "**Service description**\n\nClassify a vehicle as an end-of-life vehicle from images. The request and response follow the schemas documented below.\n\n**Usage and legal notice**\n\nFor endpoints with quality levels, `standard` is the default. Billing for `standard`, `enhanced` and `maximum` is governed exclusively by the contractually agreed terms. The levels may differ in processing scope and response time.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1vehicle~1elv-classification/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1vision~1vehicle~1elv-classification/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1vehicle~1elv-classification/post/requestBody/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "imageUrls" ], "properties": { "imageUrls": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "format": "uri" }, "description": "One to ten publicly accessible image URLs of the same vehicle that the user is authorised to transmit and process.", "example": [ "https://example.com/front.jpg", "https://example.com/seite-links.jpg", "https://example.com/innenraum.jpg" ] }, "quality": { "$ref": "#/components/schemas/ScannerQuality" }, "vehicle": { "type": "object", "additionalProperties": false, "description": "Optional vehicle details supplied as context.", "properties": { "vin": { "type": "string", "minLength": 3, "maxLength": 17, "pattern": "^[A-HJ-NPR-Za-hj-npr-z0-9]{3,17}$", "description": "The public schema defines the meaning and format of `vin`.", "example": "W0L00000000000001" }, "firstRegistration": { "type": "string", "description": "First registration as `YYYY-MM` or `YYYY-MM-DD`.", "example": "2011-04" }, "mileageKm": { "type": "integer", "minimum": 0, "maximum": 2000000, "description": "Mileage in kilometres.", "example": 236000 }, "inspectionValidUntil": { "type": "string", "description": "Periodic-inspection validity as `YYYY-MM` or `YYYY-MM-DD`.", "example": "2025-06" }, "marketValueEur": { "type": "number", "exclusiveMinimum": 0, "description": "Market or replacement value in euros. Without it, the economic axis remains `nicht_beurteilbar`.", "example": 1500 }, "repairEstimateEur": { "type": "number", "exclusiveMinimum": 0, "description": "Existing repair estimate in euros, for example from an appraisal or quotation.", "example": 4200 }, "damageDescription": { "type": "string", "maxLength": 500, "description": "Caller-supplied free-text description of the damage.", "example": "Frontschaden nach Wildunfall, Airbags ausgelöst" } } } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "imageUrls": [ "https://example.com/front.jpg", "https://example.com/seite-links.jpg", "https://example.com/innenraum.jpg" ], "quality": "standard", "vehicle": { "firstRegistration": "2011-04", "mileageKm": 236000, "marketValueEur": 1500, "repairEstimateEur": 4200, "damageDescription": "Frontschaden nach Wildunfall, Airbags ausgelöst" } } } ] } ] }, "responses": [ { "status": "200", "description": "End-of-life vehicle classification created", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1vehicle~1elv-classification/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VisionElvClassificationResponse", "schemaPointer": "#/components/schemas/VisionElvClassificationResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "format": "tapinoma.elv-classification.v1", "classification": "altfahrzeug", "technicallyIrreparable": true, "economicallyIrreparable": true, "criteria": [ { "key": "zerlegt_oder_ausgeschlachtet", "finding": "nicht_erfuellt", "confidence": "mittel", "observation": "Karosserie vollständig, keine entnommenen Baugruppen erkennbar", "imageIndexes": [] }, { "key": "zugeschweisst_oder_ausgeschaeumt", "finding": "nicht_erfuellt", "confidence": "mittel", "observation": "Türen und Klappen regulär verschlossen", "imageIndexes": [] }, { "key": "ausgebrannt", "finding": "erfuellt", "confidence": "hoch", "observation": "Motorraum vollständig ausgebrannt, Kunststoffteile geschmolzen, Brandspuren bis in den Fahrgastraum", "imageIndexes": [ 1, 3 ] }, { "key": "wasserstand_ueber_armaturenbrett", "finding": "nicht_erfuellt", "confidence": "niedrig", "observation": "keine Wasserlinien oder Schlammränder erkennbar", "imageIndexes": [] }, { "key": "strukturschaden_irreversibel", "finding": "nicht_beurteilbar", "confidence": "niedrig", "observation": "tragende Struktur durch Brandfolgen nicht sicher beurteilbar", "imageIndexes": [] }, { "key": "hauptaggregat_ersatz_erforderlich", "finding": "erfuellt", "confidence": "hoch", "observation": "Motor durch Brand zerstört, Ersatz erkennbar erforderlich", "imageIndexes": [ 1 ] }, { "key": "fahrwerk_lenkung_bremsen_nicht_instandsetzbar", "finding": "nicht_beurteilbar", "confidence": "niedrig", "observation": "Unterboden und Bremsanlage nicht abgebildet", "imageIndexes": [] } ], "economicAssessment": { "basis": "einsenderangaben", "repairCostRelation": "ueber_marktwert", "marketValueEur": 1500, "repairEstimateEur": 4200 }, "coverage": { "viewsCovered": [ "front", "left", "interior", "engine_bay" ], "viewsMissing": [ "rear", "right", "underbody" ] }, "vehicleObserved": "Kompakt-Pkw mit ausgebranntem Motorraum", "limitations": [ "Fixture-Antwort der Sandbox, kein Ergebnis einer Bildanalyse" ], "summary": "The engine compartment is completely burned out and the engine destroyed; fire damage extends into the passenger compartment. The rear, right side and underbody are not shown.", "visualOnly": true } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1vehicle~1elv-classification/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1vehicle~1elv-classification/post/responses/400/content/application~1json/schema", "schema": { "title": "ClassifyEndOfLifeVehicle400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vision~1vehicle~1elv-classification/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1vehicle~1elv-classification/post/responses/401/content/application~1json/schema", "schema": { "title": "ClassifyEndOfLifeVehicle401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1vehicle~1elv-classification/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1vehicle~1elv-classification/post/responses/402/content/application~1json/schema", "schema": { "title": "ClassifyEndOfLifeVehicle402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1vision~1vehicle~1elv-classification/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1vehicle~1elv-classification/post/responses/403/content/application~1json/schema", "schema": { "title": "ClassifyEndOfLifeVehicle403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1vehicle~1elv-classification/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1vehicle~1elv-classification/post/responses/409/content/application~1json/schema", "schema": { "title": "ClassifyEndOfLifeVehicle409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1vehicle~1elv-classification/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1vehicle~1elv-classification/post/responses/429/content/application~1json/schema", "schema": { "title": "ClassifyEndOfLifeVehicle429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "End-of-life vehicle classification failed", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1vehicle~1elv-classification/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1vehicle~1elv-classification/post/responses/500/content/application~1json/schema", "schema": { "title": "ClassifyEndOfLifeVehicle500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1vehicle~1elv-classification/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1vehicle~1elv-classification/post/responses/503/content/application~1json/schema", "schema": { "title": "ClassifyEndOfLifeVehicle503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vision~1vehicle~1elv-classification/post" }, { "operationId": "intakeVehicle", "method": "POST", "path": "/vehicles/intake", "tags": [ "Vehicles" ], "summary": "Create a vehicle file from a registration-document photo", "description": "**Service description**\n\nCreate a vehicle file from a registration-document photo. The request and response follow the schemas documented below.\n\n**Usage and legal notice**\n\nFor endpoints with quality levels, `standard` is the default. Billing for `standard`, `enhanced` and `maximum` is governed exclusively by the contractually agreed terms. The levels may differ in processing scope and response time.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1intake/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1vehicles~1intake/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1intake/post/requestBody/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "fileUrl" ], "properties": { "fileUrl": { "type": "string", "format": "uri", "description": "Publicly accessible URL of a document that the user is authorised to transmit and process.", "example": "https://example.com/fahrzeugschein.jpg" }, "photoUrls": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "string", "format": "uri" }, "description": "Optional one to five walk-around photos of the same vehicle. When photos are supplied, the response includes a condition report and that component is billed.", "example": [ "https://example.com/front.jpg", "https://example.com/heck.jpg" ] }, "country": { "type": "string", "description": "Two-letter country code used for the vehicle match.", "default": "de" }, "includeOwner": { "type": "boolean", "default": false, "description": "Only when `true` does the response include keeper data from the registration document. Otherwise the block remains `null`, preventing integrations from receiving or storing keeper data unintentionally." } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "fileUrl": "https://example.com/fahrzeugschein.jpg", "photoUrls": [ "https://example.com/front.jpg", "https://example.com/heck.jpg" ], "includeOwner": false } } ] } ] }, "responses": [ { "status": "200", "description": "Vehicle file from document scan and vehicle data", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vehicles~1intake/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VehicleIntakeResponse", "schemaPointer": "#/components/schemas/VehicleIntakeResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "format": "tapinoma.vehicle-intake.v1", "registrationDocument": { "registration": { "registrationNumber": "SBX-TE 999", "documentNumber": "SBX0000000001", "issuingAuthority": "Sandbox", "issuedDate": "2021-06-01" }, "owner": null, "inspection": null, "vehicle": { "vin": "TAPSANDBX00000001", "hsn": "9999", "tsn": "SBX1", "brand": "Sandbox Motors", "commercialName": "Modell A" } }, "vin": "TAPSANDBX00000001", "provider": 2, "tapiId": "5b1a1000-0000-4000-8000-000000000001", "vehicle": { "vin": "TAPSANDBX00000001", "tapiId": "5b1a1000-0000-4000-8000-000000000001", "provider": 2, "displayName": "Sandbox Kompaktwagen 1.5 TSI", "kTypes": [ 900001, 900002 ], "natCodes": [ "SBX0000001" ] }, "conditionReport": { "format": "tapinoma.condition-report.v1", "gradable": true, "grade": "B", "reason": null, "summary": "Light wear, with no corrosion or deformation. This results in grade B.", "zones": [ { "zone": "front", "findings": [] }, { "zone": "flanke_links", "findings": [] }, { "zone": "flanke_rechts", "findings": [] }, { "zone": "heck", "findings": [] }, { "zone": "dach", "findings": [] }, { "zone": "innenraum", "findings": [] }, { "zone": "motorraum", "findings": [] }, { "zone": "sonstiges", "findings": [] } ], "limitations": [ "Fixture-Antwort der Sandbox, kein Ergebnis einer Bildanalyse" ], "imageCount": 2, "visualOnly": true }, "components": { "registrationDocument": "delivered", "vehicle": "delivered", "conditionReport": "delivered" }, "complete": true } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vehicles~1intake/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1intake/post/responses/400/content/application~1json/schema", "schema": { "title": "IntakeVehicle400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_country", "invalid_idempotency_key", "invalid_provider" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_country", "invalid_idempotency_key", "invalid_provider" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_country", "value": { "error": "invalid_country", "message": "country must be a two-letter ISO 3166-1 code" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } }, { "name": "invalid_provider", "value": { "error": "invalid_provider", "message": "provider is not a supported selection value" } } ] } ], "errorCodes": [ "bad_request", "invalid_country", "invalid_idempotency_key", "invalid_provider" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vehicles~1intake/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1intake/post/responses/401/content/application~1json/schema", "schema": { "title": "IntakeVehicle401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vehicles~1intake/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1intake/post/responses/402/content/application~1json/schema", "schema": { "title": "IntakeVehicle402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1vehicles~1intake/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1intake/post/responses/403/content/application~1json/schema", "schema": { "title": "IntakeVehicle403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vehicles~1intake/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1intake/post/responses/409/content/application~1json/schema", "schema": { "title": "IntakeVehicle409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vehicles~1intake/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1intake/post/responses/429/content/application~1json/schema", "schema": { "title": "IntakeVehicle429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vehicles~1intake/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1intake/post/responses/500/content/application~1json/schema", "schema": { "title": "IntakeVehicle500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vehicles~1intake/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1intake/post/responses/503/content/application~1json/schema", "schema": { "title": "IntakeVehicle503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "service_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "service_unavailable" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vehicles~1intake/post" }, { "operationId": "composeVehicleListing", "method": "POST", "path": "/vehicles/{tapiId}/listing", "tags": [ "Vehicles" ], "summary": "Compose a marketplace-ready listing text", "description": "**Service description**\n\nComposes a marketplace-ready listing text — title, description and equipment highlights — from the vehicle data documented for the `tapiId`. Only the facts documented for the vehicle are used; the text never invents properties that are not on record, and prices, condition claims or value statements are never part of the output. Optional dealer notes via `notes` are taken in as factual details. `language` selects German, English or French. The reference must previously have arisen from a successful VIN flow of the client; foreign and unknown references consistently return `404`.\n\n**Usage and legal notice**\n\nFor endpoints with quality levels, `standard` is the default. Billing for `standard`, `enhanced` and `maximum` is governed exclusively by the contractually agreed terms. The levels may differ in processing scope and response time.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "tapiId", "in": "path", "required": true, "description": "Stable vehicle reference from a VIN flow previously completed successfully for this client.", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/parameters/0/schema", "schema": { "type": "string", "format": "uuid" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "5b1a1000-0000-4000-8000-000000000001" } ], "openApiPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/parameters/0" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/parameters/1/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/parameters/1" } ], "requestBody": { "required": false, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/requestBody/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "properties": { "quality": { "$ref": "#/components/schemas/ScannerQuality" }, "language": { "type": "string", "enum": [ "de", "en", "fr" ], "default": "de", "description": "Language of the generated listing text." }, "notes": { "type": "string", "maxLength": 500, "description": "Optional dealer notes. Only factual statements are used; the generated text does not invent attributes from them.", "example": "Nichtraucherfahrzeug, zwei Vorbesitzer" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "quality": "standard", "language": "de", "notes": "Nichtraucherfahrzeug, zwei Vorbesitzer" } } ] } ] }, "responses": [ { "status": "200", "description": "Marketplace-ready listing text", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VehicleListingResponse", "schemaPointer": "#/components/schemas/VehicleListingResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "format": "tapinoma.vehicle-listing.v1", "tapiId": "5b1a1000-0000-4000-8000-000000000001", "language": "de", "title": "Sandbox Motors Modell A 1.5 TSI mit Klimaautomatik", "description": "The Sandbox Motors Model A is a compact car with a 1.5 TSI petrol engine rated at 110 kW and a manual transmission. Its documented equipment includes automatic climate control. This is a fixed sandbox response, not generated text.", "highlights": [ "Sandbox Klimaautomatik", "1.5 TSI 110 kW" ], "documentedEquipmentCount": 1, "truncated": false } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/responses/400/content/application~1json/schema", "schema": { "title": "ComposeVehicleListing400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/responses/401/content/application~1json/schema", "schema": { "title": "ComposeVehicleListing401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/responses/402/content/application~1json/schema", "schema": { "title": "ComposeVehicleListing402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/responses/403/content/application~1json/schema", "schema": { "title": "ComposeVehicleListing403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "404", "description": "Vehicle not found", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/responses/404/content/application~1json/schema", "schema": { "title": "ComposeVehicleListing404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "vehicle_not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "vehicle_not_found", "message": "No vehicle is known for this identifier" } } ] } ], "errorCodes": [ "vehicle_not_found" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/responses/409/content/application~1json/schema", "schema": { "title": "ComposeVehicleListing409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/responses/429/content/application~1json/schema", "schema": { "title": "ComposeVehicleListing429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/responses/500/content/application~1json/schema", "schema": { "title": "ComposeVehicleListing500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post/responses/503/content/application~1json/schema", "schema": { "title": "ComposeVehicleListing503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vehicles~1{tapiId}~1listing/post" }, { "operationId": "reportVehicleCondition", "method": "POST", "path": "/vision/condition-report", "tags": [ "Vision" ], "summary": "Create a vehicle condition report from images", "description": "**Service description**\n\nAnalyses a walk-around of up to eight photos of the same vehicle and returns a structured condition report: findings per zone in a fixed order — front, left side, right side, rear, roof, interior, engine bay, other — with component, damage type, severity and observation, plus an overall grade of `A`, `B` or `C`. Every zone appears exactly once, even without findings, so the answer can be indexed by position. It rests on visual inspection alone; `visualOnly` permanently indicates that the report remains a description — no expert appraisal, no repair or residual-value calculation. Where no reliable grade is possible, `gradable` is `false` and `reason` states why; zones not pictured and other constraints appear in `limitations`.\n\n**Usage and legal notice**\n\nFor endpoints with quality levels, `standard` is the default. Billing for `standard`, `enhanced` and `maximum` is governed exclusively by the contractually agreed terms. The levels may differ in processing scope and response time.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1condition-report/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1vision~1condition-report/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1condition-report/post/requestBody/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "imageUrls" ], "properties": { "imageUrls": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "string", "format": "uri" }, "description": "One to eight publicly accessible image URLs of the same vehicle, ideally a walk-around with one image per zone. The caller must be authorized to transmit and process them.", "example": [ "https://example.com/front.jpg", "https://example.com/flanke-links.jpg", "https://example.com/heck.jpg" ] }, "quality": { "$ref": "#/components/schemas/ScannerQuality" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "imageUrls": [ "https://example.com/front.jpg", "https://example.com/flanke-links.jpg", "https://example.com/flanke-rechts.jpg", "https://example.com/heck.jpg" ], "quality": "standard" } } ] } ] }, "responses": [ { "status": "200", "description": "Structured condition report", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1condition-report/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VisionConditionReportResponse", "schemaPointer": "#/components/schemas/VisionConditionReportResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "format": "tapinoma.condition-report.v1", "gradable": true, "grade": "B", "reason": null, "summary": "Light wear and an abrasion on the left side, with no corrosion or deformation. This results in grade B.", "zones": [ { "zone": "front", "findings": [] }, { "zone": "flanke_links", "findings": [ { "component": "vordere linke Tür, unteres Drittel", "damageType": "kratzer", "severity": "leicht", "observation": "horizontale Schleifspur, etwa 20 cm, ohne Lackdurchschliff" } ] }, { "zone": "flanke_rechts", "findings": [] }, { "zone": "heck", "findings": [] }, { "zone": "dach", "findings": [] }, { "zone": "innenraum", "findings": [] }, { "zone": "motorraum", "findings": [] }, { "zone": "sonstiges", "findings": [] } ], "limitations": [ "Fixture-Antwort der Sandbox, kein Ergebnis einer Bildanalyse" ], "imageCount": 4, "visualOnly": true } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1condition-report/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1condition-report/post/responses/400/content/application~1json/schema", "schema": { "title": "ReportVehicleCondition400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vision~1condition-report/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1condition-report/post/responses/401/content/application~1json/schema", "schema": { "title": "ReportVehicleCondition401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1condition-report/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1condition-report/post/responses/402/content/application~1json/schema", "schema": { "title": "ReportVehicleCondition402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1vision~1condition-report/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1condition-report/post/responses/403/content/application~1json/schema", "schema": { "title": "ReportVehicleCondition403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1condition-report/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1condition-report/post/responses/409/content/application~1json/schema", "schema": { "title": "ReportVehicleCondition409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1condition-report/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1condition-report/post/responses/429/content/application~1json/schema", "schema": { "title": "ReportVehicleCondition429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1condition-report/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1condition-report/post/responses/500/content/application~1json/schema", "schema": { "title": "ReportVehicleCondition500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1condition-report/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1condition-report/post/responses/503/content/application~1json/schema", "schema": { "title": "ReportVehicleCondition503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vision~1condition-report/post" }, { "operationId": "createPartnerWorkspace", "method": "POST", "path": "/client/partner-workspaces", "tags": [ "Client Admin" ], "summary": "Create a partner workspace with key and allowlist", "description": "**Service description**\n\nCreate a partner workspace with key and allowlist. The request and response follow the schemas documented below.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1partner-workspaces/post/requestBody/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "externalReference", "endpointKeys" ], "properties": { "name": { "type": "string", "description": "Workspace display name, usually the end customer’s name.", "example": "Autohaus Nord GmbH" }, "externalReference": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,80}$", "description": "Integrator-defined stable reference for each end customer. It must be unique within the master client; submitting it again returns `workspace_reference_exists`.", "example": "dms-kunde-4711" }, "endpointKeys": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string" }, "description": "Endpoints to which the workspace is restricted. Administrative endpoints are not allowed.", "example": [ "vehicles.intake", "vehicles.listing", "vision.condition_report" ] }, "sponsorship": { "type": "boolean", "default": false, "description": "When `true`, the caller grants the workspace sponsorship for exactly the enabled endpoints in the `hub` channel as part of the same request." }, "applicationLabel": { "type": "string", "description": "Optional label for the generated API key." }, "rateLimits": { "type": "array", "items": { "type": "object" }, "description": "Optional workspace rate limits in the same format as for sub-user creation and capped by operator limits." } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "name": "Autohaus Nord GmbH", "externalReference": "dms-kunde-4711", "endpointKeys": [ "vehicles.intake", "vehicles.listing", "vision.condition_report" ], "sponsorship": true } } ] } ] }, "responses": [ { "status": "201", "description": "Partner workspace created; the raw API key is returned once", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1partner-workspaces/post/responses/201", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/PartnerWorkspaceResponse", "schemaPointer": "#/components/schemas/PartnerWorkspaceResponse", "exampleNames": [ "documented" ], "examples": [ { "name": "documented", "value": { "workspace": { "id": 4711, "name": "Autohaus Nord GmbH", "isActive": true, "defaultProviderId": 2, "parentClientId": 4200, "role": "user", "balanceCents": 0, "balance": "0.00", "currency": "EUR", "createdAt": "2026-08-28T09:12:33+00:00", "externalReference": "dms-kunde-4711" }, "apiKey": { "id": 9001, "label": "Autohaus Nord GmbH-key", "key": "tap_00000000000000000000000000000000000000000000000000000000000000", "createdAt": "2026-08-28T09:12:33+00:00" }, "allowlist": [ "vehicles.intake", "vehicles.listing", "vision.condition_report" ], "sponsorshipGrant": { "id": 77, "reference": "partner-workspace:dms-kunde-4711", "beneficiaryClientId": 4711, "endpointKeys": [ "vehicles.intake", "vehicles.listing", "vision.condition_report" ], "channels": [ "hub" ], "startsAt": "2026-08-28T09:12:33+00:00", "createdAt": "2026-08-28T09:12:33+00:00" } } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1partner-workspaces/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1partner-workspaces/post/responses/400/content/application~1json/schema", "schema": { "title": "CreatePartnerWorkspace400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "idempotency_key_not_supported" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } ] } ], "errorCodes": [ "bad_request", "idempotency_key_not_supported" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1client~1partner-workspaces/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1partner-workspaces/post/responses/401/content/application~1json/schema", "schema": { "title": "CreatePartnerWorkspace401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "Only master clients may manage sub-users", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1partner-workspaces/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1partner-workspaces/post/responses/403/content/application~1json/schema", "schema": { "title": "CreatePartnerWorkspace403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "forbidden", "invalid_api_key", "sandbox_endpoint_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "forbidden", "invalid_api_key", "sandbox_endpoint_unavailable" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } }, { "name": "sandbox_endpoint_unavailable", "value": { "error": "sandbox_endpoint_unavailable", "message": "This endpoint has no sandbox fixture; use a production key" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "forbidden", "invalid_api_key", "sandbox_endpoint_unavailable" ] }, { "status": "409", "description": "Workspace reference already taken", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1partner-workspaces/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1partner-workspaces/post/responses/409/content/application~1json/schema", "schema": { "title": "CreatePartnerWorkspace409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "workspace_reference_exists" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "workspace_reference_exists", "message": "A workspace with this externalReference already exists" } } ] } ], "errorCodes": [ "workspace_reference_exists" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1client~1partner-workspaces/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1partner-workspaces/post/responses/429/content/application~1json/schema", "schema": { "title": "CreatePartnerWorkspace429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1client~1partner-workspaces/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1partner-workspaces/post/responses/500/content/application~1json/schema", "schema": { "title": "CreatePartnerWorkspace500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1client~1partner-workspaces/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1client~1partner-workspaces/post/responses/503/content/application~1json/schema", "schema": { "title": "CreatePartnerWorkspace503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1client~1partner-workspaces/post" }, { "operationId": "getVinEconomicEvaluation", "method": "GET", "path": "/vin/{vin}/economic-evaluation", "tags": [ "Intelligence" ], "summary": "Create an economic evaluation by VIN", "description": "**Service description**\n\nCreates an economic analysis for the vehicle with revenue potential, a dismantling ranking and a purchase recommendation. The API returns `200` when the result is immediately available, otherwise `202` with `Location` and `Retry-After`.\n\n**Usage and legal notice**\n\nThe paid service consists solely of the technical comparison or analysis and delivery of the result. Rights in the result are granted only to the extent provided by the agreement. Use of the result is governed by the agreement and applicable law. Results may be incomplete, outdated or incorrect and must be independently verified before technical, commercial or legal use.\n\nBy submitting a request, the user confirms that they are authorised to transmit and process the VIN and associated data and, where personal data is involved, have a valid legal basis. Only data necessary for the specific purpose may be submitted.\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "Vehicle identification number that the user must be authorised to transmit and process.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/parameters/0/schema", "schema": { "type": "string" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "TAPSANDBX00000001" } ], "openApiPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/parameters/0" }, { "name": "country", "in": "query", "required": false, "description": "Two-letter country code used for market and regional context.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/parameters/1/schema", "schema": { "type": "string", "default": "de" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "de" } ], "openApiPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/parameters/1" }, { "name": "provider", "in": "query", "required": false, "description": "Optional numeric selection agreed by contract; the default value is `1`.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/parameters/2/schema", "schema": { "type": "integer", "enum": [ 1 ], "default": 1 }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": 1 } ], "openApiPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/parameters/2" }, { "name": "condition", "in": "query", "required": false, "description": "Part condition considered by the indicative price evaluation.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/parameters/3/schema", "schema": { "type": "string", "enum": [ "used", "new" ], "default": "used" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "used" } ], "openApiPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/parameters/3" }, { "name": "vehicleType", "in": "query", "required": false, "description": "Public parameter `vehicleType` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/parameters/4/schema", "schema": { "type": "string", "enum": [ "car", "motorcycle" ], "default": "car" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "car" } ], "openApiPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/parameters/4" }, { "name": "maxPricedParts", "in": "query", "required": false, "description": "Upper limit of parts to include in the evaluation. Default and maximum are 100.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/parameters/5/schema", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": 100 } ], "openApiPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/parameters/5" }, { "name": "recoveryRate", "in": "query", "required": false, "description": "Assumed share of the revenue potential actually realised when selling (0.05 to 1; default 0.5). Feeds the purchase recommendation and is echoed in the response.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/parameters/6/schema", "schema": { "type": "number", "minimum": 0.05, "maximum": 1, "default": 0.5 }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": 0.5 } ], "openApiPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/parameters/6" }, { "name": "costPerPart", "in": "query", "required": false, "description": "Assumed cost per priced part in EUR for removal, storage and shipping (0 to 1000; default 0). Feeds the purchase recommendation.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/parameters/7/schema", "schema": { "type": "number", "minimum": 0, "maximum": 1000, "default": 0 }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": 0 } ], "openApiPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/parameters/7" } ], "requestBody": null, "responses": [ { "status": "200", "description": "Economic evaluation result", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VinEconomicEvaluationResponse", "schemaPointer": "#/components/schemas/VinEconomicEvaluationResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "vin": "TAPSANDBX00000001", "provider": 1, "matchLevel": "vehicle_specific_best_available", "currency": "EUR", "condition": "used", "vehicleType": "car", "assumptions": { "maxPricedParts": 100, "recoveryRate": 0.5, "costPerPartEur": 0, "priceBasis": "min" }, "coverage": { "totalParts": 2, "excludedIrrelevant": 0, "relevantParts": 2, "selectedParts": 2, "pricedParts": 2, "unpricedParts": 0 }, "revenuePotential": { "min": 120, "average": 190.5, "max": 293 }, "purchaseRecommendation": { "goodPurchasePriceEur": 60 }, "parts": [ { "rank": 1, "number": "SBX0001A", "name": "Sandbox Stoßfänger vorn", "category": "ST", "amount": 1, "pricing": { "min": 89, "average": 142.5, "max": 219, "confidence": "MEDIUM", "evaluatedAt": "2026-01-01T00:00:00+00:00" }, "revenuePotential": { "min": 89, "average": 142.5, "max": 219 } }, { "rank": 2, "number": "SBX0002B", "name": "Sandbox Bremsscheibe", "category": "BR", "amount": 1, "pricing": { "min": 31, "average": 48, "max": 74, "confidence": "LOW", "evaluatedAt": "2026-01-01T00:00:00+00:00" }, "revenuePotential": { "min": 31, "average": 48, "max": 74 } } ], "tapiId": "5b1a1000-0000-4000-8000-000000000001" } } ] } ], "errorCodes": [] }, { "status": "202", "description": "Economic evaluation accepted for asynchronous processing", "headers": [ "Location", "Retry-After", "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/responses/202", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VinEconomicEvaluationJobResponse", "schemaPointer": "#/components/schemas/VinEconomicEvaluationJobResponse", "exampleNames": [ "accepted" ], "examples": [ { "name": "accepted", "value": { "jobId": "6955b900-0400-4548-9632-06e2f302e3d7", "status": "queued", "statusUrl": "https://api.tapinomahub.com/vin/economic-evaluation/jobs/6955b900-0400-4548-9632-06e2f302e3d7", "vin": "TAPSANDBX00000001", "provider": 1, "retryAfterSeconds": 3, "createdAt": "2026-01-01T00:00:00+00:00" } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/responses/400/content/application~1json/schema", "schema": { "title": "GetVinEconomicEvaluation400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported", "invalid_country", "invalid_provider", "invalid_query_parameter", "invalid_vehicle_type" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_not_supported", "invalid_country", "invalid_provider", "invalid_query_parameter", "invalid_vehicle_type" ], "examples": [ { "name": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } }, { "name": "invalid_country", "value": { "error": "invalid_country", "message": "country must be a two-letter ISO 3166-1 code" } }, { "name": "invalid_provider", "value": { "error": "invalid_provider", "message": "provider is not a supported selection value" } }, { "name": "invalid_query_parameter", "value": { "error": "invalid_query_parameter", "message": "A query parameter has the wrong type or format" } }, { "name": "invalid_vehicle_type", "value": { "error": "invalid_vehicle_type", "message": "vehicleType must be car or motorcycle" } } ] } ], "errorCodes": [ "idempotency_key_not_supported", "invalid_country", "invalid_provider", "invalid_query_parameter", "invalid_vehicle_type" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/responses/401/content/application~1json/schema", "schema": { "title": "GetVinEconomicEvaluation401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/responses/402/content/application~1json/schema", "schema": { "title": "GetVinEconomicEvaluation402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/responses/403/content/application~1json/schema", "schema": { "title": "GetVinEconomicEvaluation403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "404", "description": "Not found", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/responses/404/content/application~1json/schema", "schema": { "title": "GetVinEconomicEvaluation404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found", "vehicle_not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "not_found", "vehicle_not_found" ], "examples": [ { "name": "not_found", "value": { "error": "not_found", "message": "No record matches the given identifier" } }, { "name": "vehicle_not_found", "value": { "error": "vehicle_not_found", "message": "No vehicle is known for this identifier" } } ] } ], "errorCodes": [ "not_found", "vehicle_not_found" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/responses/429/content/application~1json/schema", "schema": { "title": "GetVinEconomicEvaluation429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/responses/500/content/application~1json/schema", "schema": { "title": "GetVinEconomicEvaluation500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Bundle", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get/responses/503/content/application~1json/schema", "schema": { "title": "GetVinEconomicEvaluation503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "vin_service_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "vin_service_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "vin_service_unavailable", "value": { "error": "vin_service_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "vin_service_unavailable" ] } ], "supportsIdempotencyKey": false, "asynchronous": true, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vin~1{vin}~1economic-evaluation/get" }, { "operationId": "getVinEconomicEvaluationJob", "method": "GET", "path": "/vin/economic-evaluation/jobs/{jobId}", "tags": [ "Intelligence" ], "summary": "Get the status of an economic evaluation", "description": "**Service description**\n\nReturns the current state of a previously accepted economic evaluation. While the status is `queued` or `running`, the client should observe `Retry-After`. On `succeeded`, `result` contains the complete evaluation. On `failed`, any charge for the original request has been refunded automatically. Status polling is part of the paid original service and creates no second order.\n\n**Usage and legal notice**\n\nThe paid service consists solely of the technical comparison or analysis and delivery of the result. Rights in the result are granted only to the extent provided by the agreement. Use of the result is governed by the agreement and applicable law. Results may be incomplete, outdated or incorrect and must be independently verified before technical, commercial or legal use.\n\nBy submitting a request, the user confirms that they are authorised to transmit and process the VIN and associated data and, where personal data is involved, have a valid legal basis. Only data necessary for the specific purpose may be submitted.\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "Job ID returned by the associated 202 response.", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-evaluation~1jobs~1{jobId}/get/parameters/0/schema", "schema": { "type": "string", "format": "uuid" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6955b900-0400-4548-9632-06e2f302e3d7" } ], "openApiPointer": "#/paths/~1vin~1economic-evaluation~1jobs~1{jobId}/get/parameters/0" } ], "requestBody": null, "responses": [ { "status": "200", "description": "Current state of the evaluation job; on success including the result", "headers": [ "Retry-After", "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1economic-evaluation~1jobs~1{jobId}/get/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VinEconomicEvaluationJobResponse", "schemaPointer": "#/components/schemas/VinEconomicEvaluationJobResponse", "exampleNames": [ "sandbox", "failed" ], "examples": [ { "name": "sandbox", "value": { "jobId": "6955b900-0400-4548-9632-06e2f302e3d7", "status": "queued", "statusUrl": "https://api.tapinomahub.com/vin/economic-evaluation/jobs/6955b900-0400-4548-9632-06e2f302e3d7", "vin": "TAPSANDBX00000001", "provider": 1, "retryAfterSeconds": 3, "createdAt": "2026-01-01T00:00:00+00:00" } }, { "name": "failed", "value": { "jobId": "6e2ce9c3-e2bf-40b3-ac9c-a7918519acee", "status": "failed", "statusUrl": "https://api.tapinomahub.com/vin/economic-evaluation/jobs/6e2ce9c3-e2bf-40b3-ac9c-a7918519acee", "vin": "WVWZZZ1JZXW000001", "provider": 1, "createdAt": "2026-01-01T00:00:00+00:00", "startedAt": "2026-01-01T00:00:05+00:00", "completedAt": "2026-01-01T00:01:00+00:00", "error": { "code": "vin_service_unavailable", "message": "The service is temporarily unavailable." } } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [], "openApiPointer": "#/paths/~1vin~1economic-evaluation~1jobs~1{jobId}/get/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-evaluation~1jobs~1{jobId}/get/responses/400/content/application~1json/schema", "schema": { "title": "GetVinEconomicEvaluationJob400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } ] } ], "errorCodes": [ "idempotency_key_not_supported" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vin~1economic-evaluation~1jobs~1{jobId}/get/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-evaluation~1jobs~1{jobId}/get/responses/401/content/application~1json/schema", "schema": { "title": "GetVinEconomicEvaluationJob401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1vin~1economic-evaluation~1jobs~1{jobId}/get/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-evaluation~1jobs~1{jobId}/get/responses/403/content/application~1json/schema", "schema": { "title": "GetVinEconomicEvaluationJob403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "404", "description": "Not found", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1economic-evaluation~1jobs~1{jobId}/get/responses/404", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-evaluation~1jobs~1{jobId}/get/responses/404/content/application~1json/schema", "schema": { "title": "GetVinEconomicEvaluationJob404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found", "vin_economic_evaluation_job_not_found" ] }, "message": { "type": "string" } } }, "exampleNames": [ "not_found", "vin_economic_evaluation_job_not_found" ], "examples": [ { "name": "not_found", "value": { "error": "not_found", "message": "No record matches the given identifier" } }, { "name": "vin_economic_evaluation_job_not_found", "value": { "error": "vin_economic_evaluation_job_not_found", "message": "No economic evaluation job exists under this jobId" } } ] } ], "errorCodes": [ "not_found", "vin_economic_evaluation_job_not_found" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vin~1economic-evaluation~1jobs~1{jobId}/get/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-evaluation~1jobs~1{jobId}/get/responses/429/content/application~1json/schema", "schema": { "title": "GetVinEconomicEvaluationJob429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vin~1economic-evaluation~1jobs~1{jobId}/get/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-evaluation~1jobs~1{jobId}/get/responses/500/content/application~1json/schema", "schema": { "title": "GetVinEconomicEvaluationJob500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [], "openApiPointer": "#/paths/~1vin~1economic-evaluation~1jobs~1{jobId}/get/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vin~1economic-evaluation~1jobs~1{jobId}/get/responses/503/content/application~1json/schema", "schema": { "title": "GetVinEconomicEvaluationJob503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": false, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vin~1economic-evaluation~1jobs~1{jobId}/get" }, { "operationId": "readLicensePlates", "method": "POST", "path": "/vision/license-plate", "tags": [ "Vision" ], "summary": "Read vehicle licence plates from a photo", "description": "**Service description**\n\nReads the vehicle licence plates off up to three photos and returns, for each plate found, the characters, a separator-free comparison form, the country as an ISO-3166-1 alpha-2 code, the confidence of the reading, the position on the vehicle and the reasons for an incomplete reading. Only what is visible in the image is returned: there is no keeper lookup, no register comparison and no statement about whether the vehicle is registered or the plate genuine. For a partly legible plate, `text`, `confidence` and `obstructions` carry the documented partial information; characters are never filled in. Where no plate is found, `plates` is empty. Not to be confused with anonymisation — this endpoint makes plates readable, it does not obscure them. The result is personal data; the legal basis for using it further rests with the caller.\n\n**Usage and legal notice**\n\nFor endpoints with quality levels, `standard` is the default. Billing for `standard`, `enhanced` and `maximum` is governed exclusively by the contractually agreed terms. The levels may differ in processing scope and response time.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1license-plate/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1vision~1license-plate/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1license-plate/post/requestBody/content/application~1json/schema", "schema": { "type": "object", "additionalProperties": false, "required": [ "imageUrls" ], "properties": { "imageUrls": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "string", "format": "uri" }, "description": "One to three publicly accessible image URLs that the caller is authorized to transmit and process.", "example": [ "https://example.com/fahrzeug-front.jpg" ] }, "quality": { "$ref": "#/components/schemas/ScannerQuality" } } }, "exampleNames": [], "examples": [] } ] }, "responses": [ { "status": "200", "description": "Licence plates found", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1license-plate/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VisionLicensePlateResponse", "schemaPointer": "#/components/schemas/VisionLicensePlateResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "format": "tapinoma.license-plate.v1", "imageCount": 1, "plateCount": 1, "plates": [ { "text": "SBX-AA 1", "normalized": "SBXAA1", "country": "DE", "confidence": "hoch", "position": "vorne", "obstructions": [] } ] } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1license-plate/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1license-plate/post/responses/400/content/application~1json/schema", "schema": { "title": "ReadLicensePlates400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vision~1license-plate/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1license-plate/post/responses/401/content/application~1json/schema", "schema": { "title": "ReadLicensePlates401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1license-plate/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1license-plate/post/responses/402/content/application~1json/schema", "schema": { "title": "ReadLicensePlates402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1vision~1license-plate/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1license-plate/post/responses/403/content/application~1json/schema", "schema": { "title": "ReadLicensePlates403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1license-plate/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1license-plate/post/responses/409/content/application~1json/schema", "schema": { "title": "ReadLicensePlates409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1license-plate/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1license-plate/post/responses/429/content/application~1json/schema", "schema": { "title": "ReadLicensePlates429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Documented HTTP 500 response.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1license-plate/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1license-plate/post/responses/500/content/application~1json/schema", "schema": { "title": "ReadLicensePlates500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1license-plate/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1license-plate/post/responses/503/content/application~1json/schema", "schema": { "title": "ReadLicensePlates503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1vision~1license-plate/post" }, { "operationId": "compositePartIntoBackground", "method": "POST", "path": "/vision/part/composite", "tags": [ "Vision" ], "summary": "Composite a new part into a background image", "description": "**Service description**\n\nComposite a new part into a background image. The request and response follow the schemas documented below.\n\n**Usage and legal notice**\n\nFor endpoints with quality levels, `standard` is the default. Billing for `standard`, `enhanced` and `maximum` is governed exclusively by the contractually agreed terms. The levels may differ in processing scope and response time.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1composite/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1vision~1part~1composite/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VisionPartCompositeRequest", "schemaPointer": "#/components/schemas/VisionPartCompositeRequest", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "partImageUrl": "https://example.com/neuteil.png", "backgroundImageUrl": "https://example.com/werkstatt.jpg", "targetBox": { "x": 0.18, "y": 0.22, "width": 0.64, "height": 0.55 }, "quality": "standard", "output": { "size": "1536x1024", "format": "jpeg" } } } ] } ] }, "responses": [ { "status": "200", "description": "New part composited into the background image", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1composite/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VisionPartCompositeResponse", "schemaPointer": "#/components/schemas/VisionPartCompositeResponse", "exampleNames": [ "documented" ], "examples": [ { "name": "documented", "value": { "format": "tapinoma.part-composite.v1", "asset": { "imageUrl": "https://sandbox.invalid/vision/image-workflows/part-composite/composite.jpg", "view": "custom", "width": 1536, "height": 1024, "format": "jpeg", "expiresAt": null, "provenance": { "format": "tapinoma.vision-provenance.v1", "assetType": "synthetic_reference", "synthetic": true, "requiredLabel": "KI-generierte Abbildung – kein Originalfoto des Einzelteils", "disclosureEmbedded": true, "sourceImageUrls": [ "https://example.com/neuteil.png", "https://example.com/werkstatt.jpg" ], "identifierRedaction": { "policy": "tapinoma.public-asset-identifiers.v1", "applied": false, "verified": true, "detections": [], "machineReadableCodesInvalidated": 0, "preservedTypeIdentifiers": [] }, "createdAt": "2026-01-01T00:00:00+00:00" } }, "partIdentityPreserved": true, "limitations": [] } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1composite/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1composite/post/responses/400/content/application~1json/schema", "schema": { "title": "CompositePartIntoBackground400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vision~1part~1composite/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1composite/post/responses/401/content/application~1json/schema", "schema": { "title": "CompositePartIntoBackground401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1composite/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1composite/post/responses/402/content/application~1json/schema", "schema": { "title": "CompositePartIntoBackground402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "API key invalid or endpoint not enabled", "headers": [], "openApiPointer": "#/paths/~1vision~1part~1composite/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1composite/post/responses/403/content/application~1json/schema", "schema": { "title": "CompositePartIntoBackground403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Idempotency-Key already used for a different request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1part~1composite/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1composite/post/responses/409/content/application~1json/schema", "schema": { "title": "CompositePartIntoBackground409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "422", "description": "Output could not be verified safely", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1composite/post/responses/422", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1composite/post/responses/422/content/application~1json/schema", "schema": { "title": "CompositePartIntoBackground422Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "part_segmentation_failed", "image_edit_unverified" ] }, "message": { "type": "string" } } }, "exampleNames": [ "part_segmentation_failed", "image_edit_unverified" ], "examples": [ { "name": "part_segmentation_failed", "value": { "error": "part_segmentation_failed", "message": "The part could not be reliably separated from its surroundings" } }, { "name": "image_edit_unverified", "value": { "error": "image_edit_unverified", "message": "The edited image could not be verified against the source, so no image is returned" } } ] } ], "errorCodes": [ "image_edit_unverified", "part_segmentation_failed" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1part~1composite/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1composite/post/responses/429/content/application~1json/schema", "schema": { "title": "CompositePartIntoBackground429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Image processing failed", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1composite/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1composite/post/responses/500/content/application~1json/schema", "schema": { "title": "CompositePartIntoBackground500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1composite/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1composite/post/responses/503/content/application~1json/schema", "schema": { "title": "CompositePartIntoBackground503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": 300, "openApiPointer": "#/paths/~1vision~1part~1composite/post" }, { "operationId": "transferVisibleDamageToPartViews", "method": "POST", "path": "/vision/part/damage-transfer", "tags": [ "Vision" ], "summary": "Transfer visible damage to standard views", "description": "**Service description**\n\nTransfer visible damage to standard views. The request and response follow the schemas documented below.\n\n**Usage and legal notice**\n\nFor endpoints with quality levels, `standard` is the default. Billing for `standard`, `enhanced` and `maximum` is governed exclusively by the contractually agreed terms. The levels may differ in processing scope and response time.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1damage-transfer/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1vision~1part~1damage-transfer/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VisionDamageTransferRequest", "schemaPointer": "#/components/schemas/VisionDamageTransferRequest", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "sources": [ { "imageUrl": "https://example.com/tuer-montiert.jpg", "view": "left" } ], "targets": [ { "imageUrl": "https://example.com/tuer-standard-links.jpg", "view": "left" } ], "partType": "Fahrertür links", "quality": "standard", "output": { "size": "1536x1024", "format": "jpeg" } } } ] } ] }, "responses": [ { "status": "200", "description": "Visible damage transferred to target views", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1damage-transfer/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VisionDamageTransferResponse", "schemaPointer": "#/components/schemas/VisionDamageTransferResponse", "exampleNames": [ "documented" ], "examples": [ { "name": "documented", "value": { "format": "tapinoma.damage-transfer.v1", "assets": [ { "imageUrl": "https://sandbox.invalid/vision/image-workflows/damage-transfer/01-left.jpg", "view": "left", "width": 1536, "height": 1024, "format": "jpeg", "expiresAt": null, "provenance": { "format": "tapinoma.vision-provenance.v1", "assetType": "synthetic_condition", "synthetic": true, "requiredLabel": "KI-generierte Zustandsdarstellung auf Basis der Originalfotos – kein Originalfoto des Einzelteils", "disclosureEmbedded": true, "sourceImageUrls": [ "https://example.com/tuer-montiert.jpg", "https://example.com/tuer-standard-links.jpg" ], "identifierRedaction": { "policy": "tapinoma.public-asset-identifiers.v1", "applied": false, "verified": true, "detections": [], "machineReadableCodesInvalidated": 0, "preservedTypeIdentifiers": [] }, "createdAt": "2026-01-01T00:00:00+00:00" } } ], "findings": [ { "type": "scratch", "description": "Synthetic sandbox scratch", "location": "unteres Drittel des Bauteils", "confidence": 1, "sourceImageIndexes": [ 0 ], "transferredToViews": [ "left" ] } ], "notTransferred": [], "limitations": [], "visualOnly": true } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1damage-transfer/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1damage-transfer/post/responses/400/content/application~1json/schema", "schema": { "title": "TransferVisibleDamageToPartViews400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vision~1part~1damage-transfer/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1damage-transfer/post/responses/401/content/application~1json/schema", "schema": { "title": "TransferVisibleDamageToPartViews401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1damage-transfer/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1damage-transfer/post/responses/402/content/application~1json/schema", "schema": { "title": "TransferVisibleDamageToPartViews402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "API key invalid or endpoint not enabled", "headers": [], "openApiPointer": "#/paths/~1vision~1part~1damage-transfer/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1damage-transfer/post/responses/403/content/application~1json/schema", "schema": { "title": "TransferVisibleDamageToPartViews403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Idempotency-Key already used for a different request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1part~1damage-transfer/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1damage-transfer/post/responses/409/content/application~1json/schema", "schema": { "title": "TransferVisibleDamageToPartViews409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "422", "description": "Output could not be verified safely", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1damage-transfer/post/responses/422", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1damage-transfer/post/responses/422/content/application~1json/schema", "schema": { "title": "TransferVisibleDamageToPartViews422Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "damage_not_transferable", "image_edit_unverified" ] }, "message": { "type": "string" } } }, "exampleNames": [ "damage_not_transferable", "image_edit_unverified" ], "examples": [ { "name": "damage_not_transferable", "value": { "error": "damage_not_transferable", "message": "The visible damage could not be reliably transferred to the standard views" } }, { "name": "image_edit_unverified", "value": { "error": "image_edit_unverified", "message": "The edited image could not be verified against the source, so no image is returned" } } ] } ], "errorCodes": [ "damage_not_transferable", "image_edit_unverified" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1part~1damage-transfer/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1damage-transfer/post/responses/429/content/application~1json/schema", "schema": { "title": "TransferVisibleDamageToPartViews429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Image processing failed", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1damage-transfer/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1damage-transfer/post/responses/500/content/application~1json/schema", "schema": { "title": "TransferVisibleDamageToPartViews500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1part~1damage-transfer/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1part~1damage-transfer/post/responses/503/content/application~1json/schema", "schema": { "title": "TransferVisibleDamageToPartViews503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": 300, "openApiPointer": "#/paths/~1vision~1part~1damage-transfer/post" }, { "operationId": "redactPartIdentifiers", "method": "POST", "path": "/vision/identifiers/redact", "tags": [ "Vision" ], "summary": "Redact instance identifiers in part images", "description": "**Service description**\n\nRedact instance identifiers in part images. The request and response follow the schemas documented below.\n\n**Usage and legal notice**\n\nFor endpoints with quality levels, `standard` is the default. Billing for `standard`, `enhanced` and `maximum` is governed exclusively by the contractually agreed terms. The levels may differ in processing scope and response time.\n\nBy submitting a request, the user confirms that they hold all rights, consents and other authorisations required to transmit and automatically process every image, document, URL and item of content. This includes in particular copyright and usage rights, confidentiality obligations and data-protection rights. Personal data may be submitted only on a valid legal basis and limited to what is necessary for the specific purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1identifiers~1redact/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1vision~1identifiers~1redact/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VisionIdentifierRedactRequest", "schemaPointer": "#/components/schemas/VisionIdentifierRedactRequest", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "imageUrls": [ "https://example.com/steuergeraet.jpg" ], "quality": "standard", "output": { "size": "1536x1024", "format": "jpeg" } } } ] } ] }, "responses": [ { "status": "200", "description": "Identifiers redacted and result verified", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1identifiers~1redact/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/VisionIdentifierRedactResponse", "schemaPointer": "#/components/schemas/VisionIdentifierRedactResponse", "exampleNames": [ "documented" ], "examples": [ { "name": "documented", "value": { "format": "tapinoma.identifier-redaction.v1", "assets": [ { "imageUrl": "https://sandbox.invalid/vision/image-workflows/identifier-redaction/01.jpg", "view": "custom", "width": 1536, "height": 1024, "format": "jpeg", "expiresAt": null, "provenance": { "format": "tapinoma.vision-provenance.v1", "assetType": "identifier_redacted_original", "synthetic": false, "requiredLabel": "Kennungen anonymisiert", "disclosureEmbedded": true, "sourceImageUrls": [ "https://example.com/steuergeraet.jpg" ], "identifierRedaction": { "policy": "tapinoma.public-asset-identifiers.v1", "applied": true, "verified": true, "detections": [ { "kind": "serial_number", "sourceImageIndex": 0, "region": { "x": 0.2, "y": 0.2, "width": 0.5, "height": 0.1 }, "action": "value_replaced_with_x", "confidence": 1, "preservedPrefixLength": 0, "maskedCharacterCount": 12 } ], "machineReadableCodesInvalidated": 0, "preservedTypeIdentifiers": [] }, "createdAt": "2026-01-01T00:00:00+00:00" } } ] } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1identifiers~1redact/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1identifiers~1redact/post/responses/400/content/application~1json/schema", "schema": { "title": "RedactPartIdentifiers400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1vision~1identifiers~1redact/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1identifiers~1redact/post/responses/401/content/application~1json/schema", "schema": { "title": "RedactPartIdentifiers401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1identifiers~1redact/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1identifiers~1redact/post/responses/402/content/application~1json/schema", "schema": { "title": "RedactPartIdentifiers402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "API key invalid or endpoint not enabled", "headers": [], "openApiPointer": "#/paths/~1vision~1identifiers~1redact/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1identifiers~1redact/post/responses/403/content/application~1json/schema", "schema": { "title": "RedactPartIdentifiers403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Idempotency-Key already used for a different request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1identifiers~1redact/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1identifiers~1redact/post/responses/409/content/application~1json/schema", "schema": { "title": "RedactPartIdentifiers409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "422", "description": "Output could not be verified safely", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1identifiers~1redact/post/responses/422", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1identifiers~1redact/post/responses/422/content/application~1json/schema", "schema": { "title": "RedactPartIdentifiers422Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "identifier_redaction_unverified" ] }, "message": { "type": "string" } } }, "exampleNames": [ "identifier_redaction_unverified" ], "examples": [ { "name": "identifier_redaction_unverified", "value": { "error": "identifier_redaction_unverified", "message": "The identifier redaction could not be verified, so no image is returned" } } ] } ], "errorCodes": [ "identifier_redaction_unverified" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1vision~1identifiers~1redact/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1identifiers~1redact/post/responses/429/content/application~1json/schema", "schema": { "title": "RedactPartIdentifiers429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Image processing failed", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1identifiers~1redact/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1identifiers~1redact/post/responses/500/content/application~1json/schema", "schema": { "title": "RedactPartIdentifiers500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1vision~1identifiers~1redact/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1vision~1identifiers~1redact/post/responses/503/content/application~1json/schema", "schema": { "title": "RedactPartIdentifiers503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": 300, "openApiPointer": "#/paths/~1vision~1identifiers~1redact/post" }, { "operationId": "identifyPart", "method": "POST", "path": "/parts/identify", "tags": [ "Parts" ], "summary": "Identify a part from customer number, label and parts list", "description": "**Service description**\n\nUses the submitted numbers, image readings, descriptions and vehicle context to determine possible OE part numbers. The response distinguishes a confirmed match, candidates and no match.\n\n**Usage and legal notice**\n\nThe paid service consists solely of the technical comparison or analysis and delivery of the result. Rights in the result are granted only to the extent provided by the agreement. Use of the result is governed by the agreement and applicable law. Results may be incomplete, outdated or incorrect and must be independently verified before technical, commercial or legal use.\n\nThe customer confirms that they are the keeper, owner, demonstrably authorised representative, or another legally entitled actor, and that they use the VIN exclusively for the stated lawful purpose.", "authentication": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Public parameter `Idempotency-Key` defined by this schema.", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1identify/post/parameters/0/schema", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" } ], "openApiPointer": "#/paths/~1parts~1identify/post/parameters/0" } ], "requestBody": { "required": true, "description": null, "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/PartIdentifyRequest", "schemaPointer": "#/components/schemas/PartIdentifyRequest", "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "vin": "TAPSANDBX00000001", "manufacturer": "SANDBOX MOTORS", "customerOeNumbers": [ "SBX 0001 A" ], "labelReadings": [ { "extractAll": { "primaryPartNumber": "SBX 0001 A", "otherPartNumbers": [ "SBX0009Z" ] } } ], "descriptions": [ "Sandbox Scheinwerfer links" ] } } ] } ] }, "responses": [ { "status": "200", "description": "Part identification completed", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Idempotency-Stored", "X-Tapinoma-Idempotent-Replay", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1identify/post/responses/200", "content": [ { "mediaType": "application/json", "schemaRef": "#/components/schemas/PartIdentifyResponse", "schemaPointer": "#/components/schemas/PartIdentifyResponse", "exampleNames": [ "sandbox" ], "examples": [ { "name": "sandbox", "value": { "status": "matched", "oeNumber": "SBX0001A", "normalizedOeNumber": "SBX0001A", "tapiGenArt": "TGA-000001", "source": "customer", "confidence": 0.99, "manufacturer": "SANDBOX MOTORS", "vinPart": { "name": "Sandbox Scheinwerfer links", "number": "SBX0001A", "tapiGenArt": "TGA-000001", "category": "lighting", "listPrice": 383.65 }, "candidates": [] } } ] } ], "errorCodes": [] }, { "status": "400", "description": "Invalid request", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1identify/post/responses/400", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1identify/post/responses/400/content/application~1json/schema", "schema": { "title": "IdentifyPart400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "bad_request", "invalid_idempotency_key" ], "examples": [ { "name": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, { "name": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } ] } ], "errorCodes": [ "bad_request", "invalid_idempotency_key" ] }, { "status": "401", "description": "API key is missing", "headers": [], "openApiPointer": "#/paths/~1parts~1identify/post/responses/401", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1identify/post/responses/401/content/application~1json/schema", "schema": { "title": "IdentifyPart401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } ] } ], "errorCodes": [ "missing_api_key" ] }, { "status": "402", "description": "Insufficient balance", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1identify/post/responses/402", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1identify/post/responses/402/content/application~1json/schema", "schema": { "title": "IdentifyPart402Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, "message": { "type": "string" } } }, "exampleNames": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ], "examples": [ { "name": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, { "name": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, { "name": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } ] } ], "errorCodes": [ "insufficient_credits", "partner_terms_not_covered", "sponsorship_cap_reached" ] }, { "status": "403", "description": "Invalid API key", "headers": [], "openApiPointer": "#/paths/~1parts~1identify/post/responses/403", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1identify/post/responses/403/content/application~1json/schema", "schema": { "title": "IdentifyPart403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "exampleNames": [ "endpoint_not_allowed", "invalid_api_key" ], "examples": [ { "name": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, { "name": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } ] } ], "errorCodes": [ "endpoint_not_allowed", "invalid_api_key" ] }, { "status": "409", "description": "Conflict with an earlier request", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1parts~1identify/post/responses/409", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1identify/post/responses/409/content/application~1json/schema", "schema": { "title": "IdentifyPart409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ], "examples": [ { "name": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, { "name": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, { "name": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } ] } ], "errorCodes": [ "idempotency_key_conflict", "idempotency_request_in_progress", "idempotency_result_unavailable" ] }, { "status": "429", "description": "Rate limit exceeded or parallel request active", "headers": [ "Retry-After" ], "openApiPointer": "#/paths/~1parts~1identify/post/responses/429", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1identify/post/responses/429/content/application~1json/schema", "schema": { "title": "IdentifyPart429Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "client_request_in_progress", "rate_limit_exceeded" ] }, "message": { "type": "string" } } }, "exampleNames": [ "client_request_in_progress", "rate_limit_exceeded" ], "examples": [ { "name": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, { "name": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } ] } ], "errorCodes": [ "client_request_in_progress", "rate_limit_exceeded" ] }, { "status": "500", "description": "Part identification failed", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1identify/post/responses/500", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1identify/post/responses/500/content/application~1json/schema", "schema": { "title": "IdentifyPart500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "exampleNames": [ "example" ], "examples": [ { "name": "example", "value": { "error": "internal_error", "message": "The request could not be completed" } } ] } ], "errorCodes": [ "internal_error" ] }, { "status": "503", "description": "The service is temporarily unavailable.", "headers": [ "X-Tapinoma-Billing-Source", "X-Tapinoma-Sponsorship-Grant", "X-Tapinoma-Usage-Warning" ], "openApiPointer": "#/paths/~1parts~1identify/post/responses/503", "content": [ { "mediaType": "application/json", "schemaRef": null, "schemaPointer": "#/paths/~1parts~1identify/post/responses/503/content/application~1json/schema", "schema": { "title": "IdentifyPart503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced", "parts_identify_unavailable" ] }, "message": { "type": "string" } } }, "exampleNames": [ "billing_unavailable", "parts_identify_unavailable", "endpoint_not_priced" ], "examples": [ { "name": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "parts_identify_unavailable", "value": { "error": "parts_identify_unavailable", "message": "The service is temporarily unavailable." } }, { "name": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } ] } ], "errorCodes": [ "billing_unavailable", "endpoint_not_priced", "parts_identify_unavailable" ] } ], "supportsIdempotencyKey": true, "asynchronous": false, "clientTimeoutSeconds": null, "openApiPointer": "#/paths/~1parts~1identify/post" } ], "errorCatalog": [ { "group": "request", "status": 400, "code": "unsupported_rate_limit_window", "retryable": false, "description": "`windowSeconds` is none of the windows the operator defines.", "groupLabel": "Request" }, { "group": "access", "status": 403, "code": "rate_limit_above_operator_default", "retryable": false, "description": "A rate limit must not exceed the operator default. Tighter limits for your own sub-users are allowed, wider ones are not.", "groupLabel": "Access" }, { "group": "request", "status": 400, "code": "invalid_idempotency_key", "retryable": false, "description": "The Idempotency-Key does not meet the character or length rules documented for the respective endpoint.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "idempotency_key_not_supported", "retryable": false, "description": "The request could not be completed with this error code.", "groupLabel": "Request" }, { "group": "flow", "status": 409, "code": "idempotency_key_conflict", "retryable": false, "description": "The same Idempotency-Key was already used for a different request. Choose a new key for a new request.", "groupLabel": "Workflow order" }, { "group": "request", "status": 400, "code": "invalid_vin", "retryable": false, "description": "The VIN is not 17 characters long or contains invalid characters.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "invalid_mode", "retryable": false, "description": "`mode` is neither `type` nor `vehicle`.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "invalid_oe_numbers", "retryable": false, "description": "`oeNumbers` is missing or is not a non-empty list.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "invalid_marketplace_id", "retryable": false, "description": "The supplied marketplace id is unknown.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "unsupported_marketplace_language", "retryable": false, "description": "The marketplace does not support the requested language.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "invalid_vehicle_type", "retryable": false, "description": "The supplied vehicle path is unknown. Use car or motorcycle.", "groupLabel": "Request" }, { "group": "notfound", "status": 404, "code": "seo_no_exact_match", "retryable": false, "description": "No exact match was found for the OE number on the selected vehicle path. The response additionally carries `oeNumber`, `marketplaceId`, `language` and `vehicleType`.", "groupLabel": "Not found" }, { "group": "notfound", "status": 404, "code": "vision_generation_job_not_found", "retryable": false, "description": "The requested image-generation job does not exist for this client or has expired.", "groupLabel": "Not found" }, { "group": "service", "status": 503, "code": "parts_service_unavailable", "retryable": true, "description": "The service is temporarily unavailable.", "groupLabel": "Service availability" }, { "group": "service", "status": 503, "code": "service_unavailable", "retryable": true, "description": "The translation service is temporarily unavailable.", "groupLabel": "Service availability" }, { "group": "access", "status": 401, "code": "missing_api_key", "retryable": false, "description": "The X-Api-Key header is missing.", "groupLabel": "Access" }, { "group": "access", "status": 403, "code": "invalid_api_key", "retryable": false, "description": "The API key is unknown, deactivated or blocked.", "groupLabel": "Access" }, { "group": "access", "status": 403, "code": "forbidden", "retryable": false, "description": "The request could not be completed with this error code.", "groupLabel": "Access" }, { "group": "access", "status": 403, "code": "endpoint_not_allowed", "retryable": false, "description": "This endpoint is not open to this client. Every master client has a list of the endpoints it may address; the list also binds its sub-users, which reach nothing beyond it. tapinoma maintains the list.", "groupLabel": "Access" }, { "group": "access", "status": 403, "code": "sandbox_endpoint_unavailable", "retryable": false, "description": "This endpoint is not available in the sandbox.", "groupLabel": "Access" }, { "group": "billing", "status": 402, "code": "insufficient_credits", "retryable": false, "description": "No active plan covers the endpoint, and balance plus overdraft allowance are insufficient.", "groupLabel": "Billing" }, { "group": "billing", "status": 402, "code": "sponsorship_cap_reached", "retryable": false, "description": "The monthly limit the sponsor set for this beneficiary is reached. It is counted net: refunded charges release it again.", "groupLabel": "Billing" }, { "group": "billing", "status": 402, "code": "partner_terms_not_covered", "retryable": false, "description": "The beneficiary works on sponsor terms and this endpoint is not part of the grant. The request is refused rather than silently charged to the own balance. Two exceptions: contract-included control calls and the beneficiary own administration under `/client/` stay open — otherwise the beneficiary could no longer read its balance or switch the choice back.", "groupLabel": "Billing" }, { "group": "billing", "status": 503, "code": "billing_unavailable", "retryable": true, "description": "Billing could not be verified; the request was not charged.", "groupLabel": "Billing" }, { "group": "limits", "status": 429, "code": "rate_limit_exceeded", "retryable": true, "description": "The rate limit for this endpoint has been reached.", "groupLabel": "Limits" }, { "group": "limits", "status": 429, "code": "client_request_in_progress", "retryable": true, "description": "A request for this client is already running. The limit applies per client, not per contract partner; retry after `Retry-After`.", "groupLabel": "Limits" }, { "group": "limits", "status": 429, "code": "seo_live_requests_paused", "retryable": true, "description": "Live enrichment is paused; X-Tapinoma-Live-Available-At states the earliest retry.", "groupLabel": "Limits" }, { "group": "request", "status": 400, "code": "bad_request", "retryable": false, "description": "The request is incomplete or a required field is missing.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "invalid_json", "retryable": false, "description": "The request body is not valid JSON.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "invalid_request", "retryable": false, "description": "The submitted fields do not form an executable request.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "invalid_query_parameter", "retryable": false, "description": "A query parameter carries an invalid value.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "unsupported_query_parameter", "retryable": false, "description": "A supplied query parameter is not supported by this endpoint.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "conflicting_query_parameters", "retryable": false, "description": "Two query parameters are mutually exclusive.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "invalid_country", "retryable": false, "description": "The country code is not two characters or is not supported.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "invalid_provider", "retryable": false, "description": "The request could not be completed with this error code.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "invalid_manufacturer", "retryable": false, "description": "The optional manufacturer is not permitted.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "invalid_oe_number", "retryable": false, "description": "The OE part number is empty or formally invalid.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "too_many_oe_numbers", "retryable": false, "description": "The cart contains more than 30 OE positions.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "text_required", "retryable": false, "description": "The text field is missing.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "text_too_long", "retryable": false, "description": "The text field exceeds the permitted length.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "source_language_required", "retryable": false, "description": "The request could not be completed with this error code.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "source_language_too_long", "retryable": false, "description": "The request could not be completed with this error code.", "groupLabel": "Request" }, { "group": "notfound", "status": 404, "code": "not_found", "retryable": false, "description": "The requested route does not exist.", "groupLabel": "Not found" }, { "group": "notfound", "status": 404, "code": "oe_part_not_found", "retryable": false, "description": "No part is known for this OE number.", "groupLabel": "Not found" }, { "group": "notfound", "status": 404, "code": "vehicle_not_found", "retryable": false, "description": "No vehicle data was found for the VIN, or the tapiId is unknown or not assigned to the authenticated client.", "groupLabel": "Not found" }, { "group": "notfound", "status": 404, "code": "vin_parts_job_not_found", "retryable": false, "description": "The VIN parts job does not exist or belongs to another client.", "groupLabel": "Not found" }, { "group": "notfound", "status": 404, "code": "vin_cart_check_job_not_found", "retryable": false, "description": "The cart check job does not exist or belongs to another client.", "groupLabel": "Not found" }, { "group": "notfound", "status": 404, "code": "vin_economic_evaluation_job_not_found", "retryable": false, "description": "The economic evaluation job does not exist or belongs to another client.", "groupLabel": "Not found" }, { "group": "flow", "status": 409, "code": "redirect_required", "retryable": false, "description": "The request could not be completed with this error code.", "groupLabel": "Workflow order" }, { "group": "flow", "status": 409, "code": "vin_provider_mismatch", "retryable": false, "description": "The request could not be completed with this error code.", "groupLabel": "Workflow order" }, { "group": "flow", "status": 409, "code": "sponsorship_conflict", "retryable": false, "description": "The grant contradicts an existing sponsorship.", "groupLabel": "Workflow order" }, { "group": "flow", "status": 409, "code": "ambiguous_grant_reference", "retryable": false, "description": "Several sponsors use the same reference for this beneficiary. The choice additionally needs `sponsorClientId` so it does not hit the wrong grant.", "groupLabel": "Workflow order" }, { "group": "flow", "status": 409, "code": "workspace_reference_exists", "retryable": false, "description": "A workspace already exists under this externalReference.", "groupLabel": "Workflow order" }, { "group": "flow", "status": 422, "code": "ambiguous_oe_number", "retryable": false, "description": "The OE number could not be resolved uniquely.", "groupLabel": "Workflow order" }, { "group": "service", "status": 500, "code": "internal_error", "retryable": true, "description": "Unexpected error. A charge that was already applied is refunded automatically.", "groupLabel": "Service availability" }, { "group": "service", "status": 503, "code": "seo_service_unavailable", "retryable": true, "description": "The service is temporarily unavailable.", "groupLabel": "Service availability" }, { "group": "service", "status": 503, "code": "oe_normalizer_unavailable", "retryable": true, "description": "OE normalisation is temporarily unavailable.", "groupLabel": "Service availability" }, { "group": "service", "status": 503, "code": "vin_service_unavailable", "retryable": true, "description": "The service is temporarily unavailable.", "groupLabel": "Service availability" }, { "group": "service", "status": 503, "code": "vdi_catalog_unavailable", "retryable": true, "description": "The VDI catalogue is temporarily unavailable.", "groupLabel": "Service availability" }, { "group": "request", "status": 400, "code": "invalid_positions", "retryable": false, "description": "`positions` is missing, empty or not a list.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "invalid_recall_position", "retryable": false, "description": "Every position needs an OE number or a vehicle make.", "groupLabel": "Request" }, { "group": "request", "status": 400, "code": "too_many_recall_positions", "retryable": false, "description": "More than 100 positions in one call.", "groupLabel": "Request" }, { "group": "notfound", "status": 404, "code": "vin_not_resolvable", "retryable": false, "description": "The VIN cannot be resolved to a vehicle series; the match was not performed and not billed.", "groupLabel": "Not found" }, { "group": "notfound", "status": 404, "code": "recall_positions_unresolvable", "retryable": false, "description": "None of the submitted positions could be assigned to a manufacturer; the call was not billed.", "groupLabel": "Not found" }, { "group": "service", "status": 503, "code": "recall_data_unavailable", "retryable": true, "description": "The request could not be completed with this error code.", "groupLabel": "Service availability" }, { "group": "billing", "status": 503, "code": "endpoint_not_priced", "retryable": true, "description": "No active price is configured for this endpoint; the request was not executed and was not charged.", "groupLabel": "Billing" }, { "group": "flow", "status": 409, "code": "idempotency_request_in_progress", "retryable": true, "description": "A call with the same Idempotency-Key is still being processed. The second call was neither executed nor charged and may be repeated unchanged after `Retry-After`.", "groupLabel": "Workflow order" }, { "group": "flow", "status": 409, "code": "idempotency_result_unavailable", "retryable": false, "description": "The request could not be completed with this error code.", "groupLabel": "Workflow order" }, { "group": "vision", "status": 422, "code": "identifier_redaction_unverified", "retryable": false, "description": "At least one instance identifier or machine-readable code could not be confirmed unreadable after editing; no image was returned.", "groupLabel": "Image verification" }, { "group": "vision", "status": 422, "code": "damage_not_transferable", "retryable": false, "description": "Visible damage could not be mapped reliably to a target view; no synthetic condition visual was returned.", "groupLabel": "Image verification" }, { "group": "vision", "status": 422, "code": "part_segmentation_failed", "retryable": false, "description": "The intended part could not be separated safely from adjacent surfaces or the background.", "groupLabel": "Image verification" }, { "group": "vision", "status": 422, "code": "image_edit_unverified", "retryable": false, "description": "The request could not be completed with this error code.", "groupLabel": "Image verification" }, { "group": "service", "status": 503, "code": "parts_identify_unavailable", "retryable": true, "description": "Part identification is temporarily unavailable.", "groupLabel": "Service availability" }, { "group": "intelligence_request", "status": 400, "code": "invalid_request_property", "retryable": false, "description": "The input violates the documented `invalid_request_property` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 400, "code": "invalid_json_object", "retryable": false, "description": "The input violates the documented `invalid_json_object` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 400, "code": "invalid_minimum_evidence", "retryable": false, "description": "The input violates the documented `invalid_minimum_evidence` condition.", "groupLabel": "Request" }, { "group": "intelligence_access", "status": 401, "code": "authentication_required", "retryable": false, "description": "Access was denied with `authentication_required`.", "groupLabel": "Access" }, { "group": "intelligence_access", "status": 403, "code": "market_intelligence_not_enabled", "retryable": false, "description": "Access was denied with `market_intelligence_not_enabled`.", "groupLabel": "Access" }, { "group": "intelligence_access", "status": 403, "code": "invalid_csrf", "retryable": false, "description": "Access was denied with `invalid_csrf`.", "groupLabel": "Access" }, { "group": "intelligence_access", "status": 403, "code": "email_not_verified", "retryable": false, "description": "Access was denied with `email_not_verified`.", "groupLabel": "Access" }, { "group": "intelligence_resource", "status": 404, "code": "cluster_not_found", "retryable": false, "description": "The requested resource is unavailable according to `cluster_not_found`.", "groupLabel": "Resource" }, { "group": "intelligence_resource", "status": 404, "code": "vin_not_found", "retryable": false, "description": "The requested resource is unavailable according to `vin_not_found`.", "groupLabel": "Resource" }, { "group": "intelligence_resource", "status": 404, "code": "job_not_found", "retryable": false, "description": "The requested resource is unavailable according to `job_not_found`.", "groupLabel": "Resource" }, { "group": "intelligence_resource", "status": 404, "code": "snapshot_not_found", "retryable": false, "description": "The requested resource is unavailable according to `snapshot_not_found`.", "groupLabel": "Resource" }, { "group": "intelligence_request", "status": 413, "code": "request_body_too_large", "retryable": false, "description": "The input violates the documented `request_body_too_large` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 415, "code": "unsupported_media_type", "retryable": false, "description": "The input violates the documented `unsupported_media_type` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 422, "code": "invalid_identifier", "retryable": false, "description": "The input violates the documented `invalid_identifier` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 422, "code": "identifier_required", "retryable": false, "description": "The input violates the documented `identifier_required` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 422, "code": "invalid_history_window", "retryable": false, "description": "The input violates the documented `invalid_history_window` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 422, "code": "invalid_vin", "retryable": false, "description": "The input violates the documented `invalid_vin` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 422, "code": "invalid_format", "retryable": false, "description": "The input violates the documented `invalid_format` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 422, "code": "invalid_enum", "retryable": false, "description": "The input violates the documented `invalid_enum` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 422, "code": "invalid_integer", "retryable": false, "description": "The input violates the documented `invalid_integer` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 422, "code": "invalid_boolean", "retryable": false, "description": "The input violates the documented `invalid_boolean` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 422, "code": "invalid_string", "retryable": false, "description": "The input violates the documented `invalid_string` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 422, "code": "invalid_date", "retryable": false, "description": "The input violates the documented `invalid_date` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 422, "code": "invalid_instant", "retryable": false, "description": "The input violates the documented `invalid_instant` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 422, "code": "ambiguous_cluster", "retryable": false, "description": "The input violates the documented `ambiguous_cluster` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 422, "code": "insufficient_evidence", "retryable": false, "description": "The input violates the documented `insufficient_evidence` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 422, "code": "refresh_unavailable", "retryable": false, "description": "The input violates the documented `refresh_unavailable` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 422, "code": "refresh_failed", "retryable": false, "description": "The input violates the documented `refresh_failed` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 422, "code": "refresh_completed_without_snapshot", "retryable": false, "description": "The input violates the documented `refresh_completed_without_snapshot` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 422, "code": "refresh_timeout", "retryable": false, "description": "The input violates the documented `refresh_timeout` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 422, "code": "refresh_job_missing", "retryable": false, "description": "The input violates the documented `refresh_job_missing` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 422, "code": "intelligence_job_failed", "retryable": false, "description": "The input violates the documented `intelligence_job_failed` condition.", "groupLabel": "Request" }, { "group": "intelligence_request", "status": 422, "code": "vin_intelligence_failed", "retryable": false, "description": "The input violates the documented `vin_intelligence_failed` condition.", "groupLabel": "Request" }, { "group": "intelligence_availability", "status": 502, "code": "invalid_vehicle_parts_response", "retryable": true, "description": "Processing is temporarily unavailable because of `invalid_vehicle_parts_response`.", "groupLabel": "Availability" }, { "group": "intelligence_availability", "status": 503, "code": "market_intelligence_vin_not_enabled", "retryable": true, "description": "Processing is temporarily unavailable because of `market_intelligence_vin_not_enabled`.", "groupLabel": "Availability" }, { "group": "intelligence_availability", "status": 503, "code": "vehicle_parts_unavailable", "retryable": true, "description": "Processing is temporarily unavailable because of `vehicle_parts_unavailable`.", "groupLabel": "Availability" }, { "group": "intelligence_availability", "status": 503, "code": "market_intelligence_dependency_unavailable", "retryable": true, "description": "Processing is temporarily unavailable because of `market_intelligence_dependency_unavailable`.", "groupLabel": "Availability" }, { "group": "intelligence_availability", "status": 503, "code": "market_intelligence_unavailable", "retryable": true, "description": "Processing is temporarily unavailable because of `market_intelligence_unavailable`.", "groupLabel": "Availability" } ], "responseHeaders": [ { "name": "X-Tapinoma-Billing-Source", "example": "plan", "description": "Technical settlement decision: plan, balance, bundle, sandbox, or idempotent_replay. The value alone proves neither a debit nor a product price." }, { "name": "X-Tapinoma-Usage-Warning", "example": "Plan STANDARD for scanner.label.extract_all has reached at least 90% usage (90 of 100).", "description": "Human-readable warning text from 90 percent plan consumption and once the quota is used up; do not parse it as a stable code, and expect multiple warnings to be joined with ` | `." }, { "name": "X-Tapinoma-Billing-Bundle", "example": "VIN_MONTHLY_LOOKUP", "description": "Set when the request falls under a monthly bundle cap." }, { "name": "X-Tapinoma-Sponsorship-Grant", "example": "erp-customer-4711", "description": "Reference of the associated billing sponsor; it does not prove that this call caused a debit." }, { "name": "X-Tapinoma-Live-Available-At", "example": "2026-08-18T14:05:00+00:00", "description": "The public schema defines the meaning and format of `4`." }, { "name": "Retry-After", "example": "5", "description": "The public schema defines the meaning and format of `5`." }, { "name": "Location", "example": "/vin/parts/jobs/6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Status URL of a job accepted for asynchronous processing." }, { "name": "X-Tapinoma-Idempotent-Replay", "example": "true", "description": "Set to `true` when the response belongs to an earlier identical request; no additional charge." }, { "name": "X-Tapinoma-Idempotency-Stored", "example": "true", "description": "`true`: An unchanged repeat with the same `Idempotency-Key` can return the earlier result. `false`: The same key returns `409 idempotency_result_unavailable`." } ], "usageRules": { "regularPrices": "Billing and contract-included account or status operations are governed exclusively by the agreed terms. Concrete prices are not published in the API contract.", "plans": "A plan is not assigned to a client globally but per `endpoint_key`.", "multiplePlans": "A client can hold several active plans as long as they cover different `endpoint_key` values, for example VIN through plan A and scanner through plan B.", "fallbackCredits": "If no active plan covers the requested endpoint, or the monthly plan quota is used up, the credit balance is charged.", "vinMonthlyBundle": "VIN Vehicle, VIN Parts and VIN Cart Check form the monthly bundle VIN_MONTHLY_LOOKUP. Billing and repetitions are governed exclusively by the agreed terms. Cache or result reuse does not change customer billing.", "rateLimits": "Rate limits apply per `endpoint_key`. Agreed limits can apply per endpoint or across endpoints using `*`; otherwise the documented default limits apply.", "rateLimitConcurrency": "One active API request is allowed per client at a time. Further requests return `429 client_request_in_progress`. Distinct clients are scoped separately.", "warnings": "From 90 percent plan consumption, and once the quota is used up, the API sends the `X-Tapinoma-Usage-Warning` header. Its human-readable text is not a stable machine code; multiple warnings are joined with ` | `. An `included_monthly_quantity` of 0 means no included quota, not unlimited. `X-Tapinoma-Billing-Source` reports `plan`, `balance`, `bundle`, `sandbox`, or `idempotent_replay` and describes a technical settlement decision; the value alone proves neither a debit nor a product price.", "refunds": "A pre-charged individual call that ends with an HTTP status of 400 or above is generally refunded automatically. Combined workflows and contract-specific conditions follow the rules in the relevant service description or agreement.", "sandbox": "Sandbox access is intended for integration testing and uses the same base URL as production. Sandbox responses use only the documented synthetic test data; usage is governed by the agreed terms. Validation, authentication, rate limits and documented asynchronous states behave as described. Mutating endpoints may return `sandbox_endpoint_unavailable`.", "idempotency": "Supported write operations accept `Idempotency-Key`. A successful repeat with the same key returns the same result without another execution or charge. While an operation is running, a repeat returns `409 idempotency_request_in_progress`; when the repeat result cannot be retrieved, it returns `409 idempotency_result_unavailable`. Keys are scoped per client for 24 hours. Operations identified in their endpoint descriptions as issuing a new API key or processing sensitive document data do not support the header. The three Intelligence data GETs and `POST /vin/economic-intelligence` also require an `Idempotency-Key`. For these pilot operations, `X-Tapinoma-Idempotent-Replay: true` identifies a replay; they document `409 idempotency_key_conflict`, but neither `X-Tapinoma-Idempotency-Stored` nor the central in-progress or result-unavailable states. The two Intelligence status operations do not accept the header.", "pagination": "Endpoints with long lists accept `limit` (1 to 500) and `offset`. Without `limit` the response stays complete as before. `count` is the total in every response, the length of the page is in `page.returned`, and `page.hasMore` states whether another page follows. Each page is a separate call and is charged like a call, so fetching everything in one go remains the cheapest way.", "polling": "The documented VIN-parts, cart-check, economic-evaluation and image-generation job-status operations are part of the paid original service and create no second order. Billing and refunds follow the rules of the original order. Without approved positive prices and atomic billing, the new Intelligence routes remain locked. Status presentation for an asynchronous order is part of the paid original service and creates no second order. Without approved positive prices and atomic billing, the new Intelligence routes remain locked." } }