{ "openapi": "3.1.0", "info": { "title": "tapinomahub API", "version": "1.71.0", "description": "tapinomahub API v1 – the central interface for VIN, parts, VDI, scanner, translation, vision, vehicle and recall services, plus public client administration. Every endpoint contains a service description and its applicable usage and billing rules. The Intelligence category groups part-market, pricing and VIN economic analyses with transparent evidence and confidence. The six new cluster-based Intelligence operations form a closed, paid production pilot; real data stays locked until positive prices and atomic billing are approved." }, "x-release": { "status": "published" }, "servers": [ { "url": "https://api.tapinomahub.com", "description": "Production server" } ], "security": [ { "apiKeyAuth": [] } ], "components": { "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "marketIntelligenceSessionCookie": { "type": "apiKey", "in": "cookie", "name": "__Host-tapinomahub_session", "description": "Verified first-party session for an explicitly enabled pilot account." } }, "schemas": { "MarketIntelligenceIntelligenceStatus": { "type": "string", "enum": [ "scored", "indicative", "insufficient_evidence" ] }, "MarketIntelligenceEvidenceLevel": { "type": "string", "enum": [ "insufficient", "directional", "usable", "strong" ] }, "MarketIntelligenceClusterIntelligenceResponse": { "type": "object", "additionalProperties": false, "required": [ "apiVersion", "requestId", "status", "asOf", "validUntil", "scope", "cluster", "evidence", "prices", "standtime", "trend", "scores", "confidence", "provenance", "warnings" ], "properties": { "apiVersion": { "type": "string", "const": "market-intelligence-v1" }, "requestId": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/MarketIntelligenceIntelligenceStatus" }, "asOf": { "type": "string", "format": "date-time" }, "validUntil": { "type": "string", "format": "date-time" }, "scope": { "$ref": "#/components/schemas/MarketIntelligenceMarketScope" }, "cluster": { "$ref": "#/components/schemas/MarketIntelligencePartCluster" }, "evidence": { "$ref": "#/components/schemas/MarketIntelligenceEvidenceBundle" }, "prices": { "$ref": "#/components/schemas/MarketIntelligencePriceIntelligence" }, "standtime": { "$ref": "#/components/schemas/MarketIntelligenceStandtimeIntelligence" }, "trend": { "$ref": "#/components/schemas/MarketIntelligenceTrendIntelligence" }, "scores": { "$ref": "#/components/schemas/MarketIntelligenceScores" }, "confidence": { "$ref": "#/components/schemas/MarketIntelligenceConfidenceSummary" }, "provenance": { "$ref": "#/components/schemas/MarketIntelligenceProvenance" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/MarketIntelligenceWarning" } } }, "example": { "apiVersion": "market-intelligence-v1", "requestId": "0ff6f6bf-295e-4c55-b1d2-f74329500cbc", "status": "scored", "asOf": "2026-09-11T12:00:00Z", "validUntil": "2026-09-12T12:00:00Z", "scope": { "marketCountry": "DE", "currency": "EUR", "condition": "used", "windowDays": 90 }, "cluster": { "clusterId": "2c236555-644a-4e6f-98d9-64ff0ce1ef7e", "clusterVersion": 4, "canonicalLabel": "Bremssattel vorne links", "identityConfidence": 94, "identifiers": [ { "scheme": "oe", "value": "8K0615123A", "manufacturer": "AUDI", "role": "current_oe", "confidence": 98 }, { "scheme": "oe", "value": "8K0615123", "manufacturer": "AUDI", "role": "superseded_oe", "confidence": 93 } ], "dimensions": { "kTypes": [ 18463 ], "natCodes": [ "AT12345" ], "genArts": [ "82" ] } }, "evidence": { "observedSupply": { "evidenceClass": "observed_supply", "available": true, "activeListingCount": 84, "distinctSellerCount": 26, "observationDayCount": 87, "sourceCount": 3, "askingPrice": { "currency": "EUR", "priceBasis": "gross", "sampleSize": 81, "p10Minor": 7800, "p25Minor": 9400, "p50Minor": 11900, "p75Minor": 14900, "p90Minor": 17900 }, "latestObservedAt": "2026-09-11T08:10:00Z", "qualityScore": 86 }, "verifiedSales": { "evidenceClass": "verified_sale", "available": true, "verifiedSaleCount": 63, "effectiveSampleSize": 47.8, "distinctContributorCount": 8, "observationDayCount": 90, "matureCohortCount": 121, "realizedPrice": { "currency": "EUR", "priceBasis": "gross", "sampleSize": 63, "p10Minor": 8200, "p25Minor": 9700, "p50Minor": 12100, "p75Minor": 14300, "p90Minor": 16800 }, "refundRate": 0.047, "latestSoldAt": "2026-09-10T16:20:00Z", "qualityScore": 91 }, "internalUsage": { "evidenceClass": "internal_usage", "available": true, "eventCount": 214, "weightedEventCount": 326.5, "distinctAccountCount": 37, "latestEventAt": "2026-09-11T10:42:00Z", "qualityScore": 88 } }, "prices": { "marketPrice": { "available": true, "amountMinor": 12100, "currency": "EUR", "priceBasis": "gross", "basis": "verified_sales_p50" }, "recommendedRange": { "available": true, "publishable": true, "floorMinor": 10500, "targetMinor": 12400, "ceilingMinor": 14600, "currency": "EUR", "priceBasis": "gross", "basis": "hierarchical_verified_sales" } }, "standtime": { "available": true, "status": "scored", "expectedDays": 41, "p50Days": 35, "p80Days": 83, "saleProbability": { "p30": 0.44, "p60": 0.68, "p90": 0.79 }, "events": 63, "censored": 84, "method": "competing_risk_survival_v1", "confidence": 73 }, "trend": { "available": true, "status": "scored", "direction": "up", "change30dPct": 0.036, "interval30dPct": { "low": -0.008, "high": 0.081 }, "probabilityPositive": 0.79, "timeBuckets": 12, "method": "robust_log_price_slope_v1", "confidence": 68 }, "scores": { "demand": { "value": 72, "confidence": 78, "status": "scored", "explanation": "Panel-adjusted verified sales dominate this score." }, "liquidity": { "value": 67, "confidence": 73, "status": "scored", "explanation": "Sale-and-kept probabilities include censored active listings." }, "competition": { "value": 58, "confidence": 71, "status": "scored", "explanation": "Supply-to-sales pressure and seller breadth are moderately high." }, "priceConfidence": { "value": 76, "confidence": 76, "status": "scored", "explanation": "Twelve contributors and 47.8 effective sales support the price cell." }, "opportunity": { "value": 69, "posteriorMean": 69, "interval": { "low": 54, "high": 84, "calibrated": false, "method": "confidence_scaled_envelope_v0" }, "confidence": 70, "status": "scored", "factors": [ { "name": "demand", "value": 72, "weight": 0.3, "contribution": 21.6, "confidence": 78, "evidence": "verified_sales" }, { "name": "liquidity", "value": 67, "weight": 0.25, "contribution": 16.75, "confidence": 73, "evidence": "verified_sales_and_observed_supply" }, { "name": "risk_adjusted_yield", "value": 71, "weight": 0.2, "contribution": 14.2, "confidence": 62, "evidence": "verified_sales_and_cost_prior" }, { "name": "inverse_competition", "value": 42, "weight": 0.15, "contribution": 6.3, "confidence": 71, "evidence": "observed_supply" }, { "name": "trend", "value": 79, "weight": 0.1, "contribution": 7.9, "confidence": 68, "evidence": "verified_sales" } ], "limitations": [ "opportunity_interval_uncalibrated_v0" ] } }, "confidence": { "value": 70, "level": "usable", "publishable": true, "effectiveSampleSize": 47.8, "contributorCount": 12, "observationDays": 90, "identityConfidence": 94, "caps": [], "missingEvidence": [] }, "provenance": { "clusterVersion": 4, "clusteringModelVersion": "part-cluster-v1", "intelligenceModelVersion": "mi-2026-09-11.1", "scoreVersion": "opportunity-v1", "snapshotId": "2f0bb94e-a6e8-42c0-9341-bc42d7e9ba5b", "sourceCutoffs": { "observedSupply": "2026-09-11T08:10:00Z", "verifiedSales": "2026-09-10T16:20:00Z", "internalUsage": "2026-09-11T10:42:00Z" }, "restated": false }, "warnings": [ { "code": "cost_prior_used", "message": "Landed cost was unavailable; risk-adjusted yield uses a category prior." } ] } }, "MarketIntelligenceMarketScope": { "type": "object", "additionalProperties": false, "required": [ "marketCountry", "currency", "condition", "windowDays" ], "properties": { "marketCountry": { "type": "string", "pattern": "^[A-Z]{2}$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "condition": { "type": "string", "enum": [ "new", "remanufactured", "used", "unknown" ] }, "windowDays": { "type": "integer", "minimum": 1, "maximum": 730 } } }, "MarketIntelligenceVinEconomicScope": { "type": "object", "additionalProperties": false, "required": [ "marketCountry", "currency", "condition", "windowDays", "asOf", "minimumEvidence", "freshnessPolicy", "maxCandidates", "includeInsufficientCandidates" ], "properties": { "marketCountry": { "type": "string", "pattern": "^[A-Z]{2}$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "condition": { "type": "string", "enum": [ "new", "remanufactured", "used", "unknown" ] }, "windowDays": { "type": "integer", "const": 90 }, "asOf": { "type": "string", "format": "date-time" }, "minimumEvidence": { "type": "string", "enum": [ "any", "directional", "usable", "strong" ] }, "freshnessPolicy": { "type": "string", "enum": [ "allow_stale", "refresh_if_stale", "require_fresh" ] }, "maxCandidates": { "type": "integer", "minimum": 1, "maximum": 100 }, "includeInsufficientCandidates": { "type": "boolean" } } }, "MarketIntelligencePartCluster": { "type": "object", "additionalProperties": false, "required": [ "clusterId", "clusterVersion", "canonicalLabel", "identityConfidence", "identifiers", "dimensions" ], "properties": { "clusterId": { "type": "string", "format": "uuid" }, "clusterVersion": { "type": "integer", "minimum": 1 }, "canonicalLabel": { "type": "string" }, "identityConfidence": { "type": "number", "minimum": 0, "maximum": 100 }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/MarketIntelligenceClusterIdentifier" } }, "dimensions": { "$ref": "#/components/schemas/MarketIntelligenceClusterDimensions" } } }, "MarketIntelligenceClusterIdentifier": { "type": "object", "additionalProperties": false, "required": [ "scheme", "value", "role", "confidence" ], "properties": { "scheme": { "type": "string", "enum": [ "oe", "aftermarket", "mpn", "gtin" ] }, "value": { "type": "string" }, "manufacturer": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "canonical", "current_oe", "superseded_oe", "equivalent", "aftermarket" ] }, "confidence": { "type": "number", "minimum": 0, "maximum": 100 } } }, "MarketIntelligenceClusterDimensions": { "type": "object", "additionalProperties": false, "required": [ "kTypes", "natCodes", "genArts" ], "properties": { "kTypes": { "type": "array", "uniqueItems": true, "items": { "type": "integer", "minimum": 1 } }, "natCodes": { "type": "array", "uniqueItems": true, "items": { "type": "string" } }, "genArts": { "type": "array", "uniqueItems": true, "items": { "type": "string" } } } }, "MarketIntelligenceEvidenceBundle": { "type": "object", "additionalProperties": false, "required": [ "observedSupply", "verifiedSales", "internalUsage" ], "properties": { "observedSupply": { "$ref": "#/components/schemas/MarketIntelligenceObservedSupplyEvidence" }, "verifiedSales": { "$ref": "#/components/schemas/MarketIntelligenceVerifiedSalesEvidence" }, "internalUsage": { "$ref": "#/components/schemas/MarketIntelligenceInternalUsageEvidence" } } }, "MarketIntelligenceObservedSupplyEvidence": { "type": "object", "additionalProperties": false, "required": [ "evidenceClass", "available", "activeListingCount", "distinctSellerCount", "observationDayCount", "sourceCount", "askingPrice", "latestObservedAt", "qualityScore" ], "properties": { "evidenceClass": { "type": "string", "const": "observed_supply" }, "available": { "type": "boolean" }, "activeListingCount": { "type": "integer", "minimum": 0 }, "distinctSellerCount": { "type": "integer", "minimum": 0 }, "observationDayCount": { "type": "integer", "minimum": 0 }, "sourceCount": { "type": "integer", "minimum": 0 }, "askingPrice": { "$ref": "#/components/schemas/MarketIntelligencePriceDistribution" }, "latestObservedAt": { "type": [ "string", "null" ], "format": "date-time" }, "qualityScore": { "type": "number", "minimum": 0, "maximum": 100 } } }, "MarketIntelligenceVerifiedSalesEvidence": { "type": "object", "additionalProperties": false, "required": [ "evidenceClass", "available", "verifiedSaleCount", "effectiveSampleSize", "distinctContributorCount", "observationDayCount", "matureCohortCount", "realizedPrice", "refundRate", "latestSoldAt", "qualityScore" ], "properties": { "evidenceClass": { "type": "string", "const": "verified_sale" }, "available": { "type": "boolean" }, "verifiedSaleCount": { "type": "integer", "minimum": 0 }, "effectiveSampleSize": { "type": [ "number", "null" ], "minimum": 0, "description": "Weighted effective sample size of verified sales; `null` for legacy snapshots or when not computed, never substituted with the raw sale count." }, "distinctContributorCount": { "type": "integer", "minimum": 0 }, "observationDayCount": { "type": "integer", "minimum": 0 }, "matureCohortCount": { "type": "integer", "minimum": 0 }, "realizedPrice": { "$ref": "#/components/schemas/MarketIntelligencePriceDistribution" }, "refundRate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "latestSoldAt": { "type": [ "string", "null" ], "format": "date-time" }, "qualityScore": { "type": "number", "minimum": 0, "maximum": 100 } } }, "MarketIntelligenceInternalUsageEvidence": { "type": "object", "additionalProperties": false, "description": "Aggregated values only; no VIN, plaintext identifier or account ID.", "required": [ "evidenceClass", "available", "eventCount", "weightedEventCount", "distinctAccountCount", "latestEventAt", "qualityScore" ], "properties": { "evidenceClass": { "type": "string", "const": "internal_usage" }, "available": { "type": "boolean" }, "eventCount": { "type": "integer", "minimum": 0 }, "weightedEventCount": { "type": "number", "minimum": 0 }, "distinctAccountCount": { "type": "integer", "minimum": 0 }, "latestEventAt": { "type": [ "string", "null" ], "format": "date-time" }, "qualityScore": { "type": "number", "minimum": 0, "maximum": 100 } } }, "MarketIntelligencePriceDistribution": { "type": "object", "additionalProperties": false, "required": [ "currency", "priceBasis", "sampleSize", "p10Minor", "p25Minor", "p50Minor", "p75Minor", "p90Minor" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "priceBasis": { "type": "string", "enum": [ "gross", "net", "mixed", "unknown" ] }, "sampleSize": { "type": "integer", "minimum": 0 }, "p10Minor": { "$ref": "#/components/schemas/MarketIntelligenceNullableMinorAmount" }, "p25Minor": { "$ref": "#/components/schemas/MarketIntelligenceNullableMinorAmount" }, "p50Minor": { "$ref": "#/components/schemas/MarketIntelligenceNullableMinorAmount" }, "p75Minor": { "$ref": "#/components/schemas/MarketIntelligenceNullableMinorAmount" }, "p90Minor": { "$ref": "#/components/schemas/MarketIntelligenceNullableMinorAmount" } } }, "MarketIntelligenceNullableMinorAmount": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "MarketIntelligencePriceIntelligence": { "type": "object", "additionalProperties": false, "required": [ "marketPrice", "recommendedRange" ], "properties": { "marketPrice": { "$ref": "#/components/schemas/MarketIntelligenceMarketPrice" }, "recommendedRange": { "$ref": "#/components/schemas/MarketIntelligenceRecommendedPriceRange" } } }, "MarketIntelligenceMarketPrice": { "type": "object", "additionalProperties": false, "required": [ "available", "amountMinor", "currency", "priceBasis", "basis" ], "properties": { "available": { "type": "boolean" }, "amountMinor": { "$ref": "#/components/schemas/MarketIntelligenceNullableMinorAmount" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "priceBasis": { "type": "string", "enum": [ "gross", "net", "mixed", "unknown" ] }, "basis": { "type": "string", "enum": [ "verified_sales_p50", "hierarchical_verified_sales", "unavailable" ] } } }, "MarketIntelligenceRecommendedPriceRange": { "type": "object", "additionalProperties": false, "required": [ "available", "publishable", "floorMinor", "targetMinor", "ceilingMinor", "currency", "priceBasis", "basis" ], "properties": { "available": { "type": "boolean" }, "publishable": { "type": "boolean" }, "floorMinor": { "$ref": "#/components/schemas/MarketIntelligenceNullableMinorAmount" }, "targetMinor": { "$ref": "#/components/schemas/MarketIntelligenceNullableMinorAmount" }, "ceilingMinor": { "$ref": "#/components/schemas/MarketIntelligenceNullableMinorAmount" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "priceBasis": { "type": "string", "enum": [ "gross", "net", "mixed", "unknown" ] }, "basis": { "type": "string", "enum": [ "verified_sales", "hierarchical_verified_sales", "observed_supply_only", "unavailable" ] } } }, "MarketIntelligenceStandtimeIntelligence": { "type": "object", "additionalProperties": false, "required": [ "available", "status", "expectedDays", "p50Days", "p80Days", "saleProbability", "events", "censored", "method", "confidence" ], "properties": { "available": { "type": "boolean" }, "status": { "$ref": "#/components/schemas/MarketIntelligenceIntelligenceStatus" }, "expectedDays": { "type": [ "number", "null" ], "minimum": 0 }, "p50Days": { "type": [ "number", "null" ], "minimum": 0 }, "p80Days": { "type": [ "number", "null" ], "minimum": 0 }, "saleProbability": { "$ref": "#/components/schemas/MarketIntelligenceSaleProbability" }, "events": { "type": "integer", "minimum": 0 }, "censored": { "type": "integer", "minimum": 0 }, "method": { "type": [ "string", "null" ] }, "confidence": { "type": "number", "minimum": 0, "maximum": 100 } } }, "MarketIntelligenceSaleProbability": { "type": "object", "additionalProperties": false, "required": [ "p30", "p60", "p90" ], "properties": { "p30": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "p60": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "p90": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 } } }, "MarketIntelligenceTrendIntelligence": { "type": "object", "additionalProperties": false, "required": [ "available", "status", "direction", "change30dPct", "interval30dPct", "probabilityPositive", "timeBuckets", "method", "confidence" ], "properties": { "available": { "type": "boolean" }, "status": { "$ref": "#/components/schemas/MarketIntelligenceIntelligenceStatus" }, "direction": { "type": "string", "enum": [ "up", "stable", "down", "unknown" ] }, "change30dPct": { "type": [ "number", "null" ] }, "interval30dPct": { "$ref": "#/components/schemas/MarketIntelligenceNullableInterval" }, "probabilityPositive": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "timeBuckets": { "type": "integer", "minimum": 0 }, "method": { "type": [ "string", "null" ] }, "confidence": { "type": "number", "minimum": 0, "maximum": 100 } } }, "MarketIntelligenceNullableInterval": { "type": "object", "additionalProperties": false, "required": [ "low", "high" ], "properties": { "low": { "type": [ "number", "null" ] }, "high": { "type": [ "number", "null" ] } } }, "MarketIntelligenceScores": { "type": "object", "additionalProperties": false, "required": [ "demand", "liquidity", "competition", "priceConfidence", "opportunity" ], "properties": { "demand": { "$ref": "#/components/schemas/MarketIntelligenceScore" }, "liquidity": { "$ref": "#/components/schemas/MarketIntelligenceScore" }, "competition": { "$ref": "#/components/schemas/MarketIntelligenceScore" }, "priceConfidence": { "$ref": "#/components/schemas/MarketIntelligenceScore" }, "opportunity": { "$ref": "#/components/schemas/MarketIntelligenceOpportunityScore" } } }, "MarketIntelligenceScore": { "type": "object", "additionalProperties": false, "required": [ "value", "confidence", "status", "explanation" ], "properties": { "value": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "confidence": { "type": "number", "minimum": 0, "maximum": 100 }, "status": { "$ref": "#/components/schemas/MarketIntelligenceIntelligenceStatus" }, "explanation": { "type": "string" } } }, "MarketIntelligenceOpportunityScore": { "type": "object", "additionalProperties": false, "required": [ "value", "posteriorMean", "interval", "confidence", "status", "factors", "limitations" ], "properties": { "value": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "posteriorMean": { "type": "number", "minimum": 0, "maximum": 100, "description": "Model mean; when evidence is insufficient, value remains null." }, "interval": { "$ref": "#/components/schemas/MarketIntelligenceOpportunityInterval" }, "confidence": { "type": "number", "minimum": 0, "maximum": 100 }, "status": { "$ref": "#/components/schemas/MarketIntelligenceIntelligenceStatus" }, "factors": { "type": "array", "items": { "$ref": "#/components/schemas/MarketIntelligenceScoreFactor" } }, "limitations": { "type": "array", "items": { "type": "string" } } } }, "MarketIntelligenceOpportunityInterval": { "type": "object", "additionalProperties": false, "required": [ "low", "high", "calibrated", "method" ], "properties": { "low": { "type": "number", "minimum": 0, "maximum": 100 }, "high": { "type": "number", "minimum": 0, "maximum": 100 }, "calibrated": { "type": "boolean" }, "method": { "type": "string", "description": "Versioned interval method; false means there is no empirical coverage guarantee." } } }, "MarketIntelligenceScoreFactor": { "type": "object", "additionalProperties": false, "required": [ "name", "value", "weight", "contribution", "confidence", "evidence" ], "properties": { "name": { "type": "string", "enum": [ "demand", "liquidity", "risk_adjusted_yield", "inverse_competition", "trend" ] }, "value": { "type": "number", "minimum": 0, "maximum": 100 }, "weight": { "type": "number", "minimum": 0, "maximum": 1 }, "contribution": { "type": "number", "minimum": 0, "maximum": 100 }, "confidence": { "type": "number", "minimum": 0, "maximum": 100 }, "evidence": { "type": "string" } } }, "MarketIntelligenceConfidenceSummary": { "type": "object", "additionalProperties": false, "required": [ "value", "level", "publishable", "effectiveSampleSize", "contributorCount", "observationDays", "identityConfidence", "caps", "missingEvidence" ], "properties": { "value": { "type": "number", "minimum": 0, "maximum": 100 }, "level": { "$ref": "#/components/schemas/MarketIntelligenceEvidenceLevel" }, "publishable": { "type": "boolean" }, "effectiveSampleSize": { "type": [ "number", "null" ], "minimum": 0, "description": "Weighted effective sample size of verified sales; `null` for legacy snapshots or when not computed, never substituted with the raw sale count." }, "contributorCount": { "type": "integer", "minimum": 0, "description": "Cross-account benchmarks are permitted only with at least ten independent contributors." }, "observationDays": { "type": "integer", "minimum": 0 }, "identityConfidence": { "type": "number", "minimum": 0, "maximum": 100 }, "caps": { "type": "array", "items": { "$ref": "#/components/schemas/MarketIntelligenceConfidenceCap" } }, "missingEvidence": { "type": "array", "items": { "type": "string" } } } }, "MarketIntelligenceConfidenceCap": { "type": "object", "additionalProperties": false, "required": [ "code", "maximum" ], "properties": { "code": { "type": "string" }, "maximum": { "type": "number", "minimum": 0, "maximum": 100 } } }, "MarketIntelligenceProvenance": { "type": "object", "additionalProperties": false, "required": [ "clusterVersion", "clusteringModelVersion", "intelligenceModelVersion", "scoreVersion", "snapshotId", "sourceCutoffs", "restated" ], "properties": { "clusterVersion": { "type": "integer", "minimum": 1 }, "clusteringModelVersion": { "type": "string" }, "intelligenceModelVersion": { "type": "string" }, "scoreVersion": { "type": "string" }, "snapshotId": { "type": "string", "format": "uuid" }, "sourceCutoffs": { "$ref": "#/components/schemas/MarketIntelligenceSourceCutoffs" }, "restated": { "type": "boolean" } } }, "MarketIntelligenceSourceCutoffs": { "type": "object", "additionalProperties": false, "required": [ "observedSupply", "verifiedSales", "internalUsage" ], "properties": { "observedSupply": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedSales": { "type": [ "string", "null" ], "format": "date-time" }, "internalUsage": { "type": [ "string", "null" ], "format": "date-time" } } }, "MarketIntelligenceWarning": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "MarketIntelligenceClusterHistoryResponse": { "type": "object", "additionalProperties": false, "required": [ "apiVersion", "requestId", "clusterId", "scope", "granularity", "points" ], "properties": { "apiVersion": { "type": "string", "const": "market-intelligence-v1" }, "requestId": { "type": "string", "format": "uuid" }, "clusterId": { "type": "string", "format": "uuid" }, "scope": { "$ref": "#/components/schemas/MarketIntelligenceMarketScope" }, "granularity": { "type": "string", "enum": [ "day", "week", "month" ] }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/MarketIntelligenceHistoryPoint" } } } }, "MarketIntelligenceHistoryPoint": { "type": "object", "additionalProperties": false, "required": [ "asOf", "status", "clusterVersion", "evidence", "prices", "standtime", "trend", "scores", "confidence", "provenance" ], "properties": { "asOf": { "type": "string", "format": "date-time" }, "status": { "$ref": "#/components/schemas/MarketIntelligenceIntelligenceStatus" }, "clusterVersion": { "type": "integer", "minimum": 1 }, "evidence": { "$ref": "#/components/schemas/MarketIntelligenceEvidenceBundle" }, "prices": { "$ref": "#/components/schemas/MarketIntelligencePriceIntelligence" }, "standtime": { "$ref": "#/components/schemas/MarketIntelligenceStandtimeIntelligence" }, "trend": { "$ref": "#/components/schemas/MarketIntelligenceTrendIntelligence" }, "scores": { "$ref": "#/components/schemas/MarketIntelligenceScores" }, "confidence": { "$ref": "#/components/schemas/MarketIntelligenceConfidenceSummary" }, "provenance": { "$ref": "#/components/schemas/MarketIntelligenceProvenance" } } }, "MarketIntelligenceVinEconomicIntelligenceRequest": { "type": "object", "additionalProperties": false, "required": [ "vin", "marketCountry", "currency", "condition" ], "properties": { "vin": { "type": "string", "minLength": 17, "maxLength": 17, "pattern": "^[A-HJ-NPR-Z0-9]{17}$", "description": "Processed only within the protected request context; Analytics stores an HMAC." }, "marketCountry": { "type": "string", "pattern": "^[A-Z]{2}$", "default": "DE" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "EUR" }, "condition": { "type": "string", "enum": [ "new", "remanufactured", "used", "unknown" ], "default": "used" }, "asOf": { "type": "string", "format": "date-time" }, "minimumEvidence": { "type": "string", "enum": [ "any", "directional", "usable", "strong" ], "default": "any" }, "freshnessPolicy": { "type": "string", "enum": [ "allow_stale", "refresh_if_stale", "require_fresh" ], "default": "refresh_if_stale", "description": "For VIN aggregation, only `allow_stale` may evaluate expired snapshots; the other two values exclude them as `stale_snapshot` and do not start a multi-cluster refresh." }, "maxCandidates": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "economicProfileId": { "type": "string", "maxLength": 120, "description": "Reserved for a later tenant-owned cost, returns and inventory profile; the closed pilot does not yet store or use this value in the calculation and marks it as `economic_profile_pending`." }, "includeInsufficientCandidates": { "type": "boolean", "default": true, "description": "When `false`, excluded or non-valued candidates are omitted from the public array. However, all portfolio and coverage values retain the original set of vehicle-specific part candidates bounded by `maxCandidates` as their reference population; unresolved candidates remain coverage gaps." } } }, "MarketIntelligenceVinEconomicIntelligenceResponse": { "type": "object", "additionalProperties": false, "required": [ "apiVersion", "requestId", "evaluationId", "status", "asOf", "scope", "pipeline", "portfolio", "candidates", "confidence", "provenance", "warnings" ], "properties": { "apiVersion": { "type": "string", "const": "market-intelligence-v1" }, "requestId": { "type": "string", "format": "uuid", "description": "Correlation ID; in the pilot it is identical to `evaluationId` and, for asynchronous processing, to `jobId`." }, "evaluationId": { "type": "string", "format": "uuid", "description": "Evaluation ID; in the pilot it is identical to `requestId` and the previously returned `jobId`." }, "status": { "type": "string", "enum": [ "scored", "partial", "insufficient_evidence" ], "description": "The status is `scored` only when every included vehicle-specific part candidate is assigned to a cluster and an eligible snapshot; unresolved candidates force `partial` or `insufficient_evidence`." }, "asOf": { "type": "string", "format": "date-time" }, "scope": { "$ref": "#/components/schemas/MarketIntelligenceVinEconomicScope" }, "pipeline": { "$ref": "#/components/schemas/MarketIntelligenceVinPipeline" }, "portfolio": { "$ref": "#/components/schemas/MarketIntelligenceVehiclePortfolio" }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/MarketIntelligenceClusterEconomicCandidate" } }, "confidence": { "$ref": "#/components/schemas/MarketIntelligenceVinConfidence" }, "provenance": { "$ref": "#/components/schemas/MarketIntelligenceVinProvenance" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/MarketIntelligenceWarning" } } } }, "MarketIntelligenceVinPipeline": { "type": "object", "additionalProperties": false, "required": [ "vinResolved", "vehiclePartsStatus", "partCandidateCount", "clusterResolvedCount", "intelligenceCoveredCount", "missingCategories" ], "properties": { "vinResolved": { "type": "boolean" }, "vehiclePartsStatus": { "type": "string", "enum": [ "complete", "partial", "unavailable" ] }, "partCandidateCount": { "type": "integer", "minimum": 0, "description": "Number of original vehicle-specific part candidates bounded by `maxCandidates`; the authoritative denominator for VIN coverage." }, "clusterResolvedCount": { "type": "integer", "minimum": 0, "description": "Number of those part candidates assigned to a versioned cluster; multiple candidates may contribute to the same returned cluster." }, "intelligenceCoveredCount": { "type": "integer", "minimum": 0, "description": "Number of original part candidates whose assigned cluster has an eligible intelligence snapshot." }, "missingCategories": { "type": "array", "description": "Uses the stable value `unclassified` to indicate that vehicle-specific part categories are not covered; external category identifiers are not returned.", "uniqueItems": true, "items": { "type": "string", "enum": [ "unclassified" ] } } } }, "MarketIntelligenceVehiclePortfolio": { "type": "object", "additionalProperties": false, "required": [ "revenueRange", "expectedDaysToLiquidate", "valuedClusterCount", "excludedClusterCount" ], "properties": { "revenueRange": { "$ref": "#/components/schemas/MarketIntelligenceMoneyRange" }, "expectedDaysToLiquidate": { "type": [ "number", "null" ], "minimum": 0 }, "valuedClusterCount": { "type": "integer", "minimum": 0 }, "excludedClusterCount": { "type": "integer", "minimum": 0, "description": "Number of original vehicle-specific part candidates without an eligible value contribution; includes both unresolved parts and clusters without sufficient snapshots." } } }, "MarketIntelligenceMoneyRange": { "type": "object", "additionalProperties": false, "required": [ "lowMinor", "targetMinor", "highMinor", "currency", "priceBasis" ], "properties": { "lowMinor": { "$ref": "#/components/schemas/MarketIntelligenceNullableMinorAmount" }, "targetMinor": { "$ref": "#/components/schemas/MarketIntelligenceNullableMinorAmount" }, "highMinor": { "$ref": "#/components/schemas/MarketIntelligenceNullableMinorAmount" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "priceBasis": { "type": "string", "enum": [ "gross", "net", "mixed", "unknown" ] } } }, "MarketIntelligenceClusterEconomicCandidate": { "type": "object", "additionalProperties": false, "required": [ "clusterId", "clusterVersion", "label", "status", "fitmentConfidence", "expectedQuantity", "extractionProbability", "revenueRange", "expectedStandtimeDays", "opportunityScore", "confidence", "snapshotId", "exclusionReason" ], "properties": { "clusterId": { "type": "string", "format": "uuid" }, "clusterVersion": { "type": "integer", "minimum": 1 }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ "valued", "indicative", "insufficient_evidence", "excluded" ] }, "fitmentConfidence": { "type": "number", "minimum": 0, "maximum": 100 }, "expectedQuantity": { "type": "integer", "minimum": 1 }, "extractionProbability": { "type": "number", "minimum": 0, "maximum": 1 }, "revenueRange": { "$ref": "#/components/schemas/MarketIntelligenceMoneyRange" }, "expectedStandtimeDays": { "type": [ "number", "null" ], "minimum": 0 }, "opportunityScore": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "confidence": { "type": "number", "minimum": 0, "maximum": 100 }, "snapshotId": { "type": [ "string", "null" ], "format": "uuid" }, "exclusionReason": { "type": [ "string", "null" ] } } }, "MarketIntelligenceVinConfidence": { "type": "object", "additionalProperties": false, "required": [ "value", "fitmentCoverage", "valueCoverage", "clusterIdentityCoverage", "missingEvidence" ], "properties": { "value": { "type": "number", "minimum": 0, "maximum": 100, "description": "Coverage-adjusted aggregate confidence; unresolved or non-valued part candidates contribute zero." }, "fitmentCoverage": { "type": "number", "minimum": 0, "maximum": 1, "description": "Weighted fitment confidence divided by the original vehicle-specific part candidate count; unresolved candidates contribute zero." }, "valueCoverage": { "type": "number", "minimum": 0, "maximum": 1, "description": "Share of original vehicle-specific part candidates with an eligible cluster snapshot." }, "clusterIdentityCoverage": { "type": "number", "minimum": 0, "maximum": 1, "description": "Share of original vehicle-specific part candidates assigned to a versioned part cluster." }, "missingEvidence": { "type": "array", "description": "Contains `part_cluster_identity_coverage` for unresolved candidates and `cluster_intelligence_coverage` for resolved clusters that cannot be valued.", "items": { "type": "string" } } } }, "MarketIntelligenceVinProvenance": { "type": "object", "additionalProperties": false, "required": [ "vehiclePartsSource", "vehiclePartsVersion", "intelligenceModelVersion", "clusterSnapshotIds" ], "properties": { "vehiclePartsSource": { "type": "string", "const": "tapinomahub", "description": "Public tapinomahub origin class for vehicle-specific parts determination." }, "vehiclePartsVersion": { "type": "string", "const": "vehicle-parts-v1", "description": "Version of the public tapinomahub contract for vehicle-specific parts determination." }, "intelligenceModelVersion": { "type": "string" }, "clusterSnapshotIds": { "type": "array", "uniqueItems": true, "items": { "type": "string", "format": "uuid" } } } }, "MarketIntelligenceAsyncAccepted": { "type": "object", "additionalProperties": false, "required": [ "requestId", "jobId", "status", "reason", "requestedAt", "statusUrl" ], "properties": { "requestId": { "type": "string", "format": "uuid", "description": "Request correlation ID; in the pilot it is identical to `jobId`." }, "jobId": { "type": "string", "format": "uuid", "description": "Request status ID; in the pilot it is identical to `requestId`." }, "status": { "type": "string", "enum": [ "queued", "running" ] }, "reason": { "type": "string", "enum": [ "snapshot_missing", "stale_snapshot", "vehicle_parts_pending", "refresh_pending" ] }, "requestedAt": { "type": "string", "format": "date-time" }, "estimatedReadyAt": { "type": [ "string", "null" ], "format": "date-time" }, "statusUrl": { "type": "string", "format": "uri" } } }, "ErrorResponse": { "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable, machine-readable error code. The complete list is in the “Error codes” section below the endpoints.", "example": "invalid_oe_number" }, "message": { "type": "string", "description": "Explanatory text for logs and support. Client-side branching must rely on `error` only.", "example": "oeNumber is not a valid OE part number" } } }, "VinRedirectSessionRequest": { "type": "object", "required": [ "vin", "returnUrl" ], "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`." }, "returnUrl": { "type": "string", "format": "uri", "description": "Address the user is redirected to after completion or cancellation. Line breaks, credentials and fragments are rejected; an existing query string is preserved and extended by `status`, `tapiId` and `state`." }, "state": { "type": [ "string", "null" ], "maxLength": 512, "description": "Any own context value, e.g. a cart identifier, returned unchanged to the `returnUrl`. An empty value counts as unset and does not appear in the callback." } } }, "VinRedirectSessionResponse": { "type": "object", "required": [ "redirectUrl", "expiresAt" ], "properties": { "redirectUrl": { "type": "string", "format": "uri", "description": "The public schema defines the meaning and format of `redirectUrl`." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Expiry of the session, ten minutes after creation by default and configurable between one and sixty minutes. After that the link is no longer accepted." } } }, "VinVehicleResponse": { "type": "object", "properties": { "vin": { "type": "string", "description": "The public schema defines the meaning and format of `vin`." }, "tapiId": { "type": "string", "format": "uuid", "description": "Stable vehicle reference returned after a successful lookup." }, "provider": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "Numeric selection used for this result." }, "incomplete": { "type": "boolean", "description": "The public schema defines the meaning and format of `incomplete`." }, "displayName": { "type": [ "string", "null" ], "description": "Human-readable vehicle name, where available." }, "constructionDate": { "type": [ "string", "null" ], "format": "date", "description": "The public schema defines the meaning and format of `constructionDate`." }, "kTypes": { "type": "array", "description": "Known K-Type assignments of the vehicle type.", "items": { "type": "integer" } }, "natCodes": { "type": "array", "description": "The public schema defines the meaning and format of `natCodes`.", "items": { "type": "string" } }, "platform": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `platform`." }, "engineDescription": { "type": [ "string", "null" ], "description": "Engine description at vehicle-type level, where available." }, "manufacturer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `id`." }, "name": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `name`." }, "groupId": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `groupId`." } }, "description": "The public schema defines the meaning and format of `manufacturer`." }, "mainTypeGroup": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `id`." }, "name": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `name`." } }, "description": "The public schema defines the meaning and format of `mainTypeGroup`." }, "mainType": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `id`." }, "name": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `name`." }, "detailName": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `detailName`." }, "constructionPeriod": { "type": [ "object", "null" ], "properties": { "from": { "type": [ "string", "null" ], "format": "date", "description": "The public schema defines the meaning and format of `from`." }, "until": { "type": [ "string", "null" ], "format": "date", "description": "The public schema defines the meaning and format of `until`." } }, "description": "The public schema defines the meaning and format of `constructionPeriod`." } }, "description": "The public schema defines the meaning and format of `mainType`." }, "subType": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `id`." }, "name": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `name`." }, "detailName": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `detailName`." }, "constructionPeriod": { "type": [ "object", "null" ], "properties": { "from": { "type": [ "string", "null" ], "format": "date", "description": "The public schema defines the meaning and format of `from`." }, "until": { "type": [ "string", "null" ], "format": "date", "description": "The public schema defines the meaning and format of `until`." } }, "description": "Construction period of the variant." } }, "description": "The public schema defines the meaning and format of `subType`." }, "kba": { "type": [ "object", "null" ], "properties": { "hsn": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `hsn`." }, "tsn": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `tsn`." } }, "description": "The public schema defines the meaning and format of `kba`." }, "variant": { "type": [ "object", "null" ], "properties": { "manufacturerVariantCode": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `manufacturerVariantCode`." } }, "description": "The public schema defines the meaning and format of `variant`." }, "engine": { "type": [ "object", "null" ], "properties": { "codes": { "type": "array", "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `codes`." } }, "description": "The public schema defines the meaning and format of `engine`." }, "transmission": { "type": [ "object", "null" ], "properties": { "codes": { "type": "array", "description": "Known transmission codes of the vehicle type.", "items": { "type": "string" } } }, "description": "The public schema defines the meaning and format of `transmission`." }, "technicalDetails": { "type": [ "object", "null" ], "properties": { "seats": { "type": "array", "items": { "type": "integer" } }, "doors": { "type": "array", "items": { "type": "integer" } }, "fuelTypes": { "type": "array", "items": { "type": "object", "properties": { "sign": { "type": "string" }, "name": { "type": "string" } } } }, "driveTypes": { "type": "array", "items": { "type": "object", "properties": { "sign": { "type": "string" }, "name": { "type": "string" } } } }, "structureTypes": { "type": "array", "items": { "type": "object", "properties": { "sign": { "type": "string" }, "name": { "type": "string" } } } }, "transmissionTypes": { "type": "array", "items": { "type": "object", "properties": { "sign": { "type": "string" }, "name": { "type": "string" } } } } }, "description": "The public schema defines the meaning and format of `technicalDetails`." }, "colors": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The public schema defines the meaning and format of `type`." }, "name": { "type": "string", "description": "The public schema defines the meaning and format of `name`." }, "value": { "type": "string", "description": "The public schema defines the meaning and format of `value`." }, "manufacturerCode": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `manufacturerCode`." } } }, "description": "The public schema defines the meaning and format of `colors`." }, "equipmentsCategorized": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "object", "properties": { "sign": { "type": "string", "description": "The public schema defines the meaning and format of `sign`." }, "name": { "type": "string", "description": "The public schema defines the meaning and format of `name`." } }, "description": "The public schema defines the meaning and format of `category`." }, "equipments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `id`." }, "name": { "type": "string", "description": "The public schema defines the meaning and format of `name`." }, "manufacturerCodes": { "type": "array", "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `manufacturerCodes`." }, "type": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `type`." }, "equipmentKind": { "type": [ "string", "null" ], "enum": [ "standard", "variant", "special", null ], "description": "The public schema defines the meaning and format of `equipmentKind`." }, "availability": { "type": [ "string", "null" ], "enum": [ "series", "option_free", "option_paid", "option_price_unknown", "option_unavailable", "mandatory_paid", null ], "description": "The public schema defines the meaning and format of `availability`." }, "isPackage": { "type": [ "boolean", "null" ], "description": "The public schema defines the meaning and format of `isPackage`." }, "harmonizedCodes": { "type": "array", "description": "The public schema defines the meaning and format of `harmonizedCodes`.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Harmonized code, for example `00759998`." }, "name": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `name`." } } } }, "listPrice": { "type": [ "object", "null" ], "description": "The public schema defines the meaning and format of `listPrice`.", "properties": { "net": { "type": [ "number", "null" ], "description": "Price excluding VAT." }, "gross": { "type": [ "number", "null" ], "description": "Price including VAT." }, "currency": { "type": [ "string", "null" ], "description": "ISO 4217 currency of the displayed list price; may be `null`." } } }, "availabilityPeriod": { "type": "object", "description": "Period during which this equipment was offered.", "properties": { "from": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `from`." }, "until": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `until`." } } }, "popularity": { "type": [ "number", "null" ], "description": "The public schema defines the meaning and format of `popularity`." } } }, "description": "The public schema defines the meaning and format of `equipments`." } } }, "description": "The public schema defines the meaning and format of `equipmentsCategorized`." }, "manufacturerOrderCodes": { "type": "object", "description": "The public schema defines the meaning and format of `manufacturerOrderCodes`.", "properties": { "matched": { "type": "array", "description": "The public schema defines the meaning and format of `matched`.", "items": { "type": "object", "properties": { "orderCode": { "type": "string", "description": "Manufacturer order code, for example a PR number." }, "name": { "type": [ "string", "null" ], "description": "Manufacturer designation for this code." } } } }, "unmatched": { "type": "array", "description": "The public schema defines the meaning and format of `unmatched`.", "items": { "type": "object", "properties": { "orderCode": { "type": "string", "description": "Manufacturer order code." }, "name": { "type": [ "string", "null" ], "description": "Manufacturer designation for this code." } } } } } }, "dates": { "type": "object", "description": "Dates for the specific vehicle in one place. `constructionDate` remains available separately and has the same value as `dates.production`.", "properties": { "production": { "type": [ "string", "null" ], "description": "Vehicle production date." }, "delivery": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `delivery`." }, "firstRegistration": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `firstRegistration`." }, "modelYear": { "type": [ "integer", "null" ], "description": "The public schema defines the meaning and format of `modelYear`." } } } } }, "VinPartsResponse": { "type": "object", "properties": { "vin": { "type": "string", "description": "The identification number the list was determined for, in upper case." }, "tapiId": { "type": [ "string", "null" ], "format": "uuid", "description": "Stable vehicle reference from the preceding vehicle lookup." }, "provider": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "Numeric selection used for this result." }, "matchLevel": { "type": "string", "enum": [ "vehicle_specific_best_available", "vehicle_type_candidates", "vehicle_specific_unverified" ], "description": "The public schema defines the meaning and format of `matchLevel`." }, "allCategorySigns": { "type": "array", "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `allCategorySigns`." }, "missingCategories": { "type": "array", "items": { "type": "string" }, "description": "Categories for which no result is available. A non-empty list means the parts list is incomplete." }, "parts": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `number`." }, "numberUnformatted": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `numberUnformatted`." }, "name": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `name`." }, "nameAddition": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `nameAddition`." }, "category": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `category`." }, "manufacturer": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `id`." }, "name": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `name`." } }, "description": "The public schema defines the meaning and format of `manufacturer`." }, "amount": { "type": [ "integer", "null" ], "description": "The public schema defines the meaning and format of `amount`." }, "price": { "type": [ "number", "null" ], "format": "double", "description": "The public schema defines the meaning and format of `price`." }, "tapiGenArt": { "type": "string", "pattern": "^TGA-[0-9]{6,}$", "description": "The public schema defines the meaning and format of `tapiGenArt`." }, "vdi": { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^VDI4081_[0-9]+(?:_[0-9]+)?$" }, "description": "Available confirmed full VDI 4081 codes for this part position; `[]` when no valid codes are available. The field is always present." } }, "required": [ "tapiGenArt", "vdi" ], "additionalProperties": false }, "description": "The determined OE items." } } }, "VinPartsJobResponse": { "type": "object", "required": [ "jobId", "status", "statusUrl", "vin", "provider", "createdAt" ], "properties": { "jobId": { "type": "string", "format": "uuid", "description": "The public schema defines the meaning and format of `jobId`." }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed" ], "description": "The public schema defines the meaning and format of `status`." }, "statusUrl": { "type": "string", "format": "uri", "description": "The public schema defines the meaning and format of `statusUrl`." }, "vin": { "type": "string", "description": "The public schema defines the meaning and format of `vin`." }, "provider": { "type": "integer", "enum": [ 1 ], "description": "Numeric selection used for this result." }, "retryAfterSeconds": { "type": "integer", "minimum": 1, "description": "The public schema defines the meaning and format of `retryAfterSeconds`." }, "createdAt": { "type": "string", "format": "date-time", "description": "The public schema defines the meaning and format of `createdAt`." }, "startedAt": { "type": "string", "format": "date-time", "description": "The public schema defines the meaning and format of `startedAt`." }, "completedAt": { "type": "string", "format": "date-time", "description": "The public schema defines the meaning and format of `completedAt`." }, "result": { "$ref": "#/components/schemas/VinPartsResponse" }, "error": { "$ref": "#/components/schemas/VinAsyncJobError" } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "status": { "enum": [ "queued", "running" ] } }, "required": [ "status" ] }, "then": { "required": [ "retryAfterSeconds" ], "not": { "anyOf": [ { "required": [ "result" ] }, { "required": [ "error" ] }, { "required": [ "completedAt" ] } ] } } }, { "if": { "properties": { "status": { "const": "succeeded" } }, "required": [ "status" ] }, "then": { "required": [ "result", "completedAt" ], "not": { "anyOf": [ { "required": [ "retryAfterSeconds" ] }, { "required": [ "error" ] } ] } } }, { "if": { "properties": { "status": { "const": "failed" } }, "required": [ "status" ] }, "then": { "required": [ "error", "startedAt", "completedAt" ], "not": { "anyOf": [ { "required": [ "retryAfterSeconds" ] }, { "required": [ "result" ] } ] } } } ] }, "VinCartCheckRequest": { "type": "object", "required": [ "vin", "mode", "oeNumbers" ], "properties": { "vin": { "type": "string", "minLength": 17, "maxLength": 17, "pattern": "^[A-HJ-NPR-Z0-9]{17}$", "description": "Vehicle identification number for the cart check." }, "country": { "type": "string", "default": "de", "pattern": "^[a-zA-Z]{2}(?:-[a-zA-Z]{2})?$", "description": "Optional market and regional context." }, "mode": { "type": "string", "enum": [ "type", "vehicle" ], "description": "Checks either at vehicle-type level or for the specific vehicle." }, "oeNumbers": { "type": "array", "minItems": 1, "maxItems": 30, "description": "One to 30 OE positions. Input order and duplicates are preserved in the response.", "items": { "type": "string", "minLength": 1, "maxLength": 64 } } } }, "VinCartCheckResult": { "type": "object", "required": [ "vin", "mode", "complete", "results" ], "properties": { "vin": { "type": "string", "description": "The checked identification number, normalised to upper case and trimmed." }, "mode": { "type": "string", "enum": [ "type", "vehicle" ], "description": "The public schema defines the meaning and format of `mode`." }, "complete": { "type": "boolean", "description": "Indicates whether the usable parts list was complete. When false, a negative item result is not a definitive exclusion." }, "results": { "type": "array", "items": { "type": "object", "required": [ "oe", "fits" ], "properties": { "oe": { "type": "string", "description": "The public schema defines the meaning and format of `oe`." }, "fits": { "type": "boolean", "description": "`true` when the number itself or a documented replacement number appears in the vehicle's parts list. `false` is a reliable exclusion only when `complete=true`." } } }, "description": "One entry per requested OE item, in the same order and with the same duplicates as in the request - the same number can sit on several independently actionable cart lines." } } }, "VinCartCheckJobResponse": { "type": "object", "required": [ "jobId", "status", "statusUrl", "vin", "mode", "createdAt" ], "properties": { "jobId": { "type": "string", "format": "uuid", "description": "The public schema defines the meaning and format of `jobId`." }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed" ], "description": "The public schema defines the meaning and format of `status`." }, "statusUrl": { "type": "string", "format": "uri", "description": "The public schema defines the meaning and format of `statusUrl`." }, "vin": { "type": "string", "description": "The public schema defines the meaning and format of `vin`." }, "mode": { "type": "string", "enum": [ "vehicle" ], "description": "The public schema defines the meaning and format of `mode`." }, "retryAfterSeconds": { "type": "integer", "minimum": 1, "description": "The public schema defines the meaning and format of `retryAfterSeconds`." }, "createdAt": { "type": "string", "format": "date-time", "description": "The public schema defines the meaning and format of `createdAt`." }, "startedAt": { "type": "string", "format": "date-time", "description": "The public schema defines the meaning and format of `startedAt`." }, "completedAt": { "type": "string", "format": "date-time", "description": "The public schema defines the meaning and format of `completedAt`." }, "result": { "$ref": "#/components/schemas/VinCartCheckResult" }, "error": { "$ref": "#/components/schemas/VinAsyncJobError" } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "status": { "enum": [ "queued", "running" ] } }, "required": [ "status" ] }, "then": { "required": [ "retryAfterSeconds" ], "not": { "anyOf": [ { "required": [ "result" ] }, { "required": [ "error" ] }, { "required": [ "completedAt" ] } ] } } }, { "if": { "properties": { "status": { "const": "succeeded" } }, "required": [ "status" ] }, "then": { "required": [ "result", "completedAt" ], "not": { "anyOf": [ { "required": [ "retryAfterSeconds" ] }, { "required": [ "error" ] } ] } } }, { "if": { "properties": { "status": { "const": "failed" } }, "required": [ "status" ] }, "then": { "required": [ "error", "startedAt", "completedAt" ], "not": { "anyOf": [ { "required": [ "retryAfterSeconds" ] }, { "required": [ "result" ] } ] } } } ] }, "PartOeResponse": { "type": "object", "additionalProperties": false, "required": [ "oeNumber", "normalizedOeNumber", "tapiGenArt", "vdi", "part", "fitment", "replacementChain", "references", "referenceNumbers" ], "properties": { "oeNumber": { "type": "string", "minLength": 1, "description": "The OE number as requested, with outer whitespace removed only." }, "normalizedOeNumber": { "type": "string", "minLength": 1, "description": "The confirmed normalized OE number to which the response applies." }, "tapiGenArt": { "type": [ "string", "null" ], "pattern": "^TGA-[0-9]{6,}$", "description": "Confirmed tapinomahub GenArt classification when available; otherwise `null`. The field is always present." }, "vdi": { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^VDI4081_[0-9]+(?:_[0-9]+)?$" }, "description": "Available confirmed full VDI 4081 codes; `[]` when no valid codes are available. The field is always present." }, "part": { "$ref": "#/components/schemas/PartOePart" }, "fitment": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/PartOeFitment" }, "description": "Available vehicle-type assignments with their documented criteria. An empty list makes no statement about undocumented vehicles." }, "replacementChain": { "type": "array", "items": { "$ref": "#/components/schemas/PartOeReplacement" }, "description": "Confirmed direct, directed replacement edges: `from` is replaced by `to`. An empty list means that no directed replacement is documented." }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/PartOeReferenceGroup" }, "description": "Confirmed reference and comparison numbers grouped by manufacturer. An empty list means that no such group is available." }, "referenceNumbers": { "$ref": "#/components/schemas/PartOeReferenceNumbers" } } }, "AftermarketReference": { "type": "object", "required": [ "partNumber", "normalizedPartNumber", "manufacturer" ], "properties": { "partNumber": { "type": "string", "description": "Part number in its original notation." }, "normalizedPartNumber": { "type": "string", "description": "Part number without formatting characters, where available." }, "manufacturer": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `manufacturer`." } } }, "AftermarketReferencesResponse": { "type": "object", "required": [ "oeNumber", "aftermarketReferences", "count" ], "properties": { "oeNumber": { "type": "string", "description": "The public schema defines the meaning and format of `oeNumber`." }, "aftermarketReferences": { "type": "array", "items": { "$ref": "#/components/schemas/AftermarketReference" }, "description": "The public schema defines the meaning and format of `aftermarketReferences`." }, "count": { "type": "integer", "minimum": 0, "description": "The public schema defines the meaning and format of `count`." }, "page": { "$ref": "#/components/schemas/PageInfo" } } }, "PartPriceEvaluationResponse": { "type": "object", "required": [ "oeNumber", "currency", "condition", "result", "vehicleType", "new", "used", "priceRecommendation" ], "properties": { "oeNumber": { "type": "string", "description": "The public schema defines the meaning and format of `oeNumber`." }, "condition": { "type": "string", "enum": [ "new", "used" ], "description": "The public schema defines the meaning and format of `condition`." }, "result": { "type": "string", "enum": [ "priced", "no_listings_found" ], "description": "What the evaluation produced. `priced`: usable listings were found and the ranges are evidenced. `no_listings_found`: no listing was usable; every value is then `0` and must not be read as a market price. If nothing could be measured at all, the endpoint answers with an error status instead of this field." }, "new": { "type": "object", "required": [ "min", "max", "average" ], "description": "The public schema defines the meaning and format of `new`.", "properties": { "min": { "type": "number", "format": "double" }, "max": { "type": "number", "format": "double" }, "average": { "type": "number", "format": "double" } } }, "used": { "type": "object", "required": [ "min", "max", "average" ], "description": "The public schema defines the meaning and format of `used`.", "properties": { "min": { "type": "number", "format": "double" }, "max": { "type": "number", "format": "double" }, "average": { "type": "number", "format": "double" } } }, "priceRecommendation": { "type": "object", "properties": { "min": { "type": "number", "format": "double", "description": "The public schema defines the meaning and format of `min`." }, "max": { "type": "number", "format": "double", "description": "The public schema defines the meaning and format of `max`." }, "average": { "type": "number", "format": "double", "description": "The public schema defines the meaning and format of `average`." }, "confidence": { "type": "string", "enum": [ "HIGH", "MEDIUM", "LOW" ], "description": "The public schema defines the meaning and format of `confidence`." } }, "description": "The public schema defines the meaning and format of `priceRecommendation`.", "required": [ "min", "max", "average", "confidence" ] }, "currency": { "type": "string", "description": "The public schema defines the meaning and format of `currency`." }, "vehicleType": { "type": "string", "enum": [ "car", "motorcycle" ], "description": "The public schema defines the meaning and format of `vehicleType`." } } }, "PartSeoResponse": { "type": "object", "additionalProperties": false, "required": [ "oeNumber", "marketplaceId", "language", "vehicleType", "categoryId", "product", "content", "keywords", "itemSpecifics" ], "properties": { "oeNumber": { "type": "string", "description": "The public schema defines the meaning and format of `oeNumber`." }, "marketplaceId": { "type": "string", "example": "EBAY_DE", "description": "The public schema defines the meaning and format of `marketplaceId`." }, "language": { "type": "string", "example": "de", "description": "The public schema defines the meaning and format of `language`." }, "vehicleType": { "type": "string", "enum": [ "car", "motorcycle" ], "example": "car" }, "categoryId": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `categoryId`." }, "product": { "$ref": "#/components/schemas/PartSeoProduct" }, "content": { "$ref": "#/components/schemas/PartSeoContent" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `keywords`." }, "itemSpecifics": { "type": "array", "items": { "$ref": "#/components/schemas/PartSeoItemSpecific" }, "description": "The public schema defines the meaning and format of `itemSpecifics`." }, "liveAvailability": { "$ref": "#/components/schemas/SeoLiveAvailability" } } }, "LabelBasicResponse": { "type": "object", "additionalProperties": false, "required": [ "hasPartNumber", "where" ], "properties": { "hasPartNumber": { "type": "boolean", "description": "The public schema defines the meaning and format of `hasPartNumber`." }, "where": { "type": "object", "additionalProperties": false, "required": [ "onLabel", "onPart" ], "properties": { "onLabel": { "type": "boolean", "description": "The public schema defines the meaning and format of `onLabel`." }, "onPart": { "type": "boolean", "description": "The public schema defines the meaning and format of `onPart`." } }, "description": "The public schema defines the meaning and format of `where`." } } }, "ScannerQuality": { "type": "string", "enum": [ "standard", "enhanced", "maximum" ], "default": "standard", "description": "Allowed processing tier. The choice can affect quality and response time. Billing for the tiers is governed exclusively by the contractually agreed terms." }, "LabelExtractPartNumbersRequest": { "type": "object", "required": [ "imageUrl" ], "properties": { "imageUrl": { "type": "string", "description": "The public schema defines the meaning and format of `imageUrl`.", "format": "uri" }, "quality": { "$ref": "#/components/schemas/ScannerQuality" } } }, "TranslationResponse": { "type": "object", "additionalProperties": false, "properties": { "en": { "type": "string", "example": "Brake disc", "description": "The public schema defines the meaning and format of `en`." }, "fr": { "type": "string", "example": "Disque de frein", "description": "The public schema defines the meaning and format of `fr`." }, "es": { "type": "string", "example": "Disco de freno", "description": "The public schema defines the meaning and format of `es`." }, "it": { "type": "string", "example": "Disco freno", "description": "The public schema defines the meaning and format of `it`." } }, "required": [ "en", "fr", "es", "it" ] }, "DocumentExtractionResponse": { "type": "object", "additionalProperties": false, "required": [ "documentType", "documentSubType", "source", "document", "vehicle", "financials", "repairAssessment", "parts", "labor", "paint", "notes" ], "properties": { "documentType": { "type": [ "string", "null" ], "example": "appraisal_report", "description": "The classification of the submitted document, derived solely from the document that was read; there is no controlled vocabulary behind it. `null` when the type does not follow from what is printed — nothing is guessed." }, "documentSubType": { "type": [ "string", "null" ], "example": "difference_of_values", "description": "The finer classification within `documentType`, likewise read from the document only and without a controlled vocabulary. `null` when the document states no such distinction." }, "source": { "type": "object", "additionalProperties": false, "required": [ "language" ], "properties": { "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code.", "example": "fr" } }, "description": "Information about the submitted document itself; at present the block carries only the detected document language. The key is always present, its content may be `null`." }, "document": { "$ref": "#/components/schemas/DocumentMeta" }, "vehicle": { "$ref": "#/components/schemas/Vehicle" }, "financials": { "$ref": "#/components/schemas/Financials" }, "repairAssessment": { "$ref": "#/components/schemas/RepairAssessment" }, "parts": { "type": "array", "items": { "$ref": "#/components/schemas/PartLine" }, "description": "The spare-part line items of the document. Amounts are net values in the document currency from `financials.currency` and are given as decimal numbers, not in cents; with no line items recognised the list stays empty instead of `null`." }, "labor": { "type": "array", "items": { "$ref": "#/components/schemas/WorkLine" }, "description": "The labour line items of the document with hours, rate and net amount. With no line items recognised the list stays empty instead of `null`; amounts are in the document currency from `financials.currency`." }, "paint": { "type": "array", "items": { "$ref": "#/components/schemas/WorkLine" }, "description": "The paint line items of the document, structured like the labour items (hours, rate, net amount). With no line items recognised the list stays empty instead of `null`." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Free-text passages from the document that could not be mapped to a structured field. Without such findings the list stays empty instead of `null`; explanations from the analysis never appear here." } } }, "DocumentCalculationResponse": { "type": "object", "additionalProperties": false, "required": [ "documentType", "documentSubType", "source", "document", "vehicle", "equipment", "financials", "repairAssessment", "parts", "labor", "paint", "notes" ], "properties": { "documentType": { "type": [ "string", "null" ], "example": "appraisal_report", "description": "The classification of the submitted document, derived solely from the document that was read; there is no controlled vocabulary behind it. `null` when the type does not follow from what is printed — nothing is guessed." }, "documentSubType": { "type": [ "string", "null" ], "example": "difference_of_values", "description": "The finer classification within `documentType`, likewise read from the document only and without a controlled vocabulary. `null` when the document states no such distinction." }, "source": { "type": "object", "additionalProperties": false, "required": [ "language" ], "properties": { "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code.", "example": "fr" } }, "description": "Information about the submitted document itself; at present the block carries only the detected document language. The key is always present, its content may be `null`." }, "document": { "$ref": "#/components/schemas/DocumentMeta" }, "vehicle": { "$ref": "#/components/schemas/Vehicle" }, "equipment": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleDocumentEquipment" }, "description": "The public schema defines the meaning and format of `equipment`." }, "financials": { "$ref": "#/components/schemas/Financials" }, "repairAssessment": { "$ref": "#/components/schemas/RepairAssessment" }, "parts": { "type": "array", "items": { "$ref": "#/components/schemas/PartLine" }, "description": "The spare-part line items of the document. Amounts are net values in the document currency from `financials.currency` and are given as decimal numbers, not in cents; with no line items recognised the list stays empty instead of `null`." }, "labor": { "type": "array", "items": { "$ref": "#/components/schemas/WorkLine" }, "description": "The labour line items of the document with hours, rate and net amount. With no line items recognised the list stays empty instead of `null`; amounts are in the document currency from `financials.currency`." }, "paint": { "type": "array", "items": { "$ref": "#/components/schemas/WorkLine" }, "description": "The paint line items of the document, structured like the labour items (hours, rate, net amount). With no line items recognised the list stays empty instead of `null`." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Free-text passages from the document that could not be mapped to a structured field. Without such findings the list stays empty instead of `null`; explanations from the analysis never appear here." } } }, "DocumentMeta": { "type": "object", "additionalProperties": false, "required": [ "referenceNumber", "orderNumber", "reportDate", "incidentDate", "inspectionDate" ], "properties": { "referenceNumber": { "type": [ "string", "null" ], "example": "253037600", "description": "The case or reference number named in the document, taken over exactly as printed. `null` when the document states no such number — it is never derived from other numbers." }, "orderNumber": { "type": [ "string", "null" ], "example": "AA11218464", "description": "The order number of the commissioning process as stated in the document, taken over unchanged. `null` when no order number is printed; it is never equated with `referenceNumber`." }, "reportDate": { "type": [ "string", "null" ], "format": "date", "example": "2025-10-20", "description": "The date on which the document itself was issued, normalised to ISO 8601 (YYYY-MM-DD). `null` when the document names no issue date; it is never concluded from other dates." }, "incidentDate": { "type": [ "string", "null" ], "format": "date", "example": "2025-10-08", "description": "The date of the damaging event as named in the document, normalised to ISO 8601 (YYYY-MM-DD). `null` when it is not stated explicitly — it is neither inferred nor calculated." }, "inspectionDate": { "type": [ "string", "null" ], "format": "date", "example": "2025-10-14", "description": "The date of the inspection documented in the file, normalised to ISO 8601 (YYYY-MM-DD). `null` when no dated inspection is stated; the issue date is never used as a substitute." } }, "description": "The header data of the document (references and dates). The block is always returned; individual fields not stated in the document are `null` inside it." }, "Vehicle": { "type": "object", "additionalProperties": false, "required": [ "vin", "licensePlate", "manufacturer", "model", "type", "firstRegistration", "mileageKm", "fuelType", "powerKw", "color" ], "properties": { "vin": { "type": [ "string", "null" ], "example": "WVGZZZA1ZJV013224", "description": "Identification number exactly as printed in the uploaded document; it is not inferred from other data. `null` when the document names no VIN." }, "licensePlate": { "type": [ "string", "null" ], "example": "EY-897-RS", "description": "Registration plate as stated in the document, in its spelling; `null` when it is not explicitly present there." }, "manufacturer": { "type": [ "string", "null" ], "example": "Volkswagen", "description": "Brand as stated in the document, untranslated; `null` when it is not explicitly present there." }, "model": { "type": [ "string", "null" ], "example": "T-ROC 2.0 TDI", "description": "Model or commercial name as stated in the document; `null` when it is not explicitly present there." }, "type": { "type": [ "string", "null" ], "example": "M10VWGVPR83R998", "description": "Type or manufacturer key as stated in the document, not the model name; `null` when the document names no such key." }, "firstRegistration": { "type": [ "string", "null" ], "example": "2022-01", "description": "First registration date as stated in the document, normalised to ISO 8601. Documents frequently print the first registration with month and year only; the value is then `YYYY-MM`, with a year alone `YYYY`, and `YYYY-MM-DD` only for a complete date. A missing day is not padded — an invented first of the month would look like a reading. `null` when the document does not state the first registration." }, "mileageKm": { "type": [ "number", "null" ], "example": 106756, "description": "Odometer reading as stated in the document, in kilometres, as a number without unit; it is never computed or converted and is `null` when the document does not state it." }, "fuelType": { "type": [ "string", "null" ], "example": "diesel", "description": "Fuel type as stated in the document, untranslated in the document's language; `null` when it is not stated there." }, "powerKw": { "type": [ "number", "null" ], "example": 110, "description": "Engine power in kilowatts as stated in the document; power given in horsepower is not converted, and without a statement the field stays `null`." }, "color": { "type": [ "string", "null" ], "example": "BLEU", "description": "Colour as stated in the document, untranslated in the document's language (e.g. `BLEU` in a French appraisal); `null` when it is not stated there." } }, "description": "The vehicle data named in the document. The block is always returned and its fields are `null` when the document states nothing; values are never derived from other entries." }, "Financials": { "type": "object", "additionalProperties": false, "required": [ "partsTotal", "laborTotal", "paintTotal", "repairNet", "vatAmount", "repairGross", "replacementValue", "residualValue", "differenceOfValues", "currency", "partsSubtotal", "partsAdjustments" ], "properties": { "partsTotal": { "type": [ "number", "null" ], "example": 12609.24, "description": "The parts total as printed in the document, in whole units of the currency named in `currency` (not in cents). The value is only read off and never computed from the line items; `null` when the document states none." }, "laborTotal": { "type": [ "number", "null" ], "example": 833.13, "description": "The labor total as printed in the document, in whole currency units. It is not summed from `labor` but only taken over when the document states it explicitly; otherwise `null`." }, "paintTotal": { "type": [ "number", "null" ], "example": null, "description": "The paint total as printed in the document, in whole currency units. Often `null` because many documents do not report paint separately — which does not mean no paint costs arise." }, "repairNet": { "type": [ "number", "null" ], "example": 13352.41, "description": "The net repair cost as printed in the document, in whole currency units. It is not computed from parts, labor and paint; `null` when the document does not state it." }, "vatAmount": { "type": [ "number", "null" ], "example": 2670.46, "description": "The tax amount printed in the document, in whole currency units — an amount, not a rate. It is never computed from `repairNet`; `null` when the document does not state it." }, "repairGross": { "type": [ "number", "null" ], "example": 16022.87, "description": "The gross repair cost as printed in the document, in whole currency units. Since nothing is computed, this value can be present while `repairNet` or `vatAmount` stay `null`, and the three need not add up." }, "replacementValue": { "type": [ "number", "null" ], "example": 19500, "description": "The vehicle's replacement value as stated in the document, in whole currency units; `null` when the document states none." }, "residualValue": { "type": [ "number", "null" ], "example": null, "description": "The residual value of the damaged vehicle as stated in the document, in whole currency units; `null` when the document states none — for instance because the vehicle is worth repairing." }, "differenceOfValues": { "type": [ "number", "null" ], "example": null, "description": "The difference of values as printed in the document itself, in whole currency units. It is never computed from `replacementValue` and `residualValue` but only taken over when the document names it explicitly; otherwise `null`." }, "currency": { "type": [ "string", "null" ], "example": "EUR", "description": "The ISO 4217 code the document uses for its amounts. It applies to every amount in `financials`, `parts`, `labor` and `paint`; `null` when the document states no currency, in which case the unit of the amounts is undetermined." }, "partsSubtotal": { "type": [ "number", "null" ], "example": 892.95, "description": "The parts subtotal before surcharges and deductions as printed in the document, in whole units of the currency named in `currency`. It is only read off and never computed from the line items; `null` when the document states no such intermediate figure." }, "partsAdjustments": { "type": "array", "items": { "$ref": "#/components/schemas/PartsAdjustment" }, "description": "The lines printed in the document between the parts subtotal and the parts total — deductions, surcharges, small-part flat rates, transfer costs — each with its caption, its rate and its amount. They explain the difference between the sum of the line items and `partsTotal`; without them the answer would contradict itself. With no such lines the list stays empty instead of `null`." } }, "description": "The amounts stated in the document together with the currency. Only explicitly printed values are taken over; missing totals stay `null` and are never calculated from the line items." }, "PartsAdjustment": { "type": "object", "additionalProperties": false, "required": [ "label", "rate", "amount" ], "properties": { "label": { "type": [ "string", "null" ], "example": "Deduction from RRP", "description": "The caption of the line, taken over exactly as printed (for example `Deduction from RRP`, `UPE-Aufschlag`, `Sundry Parts`). It is neither translated nor mapped onto a controlled vocabulary; `null` when the line carries no caption." }, "rate": { "type": [ "number", "null" ], "example": 10, "description": "The rate printed on the line as a number, without the percent sign and without a sign — the sign is carried by `amount`. `null` when the line names no rate, for instance with a fixed amount." }, "amount": { "type": [ "number", "null" ], "example": -89.3, "description": "The amount of this line in whole currency units, with the sign as printed in the document: a deduction is negative, a surcharge positive. It is never computed from `rate` and the subtotal; `null` when the line states no amount." } } }, "RepairAssessment": { "type": "object", "additionalProperties": false, "required": [ "economicallyRepairable", "technicallyRepairable", "immobilizationDays" ], "properties": { "economicallyRepairable": { "type": [ "boolean", "null" ], "example": true, "description": "Whether the analysed document explicitly assesses the repair as economically viable. The extraction takes over only what is explicitly stated and infers nothing; if the document says nothing, the value stays `null`." }, "technicallyRepairable": { "type": [ "boolean", "null" ], "example": true, "description": "Whether the analysed document explicitly assesses the repair as technically feasible; `null` when it makes no such statement, since only explicitly stated facts are taken over." }, "immobilizationDays": { "type": [ "number", "null" ], "example": 10, "description": "Duration of the vehicle's immobilization or downtime in days as named by the document; `null` when the document names no such duration." } }, "description": "The repair assessment stated in the document itself. The fields only reproduce what the document says and are `null` where it says nothing — no assessment of our own is made." }, "PartLine": { "type": "object", "additionalProperties": false, "required": [ "description", "partNumber", "quantity", "operation", "amountNet" ], "properties": { "description": { "type": [ "string", "null" ], "example": "JANTE AVG", "description": "The line text as printed in the document — in its original language, without translation or unification; `null` when the line carries no text." }, "partNumber": { "type": [ "string", "null" ], "example": "2GA601025D 2HH", "description": "The public schema defines the meaning and format of `partNumber`." }, "quantity": { "type": [ "number", "null" ], "example": 1, "description": "The quantity stated in the line, taken over unchanged from the document; the unit of measure is neither delivered nor converted. `null` when the line states none." }, "operation": { "type": [ "string", "null" ], "example": "E", "description": "The abbreviation the document uses for the kind of work on this line. It is taken over unchanged and not mapped to a common vocabulary, so it must be read per issuing system; `null` when the line names none." }, "amountNet": { "type": [ "number", "null" ], "example": 774.96, "description": "The net amount of this line in whole units of the currency named in `financials.currency` (not in cents), exactly as printed. It is not computed from `quantity` and a unit price; `null` when the line states no amount." } } }, "WorkLine": { "type": "object", "additionalProperties": false, "required": [ "description", "hours", "rate", "amountNet" ], "properties": { "description": { "type": [ "string", "null" ], "example": "T1", "description": "Designation or short code of the labour or paint item, taken exactly as printed in the analysed document; `null` when the line states no designation." }, "hours": { "type": [ "number", "null" ], "example": 11, "description": "Working time of the line in hours as stated in the document. It is never back-calculated from `amountNet` and `rate`: if the document does not state it explicitly it stays `null`." }, "rate": { "type": [ "number", "null" ], "example": 53.77, "description": "Hourly rate of the line as named in the document, as a decimal amount, not in cents; the line carries no currency of its own — the document names one, if at all, only once under `financials.currency`. `null` when the document states no rate." }, "amountNet": { "type": [ "number", "null" ], "example": 591.47, "description": "Net amount of the line excluding VAT, as a decimal amount, not in cents. The value is read from the document only, never computed from `hours` times `rate`; if absent there it is `null`. The line carries no currency — it appears, if the document names one, under `financials.currency`." } } }, "ClientUser": { "type": "object", "properties": { "id": { "type": "integer", "description": "The public schema defines the meaning and format of `id`." }, "name": { "type": "string", "description": "The public schema defines the meaning and format of `name`." }, "isActive": { "type": "boolean", "description": "The public schema defines the meaning and format of `isActive`." }, "defaultProviderId": { "type": "integer", "description": "The public schema defines the meaning and format of `defaultProviderId`.", "enum": [ 1, 2, 3 ] }, "parentClientId": { "type": [ "integer", "null" ], "description": "The public schema defines the meaning and format of `parentClientId`." }, "role": { "type": "string", "enum": [ "master", "user" ], "description": "The public schema defines the meaning and format of `role`." }, "balanceCents": { "type": "number", "description": "The public schema defines the meaning and format of `balanceCents`." }, "balance": { "type": "string", "example": "100.00", "description": "The public schema defines the meaning and format of `balance`." }, "currency": { "type": "string", "example": "EUR", "description": "The public schema defines the meaning and format of `currency`." }, "apiKeyCount": { "type": "integer", "description": "The public schema defines the meaning and format of `apiKeyCount`." }, "createdAt": { "type": "string", "format": "date-time", "description": "The public schema defines the meaning and format of `createdAt`." }, "planAssignments": { "type": "array", "items": { "$ref": "#/components/schemas/PlanAssignment" }, "description": "The public schema defines the meaning and format of `planAssignments`." } } }, "ClientUserCreateRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Required: trimmed display name of the new sub-user, which must not be empty. It also serves as the default label of the automatically created first API key (`-key`)." }, "defaultProviderId": { "type": "integer", "default": 1, "description": "The public schema defines the meaning and format of `defaultProviderId`.", "enum": [ 1, 2, 3 ] }, "isActive": { "type": "boolean", "default": true, "description": "`false` creates the user in a blocked state: its API key is already rejected during authentication. When omitted the user is created active." }, "applicationLabel": { "type": "string", "description": "Label of the automatically created first API key, identifying the consuming application; `-key` when omitted and `api-key` when empty." }, "rateLimits": { "type": "array", "items": { "$ref": "#/components/schemas/RateLimitInput" }, "description": "The public schema defines the meaning and format of `rateLimits`." } } }, "ClientUserUpdateRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "The public schema defines the meaning and format of `name`." }, "defaultProviderId": { "type": "integer", "description": "The public schema defines the meaning and format of `defaultProviderId`.", "enum": [ 1, 2, 3 ] }, "isActive": { "type": "boolean", "description": "The public schema defines the meaning and format of `isActive`." } } }, "ApiKeyCreateRequest": { "type": "object", "properties": { "label": { "type": "string", "description": "The public schema defines the meaning and format of `label`." } } }, "ApiKeyCreateResponse": { "type": "object", "properties": { "id": { "type": "integer", "description": "The public schema defines the meaning and format of `id`." }, "label": { "type": "string", "description": "The public schema defines the meaning and format of `label`." }, "key": { "type": "string", "description": "Raw API key; returned once only." }, "createdAt": { "type": "string", "format": "date-time", "description": "The public schema defines the meaning and format of `createdAt`." } } }, "CreditStatus": { "type": "object", "properties": { "clientId": { "type": "integer", "description": "Client the balance refers to: the authenticated client for `/client/credits`, or the sub-user queried in a usage report." }, "balanceCents": { "type": [ "number", "null" ], "description": "The public schema defines the meaning and format of `balanceCents`." }, "balance": { "type": [ "string", "null" ], "example": "100.00", "description": "The same balance as a decimal string in currency units (cents divided by 100, two decimals); null on partner terms." }, "currency": { "type": [ "string", "null" ], "example": "EUR", "description": "Currency of the balance account; `EUR` when no account exists, null on partner terms." }, "billingMode": { "type": "string", "enum": [ "own", "partner" ], "description": "`own` bills from the client own plan and balance. `partner` means the client chose a sponsor terms, so its balance stays untouched and is therefore not reported." }, "creditLimitCents": { "type": [ "number", "null" ], "description": "Overdraft allowance in cents, down to which the account may go negative; 0 without an allowance, null on partner terms. tapinoma grants the allowance." }, "availableCents": { "type": [ "number", "null" ], "description": "Balance plus overdraft allowance — the amount actually available; null on partner terms." } }, "description": "Balance of that same client at query time, read from the credit account." }, "RateLimitInput": { "type": "object", "required": [ "endpointKey", "windowSeconds", "maxRequests" ], "properties": { "apiKeyId": { "type": [ "integer", "null" ], "description": "Optional: restricts the limit to one API key. `null` applies to all of the user’s keys." }, "endpointKey": { "type": "string", "description": "Required: rate limits apply per endpoint, e.g. `vin.vehicle`. `*` is a global client limit across all endpoints." }, "windowSeconds": { "type": "integer", "example": 60, "description": "Documented period in seconds; 60 seconds apply when omitted." }, "maxRequests": { "type": "integer", "example": 120, "description": "Requests permitted per window. Once the counter is reached the API answers 429 with a `Retry-After` header equal to the window length; 60 applies when omitted." }, "isActive": { "type": "boolean", "default": true, "description": "The public schema defines the meaning and format of `isActive`." } } }, "RateLimit": { "allOf": [ { "$ref": "#/components/schemas/RateLimitInput" }, { "type": "object", "properties": { "id": { "type": "integer" }, "clientId": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } } } ] }, "Plan": { "type": "object", "properties": { "id": { "type": "integer", "description": "Platform-assigned plan id; it is used as `planId` when assigning plans." }, "code": { "type": "string", "description": "System-wide unique short key of the plan; it lets the plan be assigned as `planCode` instead of by id." }, "name": { "type": "string", "description": "Display name maintained by the operator for user interfaces and documents; assignments and billing reference the plan by `id` or `code`." }, "description": { "type": [ "string", "null" ], "description": "Operator free text about the plan's scope of service; `null` when nothing was provided at creation time." }, "isStandard": { "type": "boolean", "description": "`true` for standard plans, `false` for custom plans." }, "isActive": { "type": "boolean", "description": "Only active plans are listed, can be assigned and are taken into account during billing. `false` withdraws the plan from the offering without deleting existing assignments." }, "currency": { "type": "string", "example": "EUR", "description": "Currency in which this plan's base fee and endpoint prices are kept; `EUR` unless specified otherwise." }, "monthlyBaseCents": { "type": "number", "description": "Monthly base fee of the plan in cents, set via `monthlyBase` (euros) or `monthlyBaseCents`. It is plan master data; per-request debiting works off the endpoint prices." }, "monthlyBase": { "type": "string", "description": "The same base fee as a decimal string in currency units (cents divided by 100, two decimals)." }, "createdAt": { "type": "string", "format": "date-time", "description": "Point in time the plan was created." }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/PlanEndpoint" }, "description": "Endpoint configuration of the plan with prices, quotas and rate limits. Only the single-plan responses (create, update, replace endpoints) populate this field; the plan list omits it." } } }, "PlanEndpointInput": { "type": "object", "required": [ "endpointKey" ], "properties": { "endpointKey": { "type": "string", "example": "vin.vehicle", "description": "Endpoint the price, quota and limits apply to, e.g. `vin.vehicle`. An empty or missing value leads to `endpoint_key_required`." }, "regularPrice": { "type": "number", "description": "List price in euros deducted from credits for uncovered endpoints." }, "regularPriceCents": { "type": "number", "description": "List price directly in cents. When set, it takes precedence over the euro field `regularPrice`." }, "includedMonthlyQuantity": { "type": "integer", "default": 0, "description": "Number of calls included per calendar month before balance is debited; negative values are set to 0. From 90 percent consumption onwards the API adds a usage warning." }, "currency": { "type": "string", "default": "EUR", "description": "Currency of the endpoint price within the plan; `EUR` when omitted." }, "rateLimits": { "type": "array", "items": { "$ref": "#/components/schemas/PlanEndpointRateLimit" }, "description": "Rate limits that apply to every client on this plan for this endpoint. They are checked in addition to the user-specific limits and do not replace them." } } }, "PlanEndpoint": { "allOf": [ { "$ref": "#/components/schemas/PlanEndpointInput" }, { "type": "object", "properties": { "regularPrice": { "type": "string" } } } ] }, "PlanEndpointRateLimit": { "type": "object", "properties": { "windowSeconds": { "type": "integer", "example": 60, "description": "Documented period in seconds; 60 applies when omitted. Per plan and endpoint each period value may occur only once." }, "maxRequests": { "type": "integer", "example": 120, "description": "Requests the client may make per window on this endpoint; on reaching it the API answers 429. Values below 1 are raised to 1 and 60 applies when omitted." } } }, "UsageStatus": { "type": "object", "properties": { "clientId": { "type": "integer", "description": "The public schema defines the meaning and format of `clientId`." }, "balance": { "$ref": "#/components/schemas/CreditStatus" }, "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } }, "description": "The public schema defines the meaning and format of `period`." }, "plans": { "type": "array", "items": { "$ref": "#/components/schemas/PlanUsage" }, "description": "The public schema defines the meaning and format of `plans`." }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointUsage" }, "description": "The public schema defines the meaning and format of `endpoints`." } } }, "PlanUsage": { "type": "object", "properties": { "endpointKey": { "type": "string", "description": "Endpoint for which the client currently has a plan assigned. There is at most one active assignment per endpoint - a new assignment ends the previous one." }, "plan": { "type": "object", "description": "Short details of the plan active for this endpoint: `id`, `code` and `name`." }, "used": { "type": "integer", "description": "Consumption in the current calendar month. Only successful requests (HTTP 200 to 399) are counted; for `vin.vehicle`, `vin.parts` and `vin.cart_check` repeated lookups of the same reference count once." }, "includedMonthlyQuantity": { "type": "integer", "description": "Quantity included in the plan for this endpoint per calendar month. `0` means every call is debited from balance immediately." }, "remaining": { "type": "integer", "description": "Remaining quantity for the current month (included minus used), never negative. At `0` further calls are charged to the balance." }, "regularPriceCents": { "type": "number", "description": "The public schema defines the meaning and format of `regularPriceCents`." }, "regularPrice": { "type": "string", "description": "The same price as a decimal string in currency units (cents divided by 100, two decimals)." }, "currency": { "type": "string", "description": "Currency of the assigned plan, in which this row's price figures apply." } } }, "EndpointUsage": { "type": "object", "properties": { "endpointKey": { "type": "string", "description": "The public schema defines the meaning and format of `endpointKey`." }, "billingUnit": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `billingUnit`." }, "used": { "type": "integer", "description": "The public schema defines the meaning and format of `used`." }, "regularPriceCents": { "type": "number", "description": "The public schema defines the meaning and format of `regularPriceCents`." }, "regularPrice": { "type": "string", "description": "The public schema defines the meaning and format of `regularPrice`." }, "chargedCents": { "type": "number", "description": "The public schema defines the meaning and format of `chargedCents`." }, "charged": { "type": "string", "description": "The public schema defines the meaning and format of `charged`." }, "currency": { "type": "string", "description": "The public schema defines the meaning and format of `currency`." } } }, "PlanAssignment": { "type": "object", "properties": { "endpointKey": { "type": "string", "example": "vin.vehicle", "description": "Endpoint the plan applies to; each assignment binds exactly one plan to exactly one endpoint." }, "id": { "type": "integer", "description": "Id of the assigned plan - not the id of the assignment itself." }, "code": { "type": "string", "description": "Short key of the assigned plan, as used for `planCode`." }, "name": { "type": "string", "description": "Display name of the assigned plan." }, "description": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `description`." }, "isStandard": { "type": "boolean", "description": "Taken from the assigned plan: `true` for standard plans, `false` for individually negotiated special plans." }, "currency": { "type": "string", "example": "EUR", "description": "Currency of the assigned plan, in which `monthlyBaseCents` is also expressed." }, "monthlyBaseCents": { "type": "integer", "description": "Monthly base fee of the assigned plan in cents." } } }, "SponsorshipGrantUpsertRequest": { "type": "object", "required": [ "beneficiaryClientId", "endpointKeys" ], "properties": { "beneficiaryClientId": { "type": "integer", "format": "int64", "minimum": 1, "description": "Billing client ID of the beneficiary tapinoma workspace." }, "endpointKeys": { "type": "array", "minItems": 1, "maxItems": 50, "uniqueItems": true, "items": { "type": "string" }, "description": "Endpoints for which the sponsor provides its conditions." }, "channels": { "type": "array", "minItems": 1, "uniqueItems": true, "default": [ "hub" ], "items": { "type": "string", "enum": [ "hub" ] }, "description": "Currently limited to the trusted Hub channel." }, "startsAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Optional start; without a value, the grant applies immediately." }, "endsAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Optional exclusive end of sponsorship." }, "partnerTermsAllowed": { "type": "boolean", "description": "Releases the choice for the beneficiary to work permanently on the sponsor terms instead of only as a fallback. Without this field the existing setting stays unchanged; setting it back to false drops a choice already made." }, "beneficiaryMonthlyCapCents": { "type": [ "number", "null" ], "minimum": 0, "description": "Upper limit in cents this beneficiary draws from the sponsorship per calendar month; null means no limit. Counted net: refunded charges release the cap again. Without this field the existing setting stays unchanged." } } }, "SponsorshipParty": { "type": "object", "required": [ "clientId", "name" ], "properties": { "clientId": { "type": "integer", "format": "int64", "description": "The public schema defines the meaning and format of `clientId`." }, "name": { "type": "string", "description": "The public schema defines the meaning and format of `name`." } }, "description": "Workspace that steps in for a covered request once the beneficiary's plan and balance do not carry it; this is always the client that issued the grant with its own API key." }, "SponsorshipGrant": { "type": "object", "required": [ "id", "reference", "sponsor", "beneficiary", "endpointKeys", "channels", "startsAt", "active", "createdAt", "updatedAt" ], "properties": { "id": { "type": "integer", "format": "int64", "description": "The public schema defines the meaning and format of `id`." }, "reference": { "type": "string", "description": "The public schema defines the meaning and format of `reference`." }, "sponsor": { "$ref": "#/components/schemas/SponsorshipParty" }, "beneficiary": { "$ref": "#/components/schemas/SponsorshipParty" }, "endpointKeys": { "type": "array", "items": { "type": "string" }, "description": "Endpoints the cost coverage applies to. Only endpoints with an active list price or an active plan price are allowed; administration endpoints prefixed `client.` are excluded." }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "hub" ] }, "description": "Access channels in which the coverage takes effect. Only `hub` is supported; requests from other channels are never charged to the sponsor." }, "startsAt": { "type": "string", "format": "date-time", "description": "Start of the cost coverage; when omitted in the request, the moment the grant was issued. Before that point the beneficiary pays for its own requests." }, "endsAt": { "type": [ "string", "null" ], "format": "date-time", "description": "End of the cost coverage; `null` means open-ended. From that point on new requests are charged to the beneficiary again." }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Point in time of revocation, `null` while the grant has not been revoked. Revoking again keeps the first timestamp, re-issuing under the same reference resets it to `null`." }, "active": { "type": "boolean", "description": "Derived from four conditions: not revoked, sponsor and beneficiary active, start reached, end open or in the future. Only then can the sponsor step in — and only once the beneficiary cannot carry the request itself." }, "partnerTermsAllowed": { "type": "boolean", "description": "The sponsor has released the choice of terms." }, "partnerTermsChosen": { "type": "boolean", "description": "The beneficiary has chosen the sponsor terms." }, "partnerTermsActive": { "type": "boolean", "description": "Both apply; only then is the request billed on the sponsor terms." }, "beneficiaryMonthlyCapCents": { "type": [ "number", "null" ], "description": "Upper limit in cents per calendar month, or null without a limit." }, "createdAt": { "type": "string", "format": "date-time", "description": "Point in time the reference was first granted; later replacements of the same grant leave it unchanged." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Point in time of the last change; refreshed on every grant/replace and on every revocation." } }, "description": "State of the cost coverage after granting or revoking, including the derived `active` status and the freshly set timestamps." }, "SponsorshipGrantResponse": { "type": "object", "required": [ "sponsorshipGrant" ], "properties": { "sponsorshipGrant": { "$ref": "#/components/schemas/SponsorshipGrant" } } }, "SponsorshipGrantListResponse": { "type": "object", "required": [ "sponsorshipGrants" ], "properties": { "sponsorshipGrants": { "type": "array", "items": { "$ref": "#/components/schemas/SponsorshipGrant" }, "description": "All grants of the queried direction - issued ones under `/client/sponsorship-grants`, received ones under `/client/sponsorship-grants/received` - newest first. Revoked and expired grants remain included and are recognisable by `active`, `revokedAt` and `endsAt`." } } }, "VinImageScanResponse": { "type": "object", "additionalProperties": false, "required": [ "vin" ], "properties": { "vin": { "type": [ "string", "null" ], "minLength": 17, "maxLength": 17, "pattern": "^[A-HJ-NPR-Z0-9]{17}$", "example": "WVWZZZ1JZXW000001", "description": "The identification number visibly present in the image, normalised to upper case and stripped of spaces and hyphens. `null` when not all seventeen characters are reliably readable or more than one number remains plausible; it is never inferred or guessed." } } }, "PartSeoItemSpecific": { "type": "object", "additionalProperties": false, "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "The public schema defines the meaning and format of `name`." }, "value": { "type": "array", "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `value`." } } }, "PartSeoProduct": { "type": "object", "additionalProperties": false, "required": [ "manufacturer", "name", "nameAddition" ], "properties": { "manufacturer": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `manufacturer`." }, "name": { "type": "string", "description": "The public schema defines the meaning and format of `name`." }, "nameAddition": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `nameAddition`." } } }, "PartSeoContent": { "type": "object", "additionalProperties": false, "required": [ "title", "ebayTitle", "metaTitle", "metaDescription", "h1", "slug", "bulletPoints" ], "properties": { "title": { "type": "string", "maxLength": 80, "description": "The public schema defines the meaning and format of `title`." }, "ebayTitle": { "type": "string", "maxLength": 80, "description": "The public schema defines the meaning and format of `ebayTitle`." }, "metaTitle": { "type": "string", "maxLength": 60, "description": "The public schema defines the meaning and format of `metaTitle`." }, "metaDescription": { "type": "string", "maxLength": 160, "description": "The public schema defines the meaning and format of `metaDescription`." }, "h1": { "type": "string", "maxLength": 80, "description": "The public schema defines the meaning and format of `h1`." }, "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "The public schema defines the meaning and format of `slug`." }, "bulletPoints": { "type": "array", "maxItems": 5, "items": { "type": "string", "maxLength": 160 }, "description": "The public schema defines the meaning and format of `bulletPoints`." } } }, "PartSeoNoMatchResponse": { "type": "object", "additionalProperties": false, "required": [ "error", "message", "oeNumber", "marketplaceId", "language", "vehicleType" ], "properties": { "error": { "type": "string", "enum": [ "seo_no_exact_match" ], "description": "Fixed code for an exact match not being found. This case is not billed." }, "message": { "type": "string", "description": "Fixed English explanatory text without request-specific information." }, "oeNumber": { "type": "string", "description": "The requested OE number in normalized form (whitespace collapsed, upper-cased), so the negative hit can be assigned unambiguously." }, "marketplaceId": { "type": "string", "description": "Identifier of the requested marketplace." }, "language": { "type": "string", "description": "The public schema defines the meaning and format of `language`." }, "vehicleType": { "type": "string", "enum": [ "car", "motorcycle" ] } }, "description": "Public data object defined by this schema." }, "VdiCatalogStand": { "type": "object", "additionalProperties": false, "required": [ "catalogVersion" ], "properties": { "catalogVersion": { "type": "string", "example": "5.7.1", "description": "The public schema defines the meaning and format of `catalogVersion`." } }, "description": "Public data object defined by this schema." }, "VdiMainGroup": { "type": "object", "additionalProperties": false, "required": [ "id", "names" ], "properties": { "id": { "type": "integer", "minimum": 1, "description": "The public schema defines the meaning and format of `id`." }, "names": { "type": "object", "minProperties": 1, "additionalProperties": { "type": "string" }, "example": { "de": "Motorraum", "en": "engine" }, "description": "The public schema defines the meaning and format of `names`." } }, "description": "Public data object defined by this schema." }, "VdiCatalogEntry": { "type": "object", "additionalProperties": false, "required": [ "id", "code", "security", "idExtension", "mainGroup", "weight", "name", "nameEn", "synonyms", "legacyId", "qualityGroup", "possibleInstallationLocations", "possibleInstallationLocationsEn", "filter", "shippingGroup", "category2", "componentType" ], "properties": { "id": { "type": "integer", "minimum": 1, "example": 1001, "description": "The public schema defines the meaning and format of `id`." }, "code": { "type": "string", "pattern": "^VDI4081_[0-9]+$", "example": "VDI4081_1001", "description": "Public base code of the item. Optional OE mapping codes follow the documented schema." }, "security": { "type": [ "integer", "null" ], "enum": [ 0, 1, null ], "description": "The public schema defines the meaning and format of `security`." }, "idExtension": { "type": "string", "description": "The public schema defines the meaning and format of `idExtension`." }, "mainGroup": { "$ref": "#/components/schemas/VdiMainGroup" }, "weight": { "type": [ "number", "null" ], "description": "The public schema defines the meaning and format of `weight`." }, "name": { "type": "string", "description": "The public schema defines the meaning and format of `name`." }, "nameEn": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `nameEn`." }, "synonyms": { "type": "array", "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `synonyms`." }, "legacyId": { "type": [ "integer", "null" ], "description": "The public schema defines the meaning and format of `legacyId`." }, "qualityGroup": { "type": [ "integer", "null" ], "description": "The public schema defines the meaning and format of `qualityGroup`." }, "possibleInstallationLocations": { "type": "array", "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `possibleInstallationLocations`." }, "possibleInstallationLocationsEn": { "type": "array", "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `possibleInstallationLocationsEn`." }, "filter": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `filter`." }, "shippingGroup": { "type": [ "string", "null" ], "enum": [ "P", "S", null ], "description": "The public schema defines the meaning and format of `shippingGroup`." }, "category2": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `category2`." }, "componentType": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `componentType`." } } }, "VdiCatalogResponse": { "type": "object", "additionalProperties": false, "required": [ "stand", "count", "mainGroups", "entries" ], "properties": { "stand": { "$ref": "#/components/schemas/VdiCatalogStand" }, "count": { "type": "integer", "minimum": 1, "example": 2186, "description": "Total number of entries in the active catalog before pagination. When `limit` is omitted, this equals the length of `entries`." }, "mainGroups": { "type": "array", "items": { "$ref": "#/components/schemas/VdiMainGroup" }, "description": "The public schema defines the meaning and format of `mainGroups`." }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/VdiCatalogEntry" }, "description": "The public schema defines the meaning and format of `entries`." }, "page": { "$ref": "#/components/schemas/PageInfo" } } }, "OeNormalizationCandidate": { "type": "object", "additionalProperties": false, "required": [ "value", "rule", "manufacturers" ], "properties": { "value": { "type": "string", "description": "The public schema defines the meaning and format of `value`." }, "rule": { "type": "string", "description": "The public schema defines the meaning and format of `rule`." }, "manufacturers": { "type": "array", "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `manufacturers`." } } }, "OeNormalizationResponse": { "type": "object", "additionalProperties": false, "required": [ "version", "input", "manufacturer", "status", "valid", "reasons", "lookupKey", "normalizedOeNumber", "matchRule", "confidence", "equivalentOeNumbers", "equivalentOeNumberCount", "equivalentOeNumbersTruncated", "knownCandidates" ], "properties": { "version": { "type": "string", "example": "oe-2026-08-v4", "description": "The public schema defines the meaning and format of `version`." }, "input": { "type": "string", "example": "5Q0 919 275 BGRU", "description": "The public schema defines the meaning and format of `input`." }, "manufacturer": { "type": [ "string", "null" ], "example": "VOLKSWAGEN", "description": "The public schema defines the meaning and format of `manufacturer`." }, "status": { "type": "string", "enum": [ "matched", "unresolved", "ambiguous", "invalid" ], "description": "The public schema defines the meaning and format of `status`." }, "valid": { "type": "boolean", "description": "The public schema defines the meaning and format of `valid`." }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `reasons`." }, "lookupKey": { "type": "string", "example": "5Q0919275BGRU", "description": "The public schema defines the meaning and format of `lookupKey`." }, "normalizedOeNumber": { "type": [ "string", "null" ], "example": "5Q0919275B", "description": "The public schema defines the meaning and format of `normalizedOeNumber`." }, "matchRule": { "type": [ "string", "null" ], "example": "vag_suffix", "description": "The public schema defines the meaning and format of `matchRule`." }, "confidence": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "The public schema defines the meaning and format of `confidence`." }, "equivalentOeNumbers": { "type": "array", "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `equivalentOeNumbers`." }, "equivalentOeNumberCount": { "type": "integer", "minimum": 0, "description": "The public schema defines the meaning and format of `equivalentOeNumberCount`." }, "equivalentOeNumbersTruncated": { "type": "boolean", "description": "The public schema defines the meaning and format of `equivalentOeNumbersTruncated`." }, "knownCandidates": { "type": "array", "items": { "$ref": "#/components/schemas/OeNormalizationCandidate" }, "description": "The public schema defines the meaning and format of `knownCandidates`." } }, "description": "Public data object defined by this schema." }, "SeoLiveAvailability": { "type": "object", "additionalProperties": false, "required": [ "status", "reason", "availableAt", "retryAfterSeconds" ], "properties": { "status": { "type": "string", "enum": [ "PAUSED" ], "description": "The public schema defines the meaning and format of `status`." }, "reason": { "type": "string", "enum": [ "RATE_LIMIT_REACHED" ], "description": "The public schema defines the meaning and format of `reason`." }, "availableAt": { "type": "string", "format": "date-time", "description": "The public schema defines the meaning and format of `availableAt`." }, "retryAfterSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "The public schema defines the meaning and format of `retryAfterSeconds`." } }, "description": "Public data object defined by this schema." }, "SeoLivePausedResponse": { "type": "object", "additionalProperties": false, "required": [ "error", "message", "liveAvailability" ], "properties": { "error": { "type": "string", "enum": [ "seo_live_requests_paused" ], "description": "The public schema defines the meaning and format of `error`." }, "message": { "type": "string", "description": "The public schema defines the meaning and format of `message`." }, "liveAvailability": { "$ref": "#/components/schemas/SeoLiveAvailability" } } }, "VehicleHsnTsn": { "type": "object", "additionalProperties": false, "required": [ "hsn", "tsn" ], "properties": { "hsn": { "type": "string", "description": "The public schema defines the meaning and format of `hsn`." }, "tsn": { "type": "string", "description": "Type key number associated with the accompanying `hsn`." } } }, "VehicleColor": { "type": "object", "additionalProperties": false, "required": [ "code", "name", "type", "value" ], "properties": { "code": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `code`." }, "name": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `name`." }, "type": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `type`." }, "value": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `value`." } } }, "VehicleByTapiIdResponse": { "type": "object", "additionalProperties": false, "required": [ "tapiId", "make", "model", "type", "platform", "productionPeriod", "productionFrom", "productionTo", "engineDescription", "displacementCcm", "powerKw", "powerPs", "hsnTsn", "technicalDetails", "kTypes", "natCodes", "engineCodes", "transmissionCodes", "colors", "updatedAt" ], "properties": { "tapiId": { "type": "string", "format": "uuid", "description": "The public schema defines the meaning and format of `tapiId`." }, "make": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `make`." }, "model": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `model`." }, "type": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `type`." }, "platform": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `platform`." }, "productionPeriod": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `productionPeriod`." }, "productionFrom": { "type": [ "string", "null" ], "format": "date", "description": "The public schema defines the meaning and format of `productionFrom`." }, "productionTo": { "type": [ "string", "null" ], "format": "date", "description": "The public schema defines the meaning and format of `productionTo`." }, "engineDescription": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `engineDescription`." }, "displacementCcm": { "type": [ "integer", "null" ], "minimum": 0, "description": "The public schema defines the meaning and format of `displacementCcm`." }, "powerKw": { "type": [ "number", "null" ], "minimum": 0, "description": "The public schema defines the meaning and format of `powerKw`." }, "powerPs": { "type": [ "number", "null" ], "minimum": 0, "description": "The public schema defines the meaning and format of `powerPs`." }, "hsnTsn": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleHsnTsn" }, "description": "The public schema defines the meaning and format of `hsnTsn`." }, "technicalDetails": { "type": "object", "additionalProperties": true, "description": "The public schema defines the meaning and format of `technicalDetails`." }, "kTypes": { "type": "array", "items": { "type": "integer" }, "description": "The public schema defines the meaning and format of `kTypes`." }, "natCodes": { "type": "array", "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `natCodes`." }, "engineCodes": { "type": "array", "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `engineCodes`." }, "transmissionCodes": { "type": "array", "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `transmissionCodes`." }, "colors": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleColor" }, "description": "The public schema defines the meaning and format of `colors`." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time of the last change to the documented vehicle-type data." } } }, "PingResponse": { "type": "object", "additionalProperties": false, "required": [ "status", "service" ], "properties": { "status": { "type": "string", "enum": [ "ok" ], "example": "ok", "description": "The public schema defines the meaning and format of `status`." }, "service": { "type": "string", "example": "tapinoma hub", "description": "The public schema defines the meaning and format of `service`." } } }, "VisionTextQuality": { "type": "string", "enum": [ "notes", "prose", "expert" ], "default": "notes", "description": "Public data object defined by this schema." }, "VisionDamageReportResponse": { "type": "object", "additionalProperties": false, "required": [ "report", "format", "truncated" ], "properties": { "report": { "type": "string", "description": "The public schema defines the meaning and format of `report`.", "example": "# Schadensbeschreibung\n\n## Bauteil\n- vordere rechte Tür, angrenzender Schwellerbereich\n\n## Verformungen\n- unterer hinterer Türbereich leicht eingeknickt, kein durchgedrücktes Blech\n\n## Kratzer und Schrammen\n- mehrere horizontale Kratzer im unteren Türdrittel, mittlere Tiefe\n\n## Lack und Korrosion\n- Lackdurchschliff am hinteren unteren Türabschluss, Grundierung sichtbar\n- kein Rostansatz erkennbar\n\n## Fehlende oder beschädigte Anbauteile\n- offene Befestigungspunkte am Schweller, Abdeckung fehlt\n\n## Sonstige Auffälligkeiten\n- Schwellerbereich stark verschmutzt, Detailbeurteilung eingeschränkt\n" }, "format": { "type": "string", "description": "The public schema defines the meaning and format of `format`.", "example": "tapinoma.damage-report.v1" }, "truncated": { "type": "boolean", "description": "The public schema defines the meaning and format of `truncated`.", "example": false } } }, "VisionPartQualityCriterion": { "type": "object", "additionalProperties": false, "required": [ "key", "rating", "observation" ], "properties": { "key": { "type": "string", "enum": [ "gebrauchsspuren", "korrosion", "verformung", "kratzer", "lackzustand", "vollstaendigkeit", "verschmutzung" ], "description": "The public schema defines the meaning and format of `key`." }, "rating": { "type": "string", "enum": [ "keine", "leicht", "deutlich", "stark", "nicht_beurteilbar" ], "description": "The public schema defines the meaning and format of `rating`." }, "observation": { "type": "string", "description": "The public schema defines the meaning and format of `observation`." } } }, "VisionPartQualityResponse": { "type": "object", "additionalProperties": false, "required": [ "format", "gradable", "grade", "reason", "partCategory", "partName", "criteria", "reworkEffort", "refinishEffort", "limitations", "summary", "visualOnly" ], "properties": { "format": { "type": "string", "description": "The public schema defines the meaning and format of `format`.", "example": "tapinoma.part-quality.v1" }, "gradable": { "type": "boolean", "description": "The public schema defines the meaning and format of `gradable`.", "example": true }, "grade": { "type": [ "string", "null" ], "enum": [ "A", "B", "C", null ], "description": "The public schema defines the meaning and format of `grade`.", "example": "B" }, "reason": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `reason`." }, "partCategory": { "type": "string", "enum": [ "karosserie", "beleuchtung", "verglasung", "innenausstattung", "rad", "anbauteil", "sonstiges" ], "description": "The public schema defines the meaning and format of `partCategory`." }, "partName": { "type": "string", "description": "The public schema defines the meaning and format of `partName`.", "example": "Fahrertür" }, "criteria": { "type": "array", "items": { "$ref": "#/components/schemas/VisionPartQualityCriterion" }, "description": "The public schema defines the meaning and format of `criteria`." }, "reworkEffort": { "type": "string", "enum": [ "keine", "bis_30_min", "ueber_30_bis_60_min", "ueber_60_min", "nicht_beurteilbar" ], "description": "The public schema defines the meaning and format of `reworkEffort`." }, "refinishEffort": { "type": "string", "enum": [ "keine", "anschleifen_lackieren", "teilreparatur", "grossflaechige_reparatur", "nicht_beurteilbar" ], "description": "The public schema defines the meaning and format of `refinishEffort`." }, "limitations": { "type": "array", "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `limitations`." }, "summary": { "type": "string", "description": "The public schema defines the meaning and format of `summary`." }, "visualOnly": { "type": "boolean", "description": "The public schema defines the meaning and format of `visualOnly`.", "example": true } } }, "PageInfo": { "type": "object", "additionalProperties": false, "required": [ "limit", "offset", "returned", "hasMore" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "type": "integer", "minimum": 0 }, "returned": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" } } }, "SponsorshipBillingModeRequest": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "own", "partner" ], "description": "`own` bills first from the beneficiary own plan and balance and lets the sponsor step in only as a fallback. `partner` bills every covered request on the sponsor terms and leaves the own balance untouched." }, "sponsorClientId": { "type": "integer", "format": "int64", "minimum": 1, "description": "Required when several sponsors use the same reference for this beneficiary. Without it the endpoint then answers 409 `ambiguous_grant_reference`." } } }, "VisionPartGenerationAngle": { "type": "string", "enum": [ "front", "rear", "left", "right", "left_45", "right_45" ] }, "VisionPartGenerationRequest": { "type": "object", "additionalProperties": false, "required": [ "oeNumber" ], "properties": { "oeNumber": { "type": "string", "minLength": 1, "maxLength": 80, "example": "5G0807221S", "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._/-]{0,79}$", "description": "The public schema defines the meaning and format of `oeNumber`." }, "angles": { "type": "array", "minItems": 1, "maxItems": 6, "uniqueItems": true, "items": { "$ref": "#/components/schemas/VisionPartGenerationAngle" }, "default": [ "front", "rear", "left", "right", "left_45", "right_45" ] }, "colorCode": { "type": [ "string", "null" ], "maxLength": 40, "example": "LA7W", "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._/-]{0,39}$" }, "surfaceFinish": { "type": "string", "enum": [ "auto", "unpainted", "primed", "manufacturer_color" ], "default": "auto", "description": "The public schema defines the meaning and format of `surfaceFinish`." }, "quality": { "$ref": "#/components/schemas/ScannerQuality" }, "generateBaseModel": { "type": "boolean", "default": true }, "referenceImageUrls": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "type": "string", "format": "uri" }, "description": "The public schema defines the meaning and format of `referenceImageUrls`." }, "sourceMode": { "type": "string", "enum": [ "references_required", "references_preferred", "knowledge_only" ], "default": "references_required", "description": "The public schema defines the meaning and format of `sourceMode`." } } }, "VisionEvidenceMeasurement": { "type": "object", "additionalProperties": false, "required": [ "value", "min", "max", "confidence" ], "properties": { "value": { "type": [ "number", "null" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] }, "confidence": { "type": "string", "enum": [ "none", "limited", "moderate", "strong" ] }, "basis": { "type": "string" }, "method": { "type": "string" } } }, "VisionPartGenerationView": { "type": "object", "additionalProperties": false, "required": [ "angle", "imageUrl", "mediaType", "synthetic", "partIdentityVerified", "identifierProtectionVerified", "verificationConfidence", "sha256" ], "properties": { "angle": { "$ref": "#/components/schemas/VisionPartGenerationAngle" }, "imageUrl": { "type": "string", "format": "uri" }, "mediaType": { "type": "string", "enum": [ "image/png" ] }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "synthetic": { "type": "boolean", "enum": [ true ] }, "partIdentityVerified": { "type": "boolean", "description": "The public schema defines the meaning and format of `partIdentityVerified`." }, "identifierProtectionVerified": { "type": "boolean", "enum": [ true ] }, "verificationConfidence": { "type": "string", "enum": [ "limited", "moderate", "strong" ], "description": "The public schema defines the meaning and format of `verificationConfidence`." }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "VisionPartGenerationResult": { "type": "object", "additionalProperties": false, "required": [ "format", "oeNumber", "coverage", "basis", "synthetic", "disclosure", "finish", "part", "dimensions", "materials", "paintableSurface", "baseModel", "views", "identifierProtection", "limitations", "generatedAt" ], "properties": { "format": { "type": "string", "enum": [ "tapinoma.part-generation.v2" ] }, "oeNumber": { "type": "string" }, "coverage": { "type": "object", "additionalProperties": false, "description": "The public schema defines the meaning and format of `coverage`.", "required": [ "requestedAngles", "generatedAngles", "skippedAngles", "additionalMaterialHelps" ], "properties": { "requestedAngles": { "type": "array", "description": "The public schema defines the meaning and format of `requestedAngles`.", "items": { "$ref": "#/components/schemas/VisionPartGenerationAngle" } }, "generatedAngles": { "type": "array", "description": "The public schema defines the meaning and format of `generatedAngles`.", "items": { "$ref": "#/components/schemas/VisionPartGenerationAngle" } }, "skippedAngles": { "type": "array", "description": "The public schema defines the meaning and format of `skippedAngles`.", "items": { "type": "object", "additionalProperties": false, "required": [ "angle", "reason", "needed" ], "properties": { "angle": { "description": "The public schema defines the meaning and format of `angle`.", "allOf": [ { "$ref": "#/components/schemas/VisionPartGenerationAngle" } ] }, "reason": { "type": "string", "description": "The public schema defines the meaning and format of `reason`.", "enum": [ "no_source_shows_this_side", "generated_view_did_not_show_this_side", "generated_view_carried_unsupported_markings", "generated_view_did_not_match_the_part", "generated_view_verification_inconclusive", "view_shows_too_little_of_the_part" ] }, "needed": { "type": "string", "description": "The public schema defines the meaning and format of `needed`." } } } }, "additionalMaterialHelps": { "type": "boolean", "description": "The public schema defines the meaning and format of `additionalMaterialHelps`." } } }, "basis": { "type": "string", "enum": [ "reference_images", "knowledge" ], "description": "The public schema defines the meaning and format of `basis`." }, "synthetic": { "type": "boolean", "enum": [ true ] }, "disclosure": { "type": "string" }, "finish": { "type": "object", "additionalProperties": false, "required": [ "surfaceFinish", "colorCode", "colorAppearanceIsAuthoritative" ], "properties": { "surfaceFinish": { "type": "string" }, "colorCode": { "type": [ "string", "null" ] }, "colorAppearanceIsAuthoritative": { "type": "boolean", "enum": [ false ] } } }, "part": { "type": "object", "additionalProperties": false, "required": [ "description", "category", "bodyPanel", "confidence" ], "properties": { "description": { "type": "string" }, "category": { "type": "string" }, "bodyPanel": { "type": "boolean" }, "confidence": { "type": "string", "enum": [ "limited", "moderate", "strong" ] } } }, "dimensions": { "type": "object", "additionalProperties": false, "required": [ "unit", "width", "height", "depth" ], "properties": { "unit": { "type": "string", "enum": [ "mm" ] }, "width": { "$ref": "#/components/schemas/VisionEvidenceMeasurement" }, "height": { "$ref": "#/components/schemas/VisionEvidenceMeasurement" }, "depth": { "$ref": "#/components/schemas/VisionEvidenceMeasurement" } } }, "materials": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "confidence", "basis" ], "properties": { "name": { "type": "string" }, "confidence": { "type": "string", "enum": [ "limited", "moderate", "strong" ] }, "basis": { "type": "string" } } } }, "paintableSurface": { "$ref": "#/components/schemas/VisionPaintableSurface" }, "baseModel": { "type": "object", "additionalProperties": false, "required": [ "status", "kind", "modelUrl" ], "properties": { "status": { "type": "string", "enum": [ "not_requested", "not_generated", "generated" ] }, "kind": { "type": [ "string", "null" ] }, "format": { "type": "string" }, "modelUrl": { "type": [ "string", "null" ], "format": "uri" }, "reason": { "type": "string" }, "sha256": { "type": "string" }, "dimensionsMm": { "type": "object", "additionalProperties": false, "properties": { "width": { "type": "number" }, "height": { "type": "number" }, "depth": { "type": "number" } }, "required": [ "width", "height", "depth" ] }, "warning": { "type": "string" } } }, "views": { "type": "array", "minItems": 1, "maxItems": 6, "items": { "$ref": "#/components/schemas/VisionPartGenerationView" } }, "identifierProtection": { "type": "object", "additionalProperties": false, "required": [ "mode", "verified", "rules" ], "properties": { "mode": { "type": "string", "enum": [ "automatic" ] }, "verified": { "type": "boolean", "enum": [ true ] }, "rules": { "type": "object", "additionalProperties": false, "required": [ "mac", "imei", "vin", "serial", "machineCodes" ], "properties": { "mac": { "type": "string" }, "imei": { "type": "string" }, "vin": { "type": "string" }, "serial": { "type": "string" }, "machineCodes": { "type": "string" } } } } }, "limitations": { "type": "array", "items": { "type": "string" } }, "generatedAt": { "type": "string", "format": "date-time" } } }, "VisionPartGenerationAccepted": { "type": "object", "additionalProperties": false, "required": [ "jobId", "status", "statusUrl", "oeNumber", "createdAt", "retryAfterSeconds" ], "properties": { "jobId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued" ] }, "statusUrl": { "type": "string", "format": "uri" }, "oeNumber": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 } } }, "VisionPartGenerationJobStatus": { "type": "object", "additionalProperties": false, "required": [ "jobId", "status", "statusUrl", "oeNumber", "createdAt" ], "properties": { "jobId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed" ] }, "statusUrl": { "type": "string", "format": "uri" }, "oeNumber": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "result": { "$ref": "#/components/schemas/VisionPartGenerationResult" }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "VisionPaintableSurface": { "type": "object", "additionalProperties": false, "required": [ "value", "min", "max", "confidence", "unit", "method" ], "properties": { "value": { "type": [ "number", "null" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] }, "confidence": { "type": "string", "enum": [ "none", "limited", "moderate", "strong" ] }, "basis": { "type": "string" }, "unit": { "type": "string", "enum": [ "m2" ] }, "method": { "type": "string" } } }, "VisionCutoutCoverage": { "type": "object", "additionalProperties": false, "required": [ "areaShare", "touchesImageEdge", "cropped" ], "properties": { "areaShare": { "type": [ "number", "null" ], "description": "The public schema defines the meaning and format of `areaShare`.", "example": 0.42 }, "touchesImageEdge": { "type": [ "boolean", "null" ], "description": "The public schema defines the meaning and format of `touchesImageEdge`.", "example": false }, "cropped": { "type": "boolean", "description": "The public schema defines the meaning and format of `cropped`.", "example": false } } }, "VisionCutoutResponse": { "type": "object", "additionalProperties": false, "required": [ "format", "subject", "quality", "background", "found", "label", "imageUrl", "mediaType", "width", "height", "coverage", "sourcePixelsPreserved", "limitations" ], "properties": { "format": { "type": "string", "description": "The public schema defines the meaning and format of `format`.", "example": "tapinoma.cutout.v1" }, "subject": { "type": "string", "enum": [ "part", "vehicle" ], "description": "The public schema defines the meaning and format of `subject`." }, "quality": { "type": "string", "enum": [ "standard", "enhanced", "maximum" ], "description": "The public schema defines the meaning and format of `quality`." }, "background": { "type": "string", "enum": [ "transparent", "white" ], "description": "The public schema defines the meaning and format of `background`." }, "found": { "type": "boolean", "description": "The public schema defines the meaning and format of `found`.", "example": true }, "label": { "type": "string", "description": "The public schema defines the meaning and format of `label`.", "example": "Sandbox-Bauteil" }, "imageUrl": { "type": [ "string", "null" ], "format": "uri", "description": "The public schema defines the meaning and format of `imageUrl`.", "example": "https://assets.example.com/vision/background-removal/5bxa1000-0000-4000-8000-000000000001/cutout.png" }, "mediaType": { "type": [ "string", "null" ], "enum": [ "image/png", null ], "description": "The public schema defines the meaning and format of `mediaType`." }, "width": { "type": [ "integer", "null" ], "description": "The public schema defines the meaning and format of `width`.", "example": 1600 }, "height": { "type": [ "integer", "null" ], "description": "The public schema defines the meaning and format of `height`.", "example": 1200 }, "coverage": { "$ref": "#/components/schemas/VisionCutoutCoverage" }, "sourcePixelsPreserved": { "type": "boolean", "description": "The public schema defines the meaning and format of `sourcePixelsPreserved`.", "example": true }, "limitations": { "type": "array", "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `limitations`." } } }, "VisionElvCriterion": { "type": "object", "additionalProperties": false, "required": [ "key", "finding", "confidence", "observation", "imageIndexes" ], "properties": { "key": { "type": "string", "enum": [ "zerlegt_oder_ausgeschlachtet", "zugeschweisst_oder_ausgeschaeumt", "ausgebrannt", "wasserstand_ueber_armaturenbrett", "strukturschaden_irreversibel", "hauptaggregat_ersatz_erforderlich", "fahrwerk_lenkung_bremsen_nicht_instandsetzbar" ], "description": "The public schema defines the meaning and format of `key`." }, "finding": { "type": "string", "enum": [ "erfuellt", "nicht_erfuellt", "nicht_beurteilbar" ], "description": "The public schema defines the meaning and format of `finding`." }, "confidence": { "type": "string", "enum": [ "hoch", "mittel", "niedrig" ], "description": "The public schema defines the meaning and format of `confidence`." }, "observation": { "type": "string", "description": "The public schema defines the meaning and format of `observation`." }, "imageIndexes": { "type": "array", "items": { "type": "integer" }, "description": "The public schema defines the meaning and format of `imageIndexes`." } } }, "VisionElvEconomicAssessment": { "type": "object", "additionalProperties": false, "required": [ "basis", "repairCostRelation", "marketValueEur", "repairEstimateEur" ], "properties": { "basis": { "type": "string", "enum": [ "einsenderangaben", "bildeinschaetzung", "keine" ], "description": "The public schema defines the meaning and format of `basis`." }, "repairCostRelation": { "type": "string", "enum": [ "unter_marktwert", "nahe_marktwert", "ueber_marktwert", "nicht_beurteilbar" ], "description": "The public schema defines the meaning and format of `repairCostRelation`." }, "marketValueEur": { "type": [ "number", "null" ], "description": "The public schema defines the meaning and format of `marketValueEur`." }, "repairEstimateEur": { "type": [ "number", "null" ], "description": "The public schema defines the meaning and format of `repairEstimateEur`." } } }, "VisionElvCoverage": { "type": "object", "additionalProperties": false, "required": [ "viewsCovered", "viewsMissing" ], "properties": { "viewsCovered": { "type": "array", "items": { "type": "string", "enum": [ "front", "rear", "left", "right", "interior", "engine_bay", "underbody" ] }, "description": "The public schema defines the meaning and format of `viewsCovered`." }, "viewsMissing": { "type": "array", "items": { "type": "string", "enum": [ "front", "rear", "left", "right", "interior", "engine_bay", "underbody" ] }, "description": "The public schema defines the meaning and format of `viewsMissing`." } } }, "VisionElvClassificationResponse": { "type": "object", "additionalProperties": false, "required": [ "format", "classification", "technicallyIrreparable", "economicallyIrreparable", "criteria", "economicAssessment", "coverage", "vehicleObserved", "limitations", "summary", "visualOnly" ], "properties": { "format": { "type": "string", "description": "The public schema defines the meaning and format of `format`.", "example": "tapinoma.elv-classification.v1" }, "classification": { "type": "string", "enum": [ "kein_altfahrzeug_verdacht", "gutachten_empfohlen", "altfahrzeug" ], "description": "The public schema defines the meaning and format of `classification`.", "example": "altfahrzeug" }, "technicallyIrreparable": { "type": [ "boolean", "null" ], "description": "The public schema defines the meaning and format of `technicallyIrreparable`.", "example": true }, "economicallyIrreparable": { "type": [ "boolean", "null" ], "description": "The public schema defines the meaning and format of `economicallyIrreparable`.", "example": true }, "criteria": { "type": "array", "items": { "$ref": "#/components/schemas/VisionElvCriterion" }, "description": "The public schema defines the meaning and format of `criteria`." }, "economicAssessment": { "$ref": "#/components/schemas/VisionElvEconomicAssessment" }, "coverage": { "$ref": "#/components/schemas/VisionElvCoverage" }, "vehicleObserved": { "type": "string", "description": "The public schema defines the meaning and format of `vehicleObserved`.", "example": "Kompakt-Pkw mit ausgebranntem Motorraum" }, "limitations": { "type": "array", "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `limitations`." }, "summary": { "type": "string", "description": "The public schema defines the meaning and format of `summary`." }, "visualOnly": { "type": "boolean", "description": "The public schema defines the meaning and format of `visualOnly`.", "example": true } } }, "VisionConditionFinding": { "type": "object", "additionalProperties": false, "required": [ "component", "damageType", "severity", "observation" ], "properties": { "component": { "type": "string", "description": "The public schema defines the meaning and format of `component`.", "example": "vordere rechte Tür, unteres Drittel" }, "damageType": { "type": "string", "enum": [ "verformung", "kratzer", "lack", "korrosion", "anbauteil", "verglasung", "sonstiges" ], "description": "The public schema defines the meaning and format of `damageType`." }, "severity": { "type": "string", "enum": [ "leicht", "deutlich", "stark", "nicht_beurteilbar" ], "description": "The public schema defines the meaning and format of `severity`." }, "observation": { "type": "string", "description": "The public schema defines the meaning and format of `observation`.", "example": "horizontale Schleifspur, etwa 20 cm, mittlere Tiefe" } } }, "VisionConditionZone": { "type": "object", "additionalProperties": false, "required": [ "zone", "findings" ], "properties": { "zone": { "type": "string", "enum": [ "front", "flanke_links", "flanke_rechts", "heck", "dach", "innenraum", "motorraum", "sonstiges" ], "description": "The public schema defines the meaning and format of `zone`." }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/VisionConditionFinding" }, "description": "The public schema defines the meaning and format of `findings`." } } }, "VisionConditionReportResponse": { "type": "object", "additionalProperties": false, "required": [ "format", "gradable", "grade", "reason", "summary", "zones", "limitations", "imageCount", "visualOnly" ], "properties": { "format": { "type": "string", "description": "The public schema defines the meaning and format of `format`.", "example": "tapinoma.condition-report.v1" }, "gradable": { "type": "boolean", "description": "The public schema defines the meaning and format of `gradable`.", "example": true }, "grade": { "type": [ "string", "null" ], "enum": [ "A", "B", "C", null ], "description": "The public schema defines the meaning and format of `grade`.", "example": "B" }, "reason": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `reason`." }, "summary": { "type": "string", "description": "The public schema defines the meaning and format of `summary`." }, "zones": { "type": "array", "items": { "$ref": "#/components/schemas/VisionConditionZone" }, "description": "The public schema defines the meaning and format of `zones`." }, "limitations": { "type": "array", "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `limitations`." }, "imageCount": { "type": "integer", "description": "The public schema defines the meaning and format of `imageCount`.", "example": 6 }, "visualOnly": { "type": "boolean", "description": "The public schema defines the meaning and format of `visualOnly`.", "example": true } } }, "VehicleListingResponse": { "type": "object", "additionalProperties": false, "required": [ "format", "tapiId", "language", "title", "description", "highlights", "documentedEquipmentCount", "truncated" ], "properties": { "format": { "type": "string", "description": "Response-contract identifier. Parsers should branch on this value.", "example": "tapinoma.vehicle-listing.v1" }, "tapiId": { "type": "string", "format": "uuid", "description": "Vehicle reference for which the text was generated." }, "language": { "type": "string", "enum": [ "de", "en", "fr" ], "description": "Language of the generated text.", "example": "de" }, "title": { "type": "string", "description": "Listing headline based on documented vehicle details; at most 80 characters.", "example": "Sandbox Motors Modell A 1.5 TSI mit Klimaautomatik" }, "description": { "type": "string", "description": "Coherent description in complete sentences, based solely on documented vehicle data and containing no price, condition or value claims." }, "highlights": { "type": "array", "items": { "type": "string" }, "description": "Up to eight concise, evidenced attributes relevant to a purchase decision.", "example": [ "Klimaautomatik", "1.5 TSI 110 kW" ] }, "documentedEquipmentCount": { "type": "integer", "description": "Number of documented equipment attributes available as factual input.", "example": 1 }, "truncated": { "type": "boolean", "description": "The public schema defines the meaning and format of `truncated`.", "example": false } } }, "VehicleIntakeDocument": { "type": "object", "additionalProperties": false, "required": [ "registration", "owner", "inspection", "vehicle" ], "properties": { "registration": { "type": "object", "additionalProperties": false, "required": [ "registrationNumber", "documentNumber", "issuingAuthority", "issuedDate" ], "properties": { "registrationNumber": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `registrationNumber`." }, "documentNumber": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `documentNumber`." }, "issuingAuthority": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `issuingAuthority`." }, "issuedDate": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `issuedDate`." } } }, "owner": { "type": [ "object", "null" ], "description": "The public schema defines the meaning and format of `owner`.", "properties": { "nameOrCompany": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `nameOrCompany`." }, "givenNames": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `givenNames`." }, "address": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `address`." } } }, "inspection": { "type": [ "object", "null" ], "description": "The public schema defines the meaning and format of `inspection`.", "properties": { "nextInspection": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `nextInspection`." }, "lastInspectionDate": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `lastInspectionDate`." }, "inspectionPlace": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `inspectionPlace`." } } }, "vehicle": { "type": "object", "additionalProperties": false, "required": [ "vin", "hsn", "tsn", "brand", "commercialName" ], "properties": { "vin": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `vin`." }, "hsn": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `hsn`." }, "tsn": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `tsn`." }, "brand": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `brand`." }, "modelCode": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `modelCode`." }, "commercialName": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `commercialName`." }, "vehicleClass": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `vehicleClass`." }, "bodyType": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `bodyType`." }, "fuel": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `fuel`." }, "displacementCc": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `displacementCc`." }, "powerKw": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `powerKw`." }, "co2GPerKm": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `co2GPerKm`." }, "emissionsClass": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `emissionsClass`." }, "permissibleTotalMassF1": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `permissibleTotalMassF1`." }, "permissibleTotalMassF2": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `permissibleTotalMassF2`." }, "unladenMassKg": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `unladenMassKg`." }, "axleLoads": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `axleLoads`." }, "allowedTrailerMassBraked": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `allowedTrailerMassBraked`." }, "allowedTrailerMassUnbraked": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `allowedTrailerMassUnbraked`." }, "seatsTotal": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `seatsTotal`." }, "tireSizes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `tireSizes`." } } } } }, "VehicleIntakeComponents": { "type": "object", "additionalProperties": false, "required": [ "registrationDocument", "vehicle", "conditionReport" ], "properties": { "registrationDocument": { "type": "string", "enum": [ "delivered" ], "description": "The public schema defines the meaning and format of `registrationDocument`." }, "vehicle": { "type": "string", "enum": [ "delivered", "vin_not_readable", "unavailable" ], "description": "The public schema defines the meaning and format of `vehicle`." }, "conditionReport": { "type": "string", "enum": [ "delivered", "failed", "not_requested" ], "description": "The public schema defines the meaning and format of `conditionReport`." } } }, "VehicleIntakeResponse": { "type": "object", "additionalProperties": false, "required": [ "format", "registrationDocument", "vin", "provider", "tapiId", "vehicle", "conditionReport", "components", "complete" ], "properties": { "format": { "type": "string", "description": "The public schema defines the meaning and format of `format`.", "example": "tapinoma.vehicle-intake.v1" }, "registrationDocument": { "$ref": "#/components/schemas/VehicleIntakeDocument" }, "vin": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `vin`.", "example": "TAPSANDBX00000001" }, "provider": { "type": "integer", "description": "Numeric selection used for this result.", "example": 2 }, "tapiId": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `tapiId`." }, "vehicle": { "type": [ "object", "null" ], "description": "The public schema defines the meaning and format of `vehicle`." }, "conditionReport": { "type": [ "object", "null" ], "description": "The public schema defines the meaning and format of `conditionReport`." }, "components": { "$ref": "#/components/schemas/VehicleIntakeComponents" }, "complete": { "type": "boolean", "description": "The public schema defines the meaning and format of `complete`.", "example": true } } }, "PartnerWorkspaceResponse": { "type": "object", "additionalProperties": false, "required": [ "workspace", "apiKey", "allowlist", "sponsorshipGrant" ], "properties": { "workspace": { "type": "object", "description": "Created workspace in the same structure as a sub-user returned by `POST /client/users`, extended with `externalReference`.", "properties": { "id": { "type": "integer", "description": "Unique workspace ID.", "example": 4711 }, "name": { "type": "string", "description": "Workspace display name.", "example": "Autohaus Nord GmbH" }, "externalReference": { "type": "string", "description": "Integrator-defined reference, unique within the master client.", "example": "dms-kunde-4711" } } }, "apiKey": { "type": "object", "additionalProperties": false, "required": [ "id", "label", "key", "createdAt" ], "properties": { "id": { "type": "integer", "description": "ID of the generated API key.", "example": 9001 }, "label": { "type": "string", "description": "API-key label.", "example": "Autohaus Nord GmbH-key" }, "key": { "type": "string", "description": "Raw API key; returned once only.", "example": "tap_sandboxsandboxsandboxsandboxsandboxsandboxsandboxsandbox0000" }, "createdAt": { "type": "string", "description": "Creation timestamp.", "example": "2026-01-01T00:00:00+00:00" } } }, "allowlist": { "type": "array", "items": { "type": "string" }, "description": "Endpoints to which the workspace is restricted.", "example": [ "vehicles.intake", "vehicles.listing", "vision.condition_report" ] }, "sponsorshipGrant": { "type": [ "object", "null" ], "description": "Sponsorship grant created by the caller for this workspace in the same request, or `null` if none was requested.", "properties": { "id": { "type": "integer", "description": "Grant ID." }, "reference": { "type": "string", "description": "Public sponsorship-grant reference." }, "beneficiaryClientId": { "type": "integer", "description": "ID of the beneficiary workspace." }, "endpointKeys": { "type": "array", "items": { "type": "string" }, "description": "Endpoints covered by the sponsorship grant." }, "channels": { "type": "array", "items": { "type": "string" }, "description": "Channels covered by the sponsorship grant." } } } } }, "RecallVehicleMatchResponse": { "type": "object", "additionalProperties": false, "required": [ "vin", "measures", "measureCount", "registers", "notice" ], "properties": { "vin": { "type": "string", "description": "The public schema defines the meaning and format of `vin`." }, "measures": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "reference", "register", "publishedAt", "manufacturer", "tradeNames", "buildPeriod", "stopDrive", "component", "defect", "remedy", "match" ], "properties": { "reference": { "type": "string", "description": "The public schema defines the meaning and format of `reference`." }, "register": { "type": "string", "enum": [ "kba", "eu_safety_gate", "nhtsa" ], "description": "The public schema defines the meaning and format of `register`." }, "publishedAt": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `publishedAt`." }, "manufacturer": { "type": "string", "description": "The public schema defines the meaning and format of `manufacturer`." }, "tradeNames": { "type": "array", "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `tradeNames`." }, "buildPeriod": { "type": "object", "additionalProperties": false, "required": [ "from", "until" ], "properties": { "from": { "type": [ "string", "null" ] }, "until": { "type": [ "string", "null" ] } }, "description": "The public schema defines the meaning and format of `buildPeriod`." }, "stopDrive": { "type": "boolean", "description": "The public schema defines the meaning and format of `stopDrive`." }, "component": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `component`." }, "defect": { "type": "object", "additionalProperties": false, "required": [ "de", "en", "fr" ], "properties": { "de": { "type": "string" }, "en": { "type": [ "string", "null" ] }, "fr": { "type": [ "string", "null" ] } }, "description": "The public schema defines the meaning and format of `defect`." }, "remedy": { "type": "object", "additionalProperties": false, "required": [ "de", "en", "fr" ], "properties": { "de": { "type": [ "string", "null" ] }, "en": { "type": [ "string", "null" ] }, "fr": { "type": [ "string", "null" ] } }, "description": "The public schema defines the meaning and format of `remedy`." }, "match": { "type": "object", "additionalProperties": false, "required": [ "confidence", "matchedOn" ], "properties": { "confidence": { "type": "string", "enum": [ "strong", "medium", "weak" ] }, "matchedOn": { "type": "array", "items": { "type": "string", "enum": [ "manufacturer", "model", "constructionPeriod" ] } } }, "description": "The public schema defines the meaning and format of `match`." } } }, "description": "The public schema defines the meaning and format of `measures`." }, "measureCount": { "type": "integer", "description": "The public schema defines the meaning and format of `measureCount`." }, "registers": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "register", "dataStand", "measureCount" ], "properties": { "register": { "type": "string", "enum": [ "kba", "eu_safety_gate", "nhtsa" ] }, "dataStand": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `dataStand`." }, "measureCount": { "type": [ "integer", "null" ], "description": "The public schema defines the meaning and format of `measureCount`." } } }, "description": "The public schema defines the meaning and format of `registers`." }, "notice": { "type": "object", "additionalProperties": false, "required": [ "de", "en", "fr" ], "properties": { "de": { "type": "string" }, "en": { "type": "string" }, "fr": { "type": "string" } }, "description": "The public schema defines the meaning and format of `notice`." } } }, "RecallPartsMatchRequest": { "type": "object", "additionalProperties": false, "required": [ "positions" ], "properties": { "positions": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "properties": { "oeNumber": { "type": "string", "description": "Submitted OE number for the position." }, "reference": { "type": "string", "description": "Caller-defined position reference of up to 200 characters, returned unchanged.", "maxLength": 200 }, "vehicle": { "type": "object", "additionalProperties": false, "properties": { "make": { "type": "string" }, "model": { "type": "string" }, "productionFrom": { "type": "integer" }, "productionTo": { "type": "integer" } } } } }, "description": "Positions to match; the response preserves their order." } } }, "RecallPartsMatchResponse": { "type": "object", "additionalProperties": false, "required": [ "positions", "positionCount", "resolvedCount", "registers", "notice" ], "properties": { "positions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "oeNumber", "normalizedOeNumber", "reference", "status", "unresolvedReason", "measures", "measureCount" ], "properties": { "oeNumber": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `oeNumber`." }, "normalizedOeNumber": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `normalizedOeNumber`." }, "reference": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `reference`." }, "status": { "type": "string", "enum": [ "matched", "no_measures", "unresolved" ], "description": "The public schema defines the meaning and format of `status`." }, "unresolvedReason": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `unresolvedReason`." }, "measures": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "reference", "register", "publishedAt", "manufacturer", "tradeNames", "buildPeriod", "stopDrive", "component", "defect", "remedy", "match" ], "properties": { "reference": { "type": "string", "description": "The public schema defines the meaning and format of `reference`." }, "register": { "type": "string", "enum": [ "kba", "eu_safety_gate", "nhtsa" ], "description": "The public schema defines the meaning and format of `register`." }, "publishedAt": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `publishedAt`." }, "manufacturer": { "type": "string", "description": "The public schema defines the meaning and format of `manufacturer`." }, "tradeNames": { "type": "array", "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `tradeNames`." }, "buildPeriod": { "type": "object", "additionalProperties": false, "required": [ "from", "until" ], "properties": { "from": { "type": [ "string", "null" ] }, "until": { "type": [ "string", "null" ] } }, "description": "The public schema defines the meaning and format of `buildPeriod`." }, "stopDrive": { "type": "boolean", "description": "The public schema defines the meaning and format of `stopDrive`." }, "component": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `component`." }, "defect": { "type": "object", "additionalProperties": false, "required": [ "de", "en", "fr" ], "properties": { "de": { "type": "string" }, "en": { "type": [ "string", "null" ] }, "fr": { "type": [ "string", "null" ] } }, "description": "The public schema defines the meaning and format of `defect`." }, "remedy": { "type": "object", "additionalProperties": false, "required": [ "de", "en", "fr" ], "properties": { "de": { "type": [ "string", "null" ] }, "en": { "type": [ "string", "null" ] }, "fr": { "type": [ "string", "null" ] } }, "description": "The public schema defines the meaning and format of `remedy`." }, "match": { "type": "object", "additionalProperties": false, "required": [ "confidence", "matchedOn" ], "properties": { "confidence": { "type": "string", "enum": [ "strong", "medium", "weak" ] }, "matchedOn": { "type": "array", "items": { "type": "string", "enum": [ "manufacturer", "model", "constructionPeriod" ] } } }, "description": "The public schema defines the meaning and format of `match`." } } } }, "measureCount": { "type": "integer" } } }, "description": "The public schema defines the meaning and format of `positions`." }, "positionCount": { "type": "integer", "description": "The public schema defines the meaning and format of `positionCount`." }, "resolvedCount": { "type": "integer", "description": "The public schema defines the meaning and format of `resolvedCount`." }, "registers": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "register", "dataStand", "measureCount" ], "properties": { "register": { "type": "string", "enum": [ "kba", "eu_safety_gate", "nhtsa" ] }, "dataStand": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `dataStand`." }, "measureCount": { "type": [ "integer", "null" ], "description": "The public schema defines the meaning and format of `measureCount`." } } }, "description": "The public schema defines the meaning and format of `registers`." }, "notice": { "type": "object", "additionalProperties": false, "required": [ "de", "en", "fr" ], "properties": { "de": { "type": "string" }, "en": { "type": "string" }, "fr": { "type": "string" } }, "description": "The public schema defines the meaning and format of `notice`." } } }, "VinEconomicEvaluationResponse": { "type": "object", "additionalProperties": false, "required": [ "vin", "provider", "matchLevel", "currency", "condition", "vehicleType", "assumptions", "coverage", "revenuePotential", "purchaseRecommendation", "parts" ], "properties": { "vin": { "type": "string", "example": "TAPSANDBX00000001", "description": "The public schema defines the meaning and format of `vin`." }, "tapiId": { "type": "string", "format": "uuid", "example": "5b0a1000-0000-4000-8000-000000000001", "description": "The public schema defines the meaning and format of `tapiId`." }, "provider": { "type": "integer", "enum": [ 1 ], "description": "Numeric selection used for this result." }, "matchLevel": { "type": "string", "enum": [ "vehicle_specific_best_available" ], "description": "The public schema defines the meaning and format of `matchLevel`." }, "currency": { "type": "string", "enum": [ "EUR" ], "description": "The public schema defines the meaning and format of `currency`." }, "condition": { "type": "string", "enum": [ "used", "new" ], "description": "The public schema defines the meaning and format of `condition`." }, "vehicleType": { "type": "string", "enum": [ "car", "motorcycle" ], "description": "The public schema defines the meaning and format of `vehicleType`." }, "assumptions": { "type": "object", "additionalProperties": false, "required": [ "maxPricedParts", "recoveryRate", "costPerPartEur", "priceBasis" ], "properties": { "maxPricedParts": { "type": "integer", "minimum": 1, "maximum": 100, "example": 100, "description": "The public schema defines the meaning and format of `maxPricedParts`." }, "recoveryRate": { "type": "number", "minimum": 0.05, "maximum": 1, "example": 0.5, "description": "The public schema defines the meaning and format of `recoveryRate`." }, "costPerPartEur": { "type": "number", "minimum": 0, "example": 0, "description": "The public schema defines the meaning and format of `costPerPartEur`." }, "priceBasis": { "type": "string", "enum": [ "min" ], "description": "The public schema defines the meaning and format of `priceBasis`." } }, "description": "The public schema defines the meaning and format of `assumptions`." }, "coverage": { "type": "object", "additionalProperties": false, "required": [ "totalParts", "excludedIrrelevant", "relevantParts", "selectedParts", "pricedParts", "unpricedParts" ], "properties": { "totalParts": { "type": "integer", "minimum": 0, "example": 2, "description": "The public schema defines the meaning and format of `totalParts`." }, "excludedIrrelevant": { "type": "integer", "minimum": 0, "example": 0, "description": "The public schema defines the meaning and format of `excludedIrrelevant`." }, "relevantParts": { "type": "integer", "minimum": 0, "example": 2, "description": "The public schema defines the meaning and format of `relevantParts`." }, "selectedParts": { "type": "integer", "minimum": 0, "example": 2, "description": "The public schema defines the meaning and format of `selectedParts`." }, "pricedParts": { "type": "integer", "minimum": 0, "example": 2, "description": "The public schema defines the meaning and format of `pricedParts`." }, "unpricedParts": { "type": "integer", "minimum": 0, "example": 0, "description": "The public schema defines the meaning and format of `unpricedParts`." } }, "description": "The public schema defines the meaning and format of `coverage`." }, "revenuePotential": { "type": "object", "additionalProperties": false, "required": [ "min", "average", "max" ], "properties": { "min": { "type": "number", "minimum": 0, "example": 120, "description": "The public schema defines the meaning and format of `min`." }, "average": { "type": "number", "minimum": 0, "example": 190.5, "description": "The public schema defines the meaning and format of `average`." }, "max": { "type": "number", "minimum": 0, "example": 293, "description": "The public schema defines the meaning and format of `max`." } }, "description": "The public schema defines the meaning and format of `revenuePotential`." }, "purchaseRecommendation": { "type": "object", "additionalProperties": false, "required": [ "goodPurchasePriceEur" ], "properties": { "goodPurchasePriceEur": { "type": "number", "minimum": 0, "example": 60, "description": "The public schema defines the meaning and format of `goodPurchasePriceEur`." } }, "description": "The public schema defines the meaning and format of `purchaseRecommendation`." }, "parts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "rank", "number", "amount", "pricing" ], "properties": { "rank": { "type": "integer", "minimum": 1, "example": 1, "description": "The public schema defines the meaning and format of `rank`." }, "number": { "type": "string", "example": "SBX0001A", "description": "The public schema defines the meaning and format of `number`." }, "name": { "type": [ "string", "null" ], "example": "Sandbox Stoßfänger vorn", "description": "The public schema defines the meaning and format of `name`." }, "category": { "type": [ "string", "null" ], "example": "ST", "description": "The public schema defines the meaning and format of `category`." }, "amount": { "type": "integer", "minimum": 1, "example": 1, "description": "The public schema defines the meaning and format of `amount`." }, "pricing": { "type": "object", "additionalProperties": false, "required": [], "properties": { "min": { "type": "number", "minimum": 0, "example": 89, "description": "The public schema defines the meaning and format of `min`." }, "average": { "type": "number", "minimum": 0, "example": 142.5, "description": "The public schema defines the meaning and format of `average`." }, "max": { "type": "number", "minimum": 0, "example": 219, "description": "The public schema defines the meaning and format of `max`." }, "confidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ], "description": "The public schema defines the meaning and format of `confidence`." }, "evaluatedAt": { "type": "string", "format": "date-time", "example": "2026-01-01T00:00:00+00:00", "description": "The public schema defines the meaning and format of `evaluatedAt`." } }, "description": "The public schema defines the meaning and format of `pricing`." }, "revenuePotential": { "type": "object", "additionalProperties": false, "required": [ "min", "average", "max" ], "properties": { "min": { "type": "number", "minimum": 0, "example": 120 }, "average": { "type": "number", "minimum": 0, "example": 190.5 }, "max": { "type": "number", "minimum": 0, "example": 293 } }, "description": "The public schema defines the meaning and format of `revenuePotential`." } } }, "description": "The public schema defines the meaning and format of `parts`." }, "warnings": { "type": "array", "items": { "type": "string", "enum": [ "live_pricing_paused", "live_pricing_unavailable" ] }, "description": "The public schema defines the meaning and format of `warnings`." }, "liveAvailability": { "$ref": "#/components/schemas/SeoLiveAvailability" } } }, "VinEconomicEvaluationJobResponse": { "type": "object", "required": [ "jobId", "status", "statusUrl", "vin", "provider", "createdAt" ], "properties": { "jobId": { "type": "string", "format": "uuid", "example": "6955b900-0400-4548-9632-06e2f302e3d7", "description": "The public schema defines the meaning and format of `jobId`." }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed" ], "description": "The public schema defines the meaning and format of `status`." }, "statusUrl": { "type": "string", "format": "uri", "example": "https://api.tapinomahub.com/vin/economic-evaluation/jobs/6955b900-0400-4548-9632-06e2f302e3d7", "description": "The public schema defines the meaning and format of `statusUrl`." }, "vin": { "type": "string", "example": "TAPSANDBX00000001", "description": "The public schema defines the meaning and format of `vin`." }, "provider": { "type": "integer", "enum": [ 1 ], "description": "Numeric selection used for this result." }, "retryAfterSeconds": { "type": "integer", "minimum": 1, "example": 5, "description": "The public schema defines the meaning and format of `retryAfterSeconds`." }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-01-01T00:00:00+00:00", "description": "The public schema defines the meaning and format of `createdAt`." }, "startedAt": { "type": "string", "format": "date-time", "description": "The public schema defines the meaning and format of `startedAt`." }, "completedAt": { "type": "string", "format": "date-time", "description": "The public schema defines the meaning and format of `completedAt`." }, "result": { "$ref": "#/components/schemas/VinEconomicEvaluationResponse" }, "error": { "$ref": "#/components/schemas/VinAsyncJobError" } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "status": { "enum": [ "queued", "running" ] } }, "required": [ "status" ] }, "then": { "required": [ "retryAfterSeconds" ], "not": { "anyOf": [ { "required": [ "result" ] }, { "required": [ "error" ] }, { "required": [ "completedAt" ] } ] } } }, { "if": { "properties": { "status": { "const": "succeeded" } }, "required": [ "status" ] }, "then": { "required": [ "result", "completedAt" ], "not": { "anyOf": [ { "required": [ "retryAfterSeconds" ] }, { "required": [ "error" ] } ] } } }, { "if": { "properties": { "status": { "const": "failed" } }, "required": [ "status" ] }, "then": { "required": [ "error", "startedAt", "completedAt" ], "not": { "anyOf": [ { "required": [ "retryAfterSeconds" ] }, { "required": [ "result" ] } ] } } } ] }, "VisionLicensePlate": { "type": "object", "additionalProperties": false, "required": [ "text", "normalized", "country", "confidence", "position", "obstructions" ], "properties": { "text": { "type": "string", "description": "The public schema defines the meaning and format of `text`.", "example": "M-AB 1234" }, "normalized": { "type": "string", "description": "The public schema defines the meaning and format of `normalized`.", "example": "MAB1234" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "The public schema defines the meaning and format of `country`.", "example": "DE" }, "confidence": { "type": "string", "enum": [ "hoch", "mittel", "gering" ], "description": "The public schema defines the meaning and format of `confidence`.", "example": "hoch" }, "position": { "type": "string", "enum": [ "vorne", "hinten", "unbekannt" ], "description": "The public schema defines the meaning and format of `position`.", "example": "vorne" }, "obstructions": { "type": "array", "items": { "type": "string", "enum": [ "unscharf", "verdeckt", "abgeschnitten", "gespiegelt", "zu_klein", "ueberbelichtet", "verschmutzt" ] }, "description": "The public schema defines the meaning and format of `obstructions`.", "example": [] } } }, "VisionLicensePlateResponse": { "type": "object", "additionalProperties": false, "required": [ "format", "imageCount", "plateCount", "plates" ], "properties": { "format": { "type": "string", "description": "The public schema defines the meaning and format of `format`.", "example": "tapinoma.license-plate.v1" }, "imageCount": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The public schema defines the meaning and format of `imageCount`.", "example": 1 }, "plateCount": { "type": "integer", "minimum": 0, "description": "The public schema defines the meaning and format of `plateCount`.", "example": 1 }, "plates": { "type": "array", "items": { "$ref": "#/components/schemas/VisionLicensePlate" }, "description": "The public schema defines the meaning and format of `plates`." } } }, "RegistrationDocumentV2Field": { "type": "object", "additionalProperties": false, "required": [ "scope", "code", "sourceCode", "name", "value", "sourceValue" ], "properties": { "scope": { "type": "string", "enum": [ "document", "harmonized", "national" ], "description": "Whether the value comes from a document header, a harmonized European field code or a national field." }, "code": { "type": "string", "description": "Canonical semantic identifier. D.2.type, D.2.variant and D.2.version identify the three values sharing the printed D.2 box. A national field without a code receives a stable national: identifier." }, "sourceCode": { "type": [ "string", "null" ], "description": "Exact visibly printed field code, or null when the document prints no code." }, "name": { "type": "string", "description": "Canonical field name in English." }, "value": { "type": "string", "description": "Normalized value. Language-bearing values are in English; identifiers and proper names are unchanged." }, "sourceValue": { "type": [ "string", "null" ], "description": "Exact printed text when value was translated or normalized; otherwise null." } } }, "RegistrationDocumentV2Response": { "type": "object", "additionalProperties": false, "required": [ "format", "document", "registration", "holder", "inspection", "vehicle", "fields", "warnings" ], "properties": { "format": { "type": "string", "enum": [ "tapinoma.vehicle-registration.v2" ] }, "document": { "type": "object", "additionalProperties": false, "required": [ "countryCode", "countryName", "profile", "variantId", "documentType", "documentPart", "documentVersion", "sourceLanguages" ], "properties": { "countryCode": { "type": [ "string", "null" ], "description": "Issuing country as ISO 3166-1 alpha-2; GB is used for the United Kingdom." }, "countryName": { "type": [ "string", "null" ], "description": "Issuing country name in English." }, "profile": { "type": "string", "enum": [ "eu-1999-37-ec", "ch-fahrzeugausweis", "gb-v5c", "generic-national" ] }, "variantId": { "type": "string", "description": "The public schema defines the meaning and format of `variantId`." }, "documentType": { "type": [ "string", "null" ], "description": "Detected document name in English." }, "documentPart": { "type": "string", "enum": [ "part_i", "part_ii", "single_part", "unknown" ] }, "documentVersion": { "type": [ "string", "null" ], "description": "Visible layout edition in English when it can be identified safely." }, "sourceLanguages": { "type": "array", "items": { "type": "string" }, "description": "Detected document languages as lower-case ISO language codes." } } }, "registration": { "type": "object", "additionalProperties": false, "required": [ "registrationNumber", "documentNumber", "issuingAuthority", "firstRegistrationDate", "registrationDate" ], "properties": { "registrationNumber": { "type": [ "string", "null" ] }, "documentNumber": { "type": [ "string", "null" ] }, "issuingAuthority": { "type": [ "string", "null" ] }, "firstRegistrationDate": { "type": [ "string", "null" ] }, "registrationDate": { "type": [ "string", "null" ] } } }, "holder": { "type": "object", "additionalProperties": false, "description": "Personal certificate-holder data copied only from matching visible fields. Proper names and addresses are never translated.", "required": [ "nameOrCompany", "givenNames", "address", "ownershipStatus" ], "properties": { "nameOrCompany": { "type": [ "string", "null" ] }, "givenNames": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "ownershipStatus": { "type": [ "string", "null" ], "description": "Ownership status normalized to English when printed." } } }, "inspection": { "type": "object", "additionalProperties": false, "required": [ "validUntil", "lastInspectionDate", "inspectionPlace" ], "properties": { "validUntil": { "type": [ "string", "null" ] }, "lastInspectionDate": { "type": [ "string", "null" ] }, "inspectionPlace": { "type": [ "string", "null" ] } } }, "vehicle": { "type": "object", "additionalProperties": false, "required": [ "vin", "chassisNumber", "make", "type", "variant", "version", "commercialDescription", "category", "bodyType", "fuelType", "colour", "engineCapacityCc", "maximumNetPowerKw", "maximumTechnicallyPermissibleMassKg", "maximumPermissibleMassKg", "massInServiceKg", "maximumBrakedTrailerMassKg", "maximumUnbrakedTrailerMassKg", "seatsIncludingDriver", "standingPlaces", "typeApprovalNumber", "carbonDioxideEmissionsGPerKm", "environmentalCategory" ], "properties": { "vin": { "type": [ "string", "null" ] }, "chassisNumber": { "type": [ "string", "null" ] }, "make": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "variant": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "commercialDescription": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "bodyType": { "type": [ "string", "null" ] }, "fuelType": { "type": [ "string", "null" ] }, "colour": { "type": [ "string", "null" ] }, "engineCapacityCc": { "type": [ "string", "null" ] }, "maximumNetPowerKw": { "type": [ "string", "null" ] }, "maximumTechnicallyPermissibleMassKg": { "type": [ "string", "null" ] }, "maximumPermissibleMassKg": { "type": [ "string", "null" ] }, "massInServiceKg": { "type": [ "string", "null" ] }, "maximumBrakedTrailerMassKg": { "type": [ "string", "null" ] }, "maximumUnbrakedTrailerMassKg": { "type": [ "string", "null" ] }, "seatsIncludingDriver": { "type": [ "string", "null" ] }, "standingPlaces": { "type": [ "string", "null" ] }, "typeApprovalNumber": { "type": [ "string", "null" ] }, "carbonDioxideEmissionsGPerKm": { "type": [ "string", "null" ] }, "environmentalCategory": { "type": [ "string", "null" ] } } }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/RegistrationDocumentV2Field" }, "description": "Every readable header, harmonized field and national field in document order." }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "SensitiveDocumentQuality": { "type": "string", "enum": [ "standard" ], "default": "standard", "description": "Public data object defined by this schema." }, "RegistrationDocumentResponse": { "type": "object", "additionalProperties": false, "required": [ "registrationNumber", "documentNumber", "issuingAuthority", "issuedDate", "owner", "inspection", "vehicle", "technicalDetailsRaw", "codesAndNotes", "rawTextLines", "notes" ], "properties": { "registrationNumber": { "type": [ "string", "null" ], "description": "The registration plate from field A of the German registration certificate part I, read character by character from the printed field box. `null` when the field cannot be read with certainty." }, "documentNumber": { "type": [ "string", "null" ], "description": "The document number printed after \"Nr.\" on the registration certificate. `null` when that number is not readable in the document." }, "issuingAuthority": { "type": [ "string", "null" ], "description": "The registration authority printed next to the issue date. `null` when no authority is readable there; it is never derived from the plate." }, "issuedDate": { "type": [ "string", "null" ], "format": "date", "description": "The date of issue from field I of the registration certificate part I. `null` when the field cannot be read with certainty." }, "owner": { "type": "object", "additionalProperties": false, "required": [ "nameOrCompany", "givenNames", "address" ], "properties": { "nameOrCompany": { "type": [ "string", "null" ], "description": "The keeper from field C.1.1 — surname or company name. `null` when the field is unreadable; the value comes from that field box only and is never copied from neighbouring lines." }, "givenNames": { "type": [ "string", "null" ], "description": "The keeper's given names from field C.1.2. `null` when the field is unreadable." }, "address": { "type": [ "string", "null" ], "description": "The keeper's address from field C.1.3 exactly as printed in the field box. `null` when the field is unreadable." } } }, "inspection": { "type": "object", "additionalProperties": false, "required": [ "nextInspectionMonthYear", "lastInspectionDate", "inspectionPlace" ], "properties": { "nextInspectionMonthYear": { "type": [ "string", "null" ], "description": "The date of the next periodic technical inspection entered at \"Nächste HU\", as month and year. `null` when no such entry is printed." }, "lastInspectionDate": { "type": [ "string", "null" ], "format": "date", "description": "The date of the last inspection, taken over only when explicitly printed in the document. Otherwise `null` — it is never back-calculated from the next due date." }, "inspectionPlace": { "type": [ "string", "null" ], "description": "The place of inspection, taken over only when explicitly printed in the document; otherwise `null`." } } }, "vehicle": { "type": "object", "additionalProperties": false, "required": [ "vin", "hsn", "tsn", "brand", "modelCode", "commercialName", "vehicleClass", "bodyType", "fuel", "displacementCc", "powerKw", "co2GPerKm", "emissionsClass", "permissibleTotalMassF1", "permissibleTotalMassF2", "unladenMassKg", "axleLoads", "allowedTrailerMassBraked", "allowedTrailerMassUnbraked", "seatsTotal", "seatsDriverIncluded", "tireSizes" ], "properties": { "vin": { "type": [ "string", "null" ], "description": "The vehicle identification number taken from field E only, in upper case and without spaces or separators. It is returned only when all 17 characters are readable and match [A-HJ-NPR-Z0-9]{17}; any incomplete or implausible reading yields `null`." }, "hsn": { "type": [ "string", "null" ], "description": "The manufacturer key number from field 2.1 only, with leading zeroes preserved. Only a sequence of exactly four digits is returned; any other reading yields `null`." }, "tsn": { "type": [ "string", "null" ], "description": "The type key number from field 2.2 only, in upper case and without spaces. Only three to ten letters and digits are returned; any other reading yields `null`." }, "brand": { "type": [ "string", "null" ], "description": "The make from field D.1. The value comes from that field box alone and is never completed or corrected from vehicle knowledge." }, "modelCode": { "type": [ "string", "null" ], "description": "The type code from field D.2. `null` when the field box cannot be read with certainty." }, "commercialName": { "type": [ "string", "null" ], "description": "The commercial description from field D.3. `null` when the field box cannot be read with certainty." }, "vehicleClass": { "type": [ "string", "null" ], "description": "The vehicle class from field J exactly as printed there. `null` when the field is unreadable." }, "bodyType": { "type": [ "string", "null" ], "description": "Vehicle body type; `null` when not readable." }, "fuel": { "type": [ "string", "null" ], "description": "The fuel type from field P.3, taken over unchanged. `null` when the field is unreadable." }, "displacementCc": { "type": [ "string", "null" ], "description": "The engine displacement from field P.1 in cubic centimetres. Printed padding zeroes and units are removed, so \"001480\" becomes 1480." }, "powerKw": { "type": [ "string", "null" ], "description": "The rated power from field P.2 in kilowatts. Printed padding zeroes and the unit are removed; `null` when the field is unreadable." }, "co2GPerKm": { "type": [ "string", "null" ], "description": "The CO2 figure from field V.7 in grams per kilometre, without the printed unit and without padding zeroes. `null` when the field is unreadable." }, "emissionsClass": { "type": [ "string", "null" ], "description": "The emissions class from field 14 exactly as printed there. `null` when the field is unreadable." }, "permissibleTotalMassF1": { "type": [ "string", "null" ], "description": "The technically permissible maximum mass from field F.1 in kilograms, without the printed unit and without padding zeroes. `null` when the field is unreadable." }, "permissibleTotalMassF2": { "type": [ "string", "null" ], "description": "The maximum mass permissible in the state of registration from field F.2 in kilograms, without unit and padding zeroes. `null` when the field is unreadable." }, "unladenMassKg": { "type": [ "string", "null" ], "description": "The mass of the vehicle in running order from field G in kilograms, without unit and padding zeroes. `null` when the field is unreadable." }, "axleLoads": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The axle loads from fields 7.1 to 7.3 in kilograms, each prefixed with its field number in the form \"7.1: 800\". Blank entries are dropped and repetitions are collapsed; with no readable axle load the value stays `null`." }, "allowedTrailerMassBraked": { "type": [ "string", "null" ], "description": "The permissible braked trailer mass from field O.1 in kilograms, without unit and padding zeroes. `null` when the field is unreadable." }, "allowedTrailerMassUnbraked": { "type": [ "string", "null" ], "description": "The permissible unbraked trailer mass from field O.2 in kilograms, without unit and padding zeroes. `null` when the field is unreadable." }, "seatsTotal": { "type": [ "string", "null" ], "description": "The number of seats from field S.1; the driver's seat is already included in that count. `null` when the field is unreadable." }, "seatsDriverIncluded": { "type": [ "string", "null" ] }, "tireSizes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The tyre sizes from fields 15.1 to 15.3, each value only once. Blank entries are dropped; with no readable tyre size the list stays empty or `null`." } } }, "technicalDetailsRaw": { "type": "object", "additionalProperties": false, "required": [ "rawTableLines" ], "properties": { "rawTableLines": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "codesAndNotes": { "type": "object", "additionalProperties": false, "required": [ "pCodes", "eTypeApproval", "otherNotes" ], "properties": { "pCodes": { "type": [ "array", "null" ], "items": { "type": "string" } }, "eTypeApproval": { "type": [ "string", "null" ] }, "otherNotes": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "rawTextLines": { "type": [ "array", "null" ], "items": { "type": "string" } }, "notes": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "RegistrationDocumentEnvelopeResponse": { "type": "object", "additionalProperties": false, "required": [ "status", "data" ], "properties": { "status": { "type": "string", "const": "ok" }, "data": { "$ref": "#/components/schemas/RegistrationDocumentResponse" } } }, "LabelExtractPartNumbersResponse": { "type": "object", "additionalProperties": false, "required": [ "partNumbers" ], "properties": { "partNumbers": { "type": "array", "items": { "type": "string" }, "description": "The recognised part numbers. The list is empty when no part number was recognised." } } }, "VinAsyncJobError": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "vehicle_not_found", "vin_service_unavailable" ], "description": "Stable outcome code of the completed VIN job: `vehicle_not_found` denotes a no-result outcome, while `vin_service_unavailable` denotes a technical failure." }, "message": { "type": "string", "minLength": 1, "description": "Human-readable error description." } }, "description": "Structured error of an asynchronous VIN job. This embedded object uses code instead of the error field used by HTTP error responses." }, "LabelExtractAllResponse": { "type": "object", "description": "Structured label data. Every business field is optional; with no detected content the data object is {}. Present values are never null, arrays are never empty and nested objects are never empty.", "additionalProperties": false, "properties": { "primaryPartNumber": { "type": "string", "description": "Primary part number recognised on the photographed component. The key is omitted entirely when no number is readable; the value is a reading, not a confirmed catalogue number." }, "otherPartNumbers": { "type": "array", "items": { "type": "string" }, "description": "Other recognised part numbers. The key is omitted when no further number was recognised.", "minItems": 1 }, "manufacturer": { "type": "string", "description": "The manufacturer name as printed on the component or its label, taken over verbatim. It is only returned when visible in the picture and is never inferred from shape or market knowledge." }, "brand": { "type": "string", "description": "Recognised brand of the component." }, "moduleType": { "type": "string", "description": "The assembly designation as stated on the label or component, taken over verbatim. There is no controlled vocabulary behind it, and the key is omitted when no such marking is printed." }, "deviceType": { "type": "string", "description": "The device designation as stated on the label, taken over verbatim. Its separation from `moduleType` follows the printed wording alone, not a fixed taxonomy." }, "functionalDescription": { "type": "string", "description": "The functional description text printed on the component or label, taken over word for word. It is not a summary written by the analysis, since free prose is excluded from the output." }, "modelName": { "type": "string", "description": "The printed model or type name of the component. It is kept separate from `primaryPartNumber` and is never derived from it." }, "mountingOrientation": { "type": "string", "description": "A mounting position or orientation stated on the component or label. It is only reported when visibly stated and is never concluded from the shape of the part." }, "functionSymbol": { "type": "string", "description": "Recognised function symbol or technical pictogram on the component." }, "variantInfo": { "type": "object", "properties": { "colorCode": { "type": "string" }, "designCode": { "type": "string" }, "variantCode": { "type": "string" } }, "description": "Visible part variant markings: `colorCode` for a colour code, `designCode` for a design or execution code, and `variantCode` for another variant code. Values are copied verbatim from the image or label and are never inferred; the object is absent or `null` when no variant marking is readable.", "additionalProperties": false, "minProperties": 1 }, "versionInfo": { "type": "object", "properties": { "hardwareVersion": { "type": "string" }, "softwareVersion": { "type": "string" }, "revisionLevel": { "type": "string" }, "softwareId": { "type": "string" } }, "description": "Printed version levels of the component: `hardwareVersion`, `softwareVersion`, `revisionLevel` and `softwareId`. The values are only read off, never checked against known version series.", "additionalProperties": false, "minProperties": 1 }, "versionDetails": { "type": "object", "properties": { "mcPartNumber": { "type": "string" }, "mePartNumber": { "type": "string" }, "softwarePartNumber": { "type": "string" }, "calibrationPartNumber": { "type": "string" } }, "description": "Further part-number-like entries for hardware, software and calibration level (`mcPartNumber`, `mePartNumber`, `softwarePartNumber`, `calibrationPartNumber`) as printed on the label. The block is only filled when these entries are visible.", "additionalProperties": false, "minProperties": 1 }, "productionInfo": { "type": "object", "properties": { "madeIn": { "type": "string" }, "country": { "type": "string" }, "countryCode": { "type": "string" }, "dateCode": { "type": "string" }, "version": { "type": "string" }, "additionalCode": { "type": "string" }, "modelNumber": { "type": "string" }, "testDate": { "type": "string" }, "testerId": { "type": "string" }, "productionDatetime": { "type": "string" }, "factoryCode": { "type": "string" }, "moldDateCodes": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "personnelId": { "type": "string" }, "productionWeek": { "type": "string" }, "productionLot": { "type": "string" }, "productionCodeRaw": { "type": "string" } }, "description": "The public schema defines the meaning and format of `productionInfo`.", "additionalProperties": false, "minProperties": 1 }, "supplierInfo": { "type": "object", "properties": { "supplierCode": { "type": "string" }, "supplierPartNumber": { "type": "string" }, "supplierLevel": { "type": "string" } }, "description": "Supplier-related markings (`supplierCode`, `supplierPartNumber`, `supplierLevel`). The block stays separate from `manufacturer` and is only filled when the data is actually printed on the label.", "additionalProperties": false, "minProperties": 1 }, "logisticsInfo": { "type": "object", "properties": { "sequenceNumber": { "type": "string" }, "containerNumber": { "type": "string" }, "orderNumber": { "type": "string" }, "lineNumber": { "type": "string" }, "kanbanCode": { "type": "string" }, "logisticsCode": { "type": "string" }, "batchNumber": { "type": "string" } }, "description": "Markings from delivery and order handling (`sequenceNumber`, `containerNumber`, `orderNumber`, `lineNumber`, `kanbanCode`, `logisticsCode`, `batchNumber`) exactly as printed on labels and attached slips. They describe the delivery process, not the technical properties of the part.", "additionalProperties": false, "minProperties": 1 }, "assemblyInfo": { "type": "object", "properties": { "description": { "type": "string" }, "assemblyCode": { "type": "string" }, "orientation": { "type": "string" } }, "description": "Assembly-related markings with `description`, `assemblyCode` and `orientation`. The block only appears when such data is readable on the component or its labels.", "additionalProperties": false, "minProperties": 1 }, "pinout": { "type": "array", "items": { "type": "object", "properties": { "connectorIdentifier": { "type": "string" }, "pinNumber": { "type": "string" }, "signal": { "type": "string" }, "description": { "type": "string" }, "notes": { "type": "string" } }, "additionalProperties": false, "minProperties": 1 }, "description": "One entry per pin assignment readable in the picture, with `connectorIdentifier`, `pinNumber`, `signal`, `description` and `notes`. Only pins actually read appear, so the list is not a complete or warranted connector pinout for the part type.", "minItems": 1 }, "connectorColors": { "type": "array", "items": { "type": "string" }, "description": "The connector colours recognised on the component; multiple findings are kept as a list. The key is omitted when no colour could be assigned.", "minItems": 1 }, "qr": { "type": "boolean", "description": "Reports a QR code spotted in the picture. The contract carries no field for the code's payload; without any sign of a QR code the key is omitted." }, "qrType": { "type": "string", "description": "The recognised flavour of the QR code, complementing `qr`, where it is stated on or discernible from the label. Without such information the key is omitted even when `qr` is set." }, "barcode": { "type": "boolean", "description": "Reports that a barcode was spotted in the picture. Its content is not decoded and not returned; the key is omitted when no barcode was discernible." }, "barcodeType": { "type": "string", "description": "The recognised barcode symbology, complementing `barcode`, where stated on or discernible from the label. Without such information the key is omitted." }, "certifications": { "type": "object", "additionalProperties": false, "properties": { "standard": { "type": "object", "additionalProperties": false, "properties": { "ce": { "type": "object", "additionalProperties": false, "properties": { "mark": { "type": [ "string", "boolean" ] }, "number": { "type": "string" }, "country": { "type": "string" } }, "minProperties": 1 }, "fcc": { "type": "object", "additionalProperties": false, "properties": { "mark": { "type": [ "string", "boolean" ] }, "id": { "type": "string" }, "contains": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "minProperties": 1 }, "ic": { "type": "object", "additionalProperties": false, "properties": { "mark": { "type": [ "string", "boolean" ] }, "id": { "type": "string" } }, "minProperties": 1 }, "anatel": { "type": "object", "additionalProperties": false, "properties": { "mark": { "type": [ "string", "boolean" ] }, "id": { "type": "string" } }, "minProperties": 1 }, "bluetooth": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "qdId": { "type": "string" } }, "minProperties": 1 }, "laser": { "type": "object", "additionalProperties": false, "properties": { "class": { "type": "string" }, "standard": { "type": "string" } }, "minProperties": 1 }, "dot": { "type": "object", "additionalProperties": false, "properties": { "mark": { "type": [ "string", "boolean" ] }, "code": { "type": "string" } }, "minProperties": 1 }, "eMark": { "type": "object", "additionalProperties": false, "properties": { "mark": { "type": [ "string", "boolean" ] }, "number": { "type": "string" }, "country": { "type": "string" } }, "minProperties": 1 }, "eceApproval": { "type": "object", "additionalProperties": false, "properties": { "mark": { "type": [ "string", "boolean" ] }, "regulation": { "type": "string" }, "number": { "type": "string" }, "country": { "type": "string" } }, "minProperties": 1 }, "ecallApproval": { "type": "object", "additionalProperties": false, "properties": { "mark": { "type": [ "string", "boolean" ] }, "number": { "type": "string" }, "country": { "type": "string" } }, "minProperties": 1 } }, "minProperties": 1 }, "regional": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "region": { "type": "string" }, "authority": { "type": "string" }, "mark": { "type": "string" }, "number": { "type": "string" }, "country": { "type": "string" }, "date": { "type": "string", "format": "date" } }, "minProperties": 1 }, "minItems": 1 } }, "description": "Regulatory markings: `standard` contains the explicitly named CE, FCC, IC, Anatel, Bluetooth, laser, DOT, E-mark and eCall details; `regional` contains further visible approvals with region, authority, marking, number, country and date. `mark` preserves either the text read from the label or a Boolean presence flag.", "minProperties": 1 }, "mobileInfo": { "type": "object", "properties": { "imei": { "type": "string" }, "iccid": { "type": "string" }, "imsi": { "type": "string" }, "meid": { "type": "string" }, "esn": { "type": "string" } }, "description": "Mobile and device identifiers from the label: `imei`, `iccid`, `imsi`, `meid` and `esn`. Such identifiers are placed here only and never appear in the other number fields.", "additionalProperties": false, "minProperties": 1 }, "networkInfo": { "type": "object", "properties": { "macAddresses": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "description": "Collects in `macAddresses` every MAC address read off the component or its label. MAC addresses are kept here only and are not copied into other number fields.", "additionalProperties": false, "minProperties": 1 }, "electricalSpecs": { "type": "object", "properties": { "voltage": { "type": "string" }, "current": { "type": "string" }, "power": { "type": "string" }, "frequency": { "type": "string" }, "resistance": { "type": "string" } }, "description": "Electrical ratings as printed (`voltage`, `current`, `power`, `frequency`, `resistance`). Voltage, current, power and frequency carry the unit inside the value and use the standard notations `VDC`, `VAC`, `A`, `W` and `Hz`.", "additionalProperties": false, "minProperties": 1 }, "mechanicalSpecs": { "type": "object", "properties": { "rotationAngle": { "type": "string" }, "torque": { "type": "string" }, "rpm": { "type": "string" }, "strokeLength": { "type": "string" }, "force": { "type": "string" }, "displacement": { "type": "string" }, "rotationDirection": { "type": "string" }, "flowDirection": { "type": "string" } }, "description": "Mechanical ratings (`rotationAngle`, `torque`, `rpm`, `strokeLength`, `force`, `displacement`, `rotationDirection`, `flowDirection`) exactly as printed on the part, unit included. No conversion into a common unit takes place.", "additionalProperties": false, "minProperties": 1 }, "fluidInfo": { "type": "object", "properties": { "oilType": { "type": "string" }, "oilVolume": { "type": "string" }, "refrigerant": { "type": "string" }, "otherFluids": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "description": "Fluid data from the component: `oilType`, `oilVolume`, `refrigerant` and further media in `otherFluids`. Quantities such as `oilVolume` carry the printed unit inside the value and are not converted.", "additionalProperties": false, "minProperties": 1 }, "fuelInfo": { "type": "object", "properties": { "minOctane": { "type": "string" }, "fuelType": { "type": "string" }, "specification": { "type": "string" }, "warning": { "type": "string" } }, "description": "Fuel-related markings with `minOctane`, `fuelType`, `specification` and a printed caution text in `warning`. All values come unchanged from the label and are never completed from vehicle knowledge.", "additionalProperties": false, "minProperties": 1 }, "safetyInfo": { "type": "object", "properties": { "warnings": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "pressureRating": { "type": "string" }, "temperatureLimit": { "type": "string" }, "weee": { "type": "boolean" } }, "description": "Safety-related markings: `warnings` with the caution texts read off, `pressureRating` and `temperatureLimit` including their printed unit, and `weee` for a recognised WEEE marking. Regulatory symbols are always captured, but the list does not replace a check against the applicable rules.", "additionalProperties": false, "minProperties": 1 }, "tireInfo": { "type": "object", "properties": { "size": { "type": "string" }, "loadIndex": { "type": "string" }, "speedIndex": { "type": "string" }, "dotCode": { "type": "string" }, "productionWeekYear": { "type": "string" }, "eceMark": { "type": "string" }, "manufacturerCode": { "type": "string" }, "plantCode": { "type": "string" }, "batchCode": { "type": "string" }, "tireModel": { "type": "string" } }, "description": "Tyre markings such as `size`, `loadIndex`, `speedIndex`, `dotCode`, `productionWeekYear`, `eceMark`, manufacturer and plant codes and `tireModel`. The block only appears when the picture actually shows such tyre markings.", "additionalProperties": false, "minProperties": 1 }, "wheelInfo": { "type": "object", "properties": { "rimWidth": { "type": "string" }, "rimDiameter": { "type": "string" }, "profile": { "type": "string" }, "etOffset": { "type": "string" }, "partNumber": { "type": "string" }, "manufacturerCode": { "type": "string" }, "productionCode": { "type": "string" } }, "description": "Wheel markings (`rimWidth`, `rimDiameter`, `profile`, `etOffset`, `partNumber`, `manufacturerCode`, `productionCode`) as read off the wheel. The `partNumber` kept here stays separate from `primaryPartNumber`.", "additionalProperties": false, "minProperties": 1 }, "toolingInfo": { "type": "object", "properties": { "moldCavity": { "type": "string" }, "shapeCode": { "type": "string" }, "toolNumber": { "type": "string" } }, "description": "Tooling markings on the component: `moldCavity`, `shapeCode` and `toolNumber`. They are only reported when readable in the picture.", "additionalProperties": false, "minProperties": 1 }, "engineInfo": { "type": "object", "properties": { "engineCode": { "type": "string" }, "engineVariant": { "type": "string" }, "notes": { "type": "string" } }, "description": "Engine-related markings with `engineCode`, `engineVariant` and supplementary `notes`. The block is filled only when such information is printed on the component or label; it is never derived from the part number.", "additionalProperties": false, "minProperties": 1 }, "supplyChain": { "type": "object", "properties": { "oemFactory": { "type": "string" }, "coreSupplier": { "type": "string" }, "coatingSupplier": { "type": "string" } }, "description": "The public schema defines the meaning and format of `supplyChain`.", "additionalProperties": false, "minProperties": 1 }, "colorCodes": { "type": "object", "properties": { "colors": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "activeColor": { "type": "string" } }, "description": "Recognised colour codes in `colors` and an optional recognised active code in `activeColor`. This is not a warranty about the actual execution.", "additionalProperties": false, "minProperties": 1 }, "fuseRelayInfo": { "type": "object", "properties": { "fuses": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "string" }, "amperage": { "type": "string" }, "color": { "type": "string" }, "label": { "type": "string" } }, "additionalProperties": false, "minProperties": 1 }, "minItems": 1 }, "relays": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "string" }, "color": { "type": "string" }, "label": { "type": "string" }, "rating": { "type": "string" } }, "additionalProperties": false, "minProperties": 1 }, "minItems": 1 } }, "description": "The fuses (`fuses` with `position`, `amperage`, `color`, `label`) and relays (`relays` with `position`, `color`, `label`, `rating`) readable in the picture. Amperages and ratings are taken over as printed and describe only the photographed specimen.", "additionalProperties": false, "minProperties": 1 }, "fuseSlotLayout": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "string" }, "slotType": { "type": "string" }, "compatibleRatings": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "isOccupied": { "type": "boolean" }, "currentFuse": { "type": "object", "properties": { "amperage": { "type": "string" }, "color": { "type": "string" }, "label": { "type": "string" } }, "additionalProperties": false, "minProperties": 1 } }, "additionalProperties": false, "minProperties": 1 }, "description": "Slot-by-slot listing of the fuse positions discernible in the picture, with format (`slotType`), the permitted ratings in `compatibleRatings`, the occupancy flag `isOccupied` and the fuse found in `currentFuse`. It describes the photographed specimen in the state found, not the target layout of the part type.", "minItems": 1 }, "relaySlotLayout": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "string" }, "format": { "type": "string" }, "isOccupied": { "type": "boolean" }, "relay": { "type": "object", "properties": { "color": { "type": "string" }, "label": { "type": "string" }, "rating": { "type": "string" } }, "additionalProperties": false, "minProperties": 1 } }, "additionalProperties": false, "minProperties": 1 }, "description": "Slot-by-slot listing of the relay positions discernible in the picture, with format (`format`), the occupancy flag `isOccupied` and the relay found in `relay`. Again it reports the state of the photographed specimen, not a target layout.", "minItems": 1 }, "manualMarkings": { "type": "array", "items": { "type": "string" }, "description": "All handwritten markings on the component or its labels — figures, initials, strokes, coloured codes and the like. They are deliberately collected here and never moved into the technical fields such as `primaryPartNumber`.", "minItems": 1 }, "logos": { "type": "array", "items": { "type": "string" }, "description": "Pictorial marks and symbols recognised on the component.", "minItems": 1 }, "materials": { "type": "array", "items": { "type": "object", "properties": { "component": { "type": "string" }, "material": { "type": "string" }, "subMaterials": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "additionalProperties": false, "minProperties": 1 }, "description": "One entry per material marking found on the component, with `component`, `material` and `subMaterials`. Only declared markings are taken over; materials are never concluded from appearance.", "minItems": 1 }, "partsList": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "string" }, "description": { "type": "string" } }, "additionalProperties": false, "minProperties": 1 }, "description": "Entries listed on the label as a number together with its description (`partNumber`, `description`). Unlike `otherPartNumbers`, the point here is the pairing of number and text.", "minItems": 1 }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Other findings read off the picture that could not be assigned to any other field. They contain image content only — no assessments, recommendations or explanations from the analysis.", "minItems": 1 } }, "title": "LabelExtractAllData" }, "LabelExtractAllEnvelopeResponse": { "type": "object", "additionalProperties": false, "required": [ "status", "data" ], "properties": { "status": { "type": "string", "const": "ok" }, "data": { "$ref": "#/components/schemas/LabelExtractAllResponse" } } }, "VisionNormalizedRegion": { "type": "object", "additionalProperties": false, "required": [ "x", "y", "width", "height" ], "description": "Public data object defined by this schema.", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1, "example": 0.18 }, "y": { "type": "number", "minimum": 0, "maximum": 1, "example": 0.22 }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 1, "example": 0.64 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 1, "example": 0.55 } } }, "VisionImageOutputOptions": { "type": "object", "additionalProperties": false, "properties": { "size": { "type": "string", "enum": [ "1024x1024", "1536x1024", "1024x1536" ], "default": "1536x1024", "description": "The public schema defines the meaning and format of `size`." }, "format": { "type": "string", "enum": [ "jpeg", "png", "webp" ], "default": "jpeg", "description": "The public schema defines the meaning and format of `format`." } } }, "VisionIdentifierKind": { "type": "string", "enum": [ "mac_address", "imei", "vin", "serial_number", "uuid", "iccid", "eid", "license_key", "access_token", "qr_code", "data_matrix", "barcode", "other_instance_id" ], "description": "Public data object defined by this schema." }, "VisionIdentifierDetection": { "type": "object", "additionalProperties": false, "required": [ "kind", "sourceImageIndex", "region", "action", "confidence", "maskedCharacterCount" ], "properties": { "kind": { "$ref": "#/components/schemas/VisionIdentifierKind" }, "sourceImageIndex": { "type": "integer", "minimum": 0, "description": "The public schema defines the meaning and format of `sourceImageIndex`." }, "region": { "$ref": "#/components/schemas/VisionNormalizedRegion" }, "action": { "type": "string", "enum": [ "suffix_replaced_with_x", "value_replaced_with_x", "code_invalidated" ], "description": "The public schema defines the meaning and format of `action`." }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "preservedPrefixLength": { "type": "integer", "minimum": 0, "default": 0, "description": "The public schema defines the meaning and format of `preservedPrefixLength`." }, "maskedCharacterCount": { "type": "integer", "minimum": 0 } } }, "VisionIdentifierRedaction": { "type": "object", "additionalProperties": false, "required": [ "policy", "applied", "verified", "detections", "machineReadableCodesInvalidated", "preservedTypeIdentifiers" ], "properties": { "policy": { "type": "string", "enum": [ "tapinoma.public-asset-identifiers.v1" ], "description": "The public schema defines the meaning and format of `policy`." }, "applied": { "type": "boolean" }, "verified": { "type": "boolean", "description": "The public schema defines the meaning and format of `verified`." }, "detections": { "type": "array", "items": { "$ref": "#/components/schemas/VisionIdentifierDetection" } }, "machineReadableCodesInvalidated": { "type": "integer", "minimum": 0 }, "preservedTypeIdentifiers": { "type": "array", "items": { "type": "string" }, "uniqueItems": true, "description": "The public schema defines the meaning and format of `preservedTypeIdentifiers`." } } }, "VisionImageProvenance": { "type": "object", "additionalProperties": false, "required": [ "format", "assetType", "synthetic", "requiredLabel", "disclosureEmbedded", "sourceImageUrls", "identifierRedaction", "createdAt" ], "properties": { "format": { "type": "string", "enum": [ "tapinoma.vision-provenance.v1" ] }, "assetType": { "type": "string", "enum": [ "synthetic_reference", "synthetic_condition", "identifier_redacted_original" ] }, "synthetic": { "type": "boolean" }, "requiredLabel": { "type": "string", "description": "The public schema defines the meaning and format of `requiredLabel`.", "example": "KI-generierte Zustandsdarstellung auf Basis der Originalfotos – kein Originalfoto des Einzelteils" }, "disclosureEmbedded": { "type": "boolean", "enum": [ true ], "description": "The public schema defines the meaning and format of `disclosureEmbedded`." }, "sourceImageUrls": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "uri" }, "description": "The public schema defines the meaning and format of `sourceImageUrls`." }, "identifierRedaction": { "$ref": "#/components/schemas/VisionIdentifierRedaction" }, "createdAt": { "type": "string", "format": "date-time" } } }, "VisionImageAsset": { "type": "object", "additionalProperties": false, "required": [ "imageUrl", "view", "width", "height", "format", "provenance", "expiresAt" ], "properties": { "imageUrl": { "type": "string", "format": "uri", "description": "The public schema defines the meaning and format of `imageUrl`.", "example": "https://files.example.com/vision/result-4711.jpg" }, "view": { "type": "string", "enum": [ "custom", "front", "rear", "left", "right", "front_left_45", "front_right_45" ] }, "width": { "type": "integer", "minimum": 1 }, "height": { "type": "integer", "minimum": 1 }, "format": { "type": "string", "enum": [ "jpeg", "png", "webp" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "The public schema defines the meaning and format of `expiresAt`." }, "provenance": { "$ref": "#/components/schemas/VisionImageProvenance" } } }, "VisionPartCompositeRequest": { "type": "object", "additionalProperties": false, "required": [ "partImageUrl", "backgroundImageUrl" ], "properties": { "partImageUrl": { "type": "string", "format": "uri", "description": "The public schema defines the meaning and format of `partImageUrl`.", "example": "https://files.example.com/part.png", "pattern": "^https://[^/@\\s]+(?:/|$)" }, "partMaskUrl": { "type": "string", "format": "uri", "description": "The public schema defines the meaning and format of `partMaskUrl`.", "example": "https://files.example.com/part-mask.png", "pattern": "^https://[^/@\\s]+(?:/|$)" }, "backgroundImageUrl": { "type": "string", "format": "uri", "description": "The public schema defines the meaning and format of `backgroundImageUrl`.", "example": "https://files.example.com/workshop.jpg", "pattern": "^https://[^/@\\s]+(?:/|$)" }, "targetBox": { "$ref": "#/components/schemas/VisionNormalizedRegion" }, "instructions": { "type": "string", "maxLength": 1000, "description": "The public schema defines the meaning and format of `instructions`." }, "quality": { "$ref": "#/components/schemas/ScannerQuality" }, "output": { "$ref": "#/components/schemas/VisionImageOutputOptions" } } }, "VisionPartCompositeResponse": { "type": "object", "additionalProperties": false, "required": [ "format", "asset", "partIdentityPreserved", "limitations" ], "properties": { "format": { "type": "string", "enum": [ "tapinoma.part-composite.v1" ] }, "asset": { "$ref": "#/components/schemas/VisionImageAsset" }, "partIdentityPreserved": { "type": "boolean", "enum": [ true ], "description": "The public schema defines the meaning and format of `partIdentityPreserved`." }, "limitations": { "type": "array", "items": { "type": "string" } } } }, "VisionDamageSource": { "type": "object", "additionalProperties": false, "required": [ "imageUrl" ], "properties": { "imageUrl": { "type": "string", "format": "uri", "description": "The public schema defines the meaning and format of `imageUrl`.", "example": "https://files.example.com/mounted-door.jpg", "pattern": "^https://[^/@\\s]+(?:/|$)" }, "partMaskUrl": { "type": "string", "format": "uri", "description": "The public schema defines the meaning and format of `partMaskUrl`.", "example": "https://files.example.com/mounted-door-mask.png", "pattern": "^https://[^/@\\s]+(?:/|$)" }, "view": { "type": "string", "enum": [ "unknown", "front", "rear", "left", "right", "front_left_45", "front_right_45" ], "default": "unknown" } } }, "VisionDamageTarget": { "type": "object", "additionalProperties": false, "required": [ "imageUrl", "view" ], "properties": { "imageUrl": { "type": "string", "format": "uri", "description": "The public schema defines the meaning and format of `imageUrl`.", "example": "https://files.example.com/door-front-left-45.jpg", "pattern": "^https://[^/@\\s]+(?:/|$)" }, "partMaskUrl": { "type": "string", "format": "uri", "description": "The public schema defines the meaning and format of `partMaskUrl`.", "example": "https://files.example.com/door-target-mask.png", "pattern": "^https://[^/@\\s]+(?:/|$)" }, "view": { "type": "string", "enum": [ "front", "rear", "left", "right", "front_left_45", "front_right_45" ] } } }, "VisionDamageFinding": { "type": "object", "additionalProperties": false, "required": [ "type", "description", "location", "confidence", "sourceImageIndexes", "transferredToViews" ], "properties": { "type": { "type": "string", "enum": [ "scratch", "scuff", "dent", "crack", "paint_loss", "corrosion", "deformation", "missing_piece", "other" ] }, "description": { "type": "string" }, "location": { "type": "string" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "sourceImageIndexes": { "type": "array", "minItems": 1, "items": { "type": "integer", "minimum": 0 }, "uniqueItems": true }, "transferredToViews": { "type": "array", "items": { "type": "string", "enum": [ "front", "rear", "left", "right", "front_left_45", "front_right_45" ] }, "uniqueItems": true } } }, "VisionDamageTransferRequest": { "type": "object", "additionalProperties": false, "required": [ "sources", "targets" ], "properties": { "sources": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "$ref": "#/components/schemas/VisionDamageSource" } }, "targets": { "type": "array", "minItems": 1, "maxItems": 6, "items": { "$ref": "#/components/schemas/VisionDamageTarget" } }, "partType": { "type": "string", "maxLength": 120, "example": "Fahrertür links" }, "instructions": { "type": "string", "maxLength": 1000, "description": "The public schema defines the meaning and format of `instructions`." }, "quality": { "$ref": "#/components/schemas/ScannerQuality" }, "output": { "$ref": "#/components/schemas/VisionImageOutputOptions" } } }, "VisionDamageTransferResponse": { "type": "object", "additionalProperties": false, "required": [ "format", "assets", "findings", "notTransferred", "limitations", "visualOnly" ], "properties": { "format": { "type": "string", "enum": [ "tapinoma.damage-transfer.v1" ] }, "assets": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/VisionImageAsset" }, "maxItems": 6 }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/VisionDamageFinding" } }, "notTransferred": { "type": "array", "items": { "type": "string" }, "description": "The public schema defines the meaning and format of `notTransferred`." }, "limitations": { "type": "array", "items": { "type": "string" } }, "visualOnly": { "type": "boolean", "enum": [ true ] } } }, "VisionIdentifierRedactRequest": { "type": "object", "additionalProperties": false, "required": [ "imageUrls" ], "properties": { "imageUrls": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "format": "uri", "pattern": "^https://[^/@\\s]+(?:/|$)" }, "description": "The public schema defines the meaning and format of `imageUrls`." }, "output": { "$ref": "#/components/schemas/VisionImageOutputOptions" }, "quality": { "$ref": "#/components/schemas/ScannerQuality" } } }, "VisionIdentifierRedactResponse": { "type": "object", "additionalProperties": false, "required": [ "format", "assets" ], "properties": { "format": { "type": "string", "enum": [ "tapinoma.identifier-redaction.v1" ] }, "assets": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/VisionImageAsset" }, "maxItems": 10 } } }, "PartOeListPrice": { "type": "object", "additionalProperties": false, "required": [ "amount", "currency", "country", "isNet" ], "properties": { "amount": { "type": "number", "minimum": 0, "description": "Non-negative list-price amount in the currency specified by `currency`." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Three-letter uppercase currency code, for example `EUR`." }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Two-letter uppercase country code associated with the price; `null` when no country is specified." }, "isNet": { "type": [ "boolean", "null" ], "description": "`true` for a net price, `false` for a gross price, and `null` when tax treatment is not specified." } } }, "PartOePart": { "type": "object", "additionalProperties": false, "required": [ "number", "manufacturer", "name", "listPrice" ], "properties": { "number": { "type": "string", "minLength": 1, "description": "The confirmed OE part number of this part entry." }, "manufacturer": { "type": [ "string", "null" ], "minLength": 1, "description": "Manufacturer designation of the part; `null` when no public manufacturer value is available." }, "name": { "type": [ "string", "null" ], "minLength": 1, "description": "Part designation when available; otherwise `null`." }, "listPrice": { "oneOf": [ { "$ref": "#/components/schemas/PartOeListPrice" }, { "type": "null" } ], "description": "Optional list price of the part; `null` when no usable price is available." } }, "description": "Public data object defined by this schema." }, "PartOeReplacement": { "type": "object", "additionalProperties": false, "required": [ "from", "to" ], "properties": { "from": { "type": "string", "minLength": 1, "description": "Confirmed OE number that is replaced by `to`." }, "to": { "type": "string", "minLength": 1, "description": "Confirmed OE number of the direct successor part." } } }, "VehicleDocumentCode": { "type": "object", "additionalProperties": false, "required": [ "codeSystem", "value", "normalizedValue" ], "properties": { "codeSystem": { "type": "string", "enum": [ "manufacturer_order", "kba_hsn", "kba_tsn", "model_code", "manufacturer_variant_code", "engine_code", "transmission_code", "color_code", "paint_code", "other" ], "description": "The public schema defines the meaning and format of `codeSystem`." }, "value": { "type": "string", "description": "The code as a string exactly as printed, including leading zeroes, spaces, separators and prefixes. It is never returned as a number or enriched from external vehicle knowledge." }, "normalizedValue": { "type": [ "string", "null" ], "description": "Optional comparison form of the adjacent `value`. It may remove formatting separators only; content, leading zeroes and prefixes must remain unchanged. `null` when no safe, purely formal normalisation is possible or necessary." } } }, "VehicleDocumentEquipment": { "type": "object", "additionalProperties": false, "required": [ "codes", "name", "equipmentKind", "availability", "isPackage", "category", "sourceSection", "listPrice", "quantity", "sourcePage" ], "properties": { "codes": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleDocumentCode" }, "description": "Every code printed directly for this equipment item, each with its code system and original value. The list is empty when the item has a name only; codes from other rows and vehicle-level identifiers are not copied into it." }, "name": { "type": "string", "description": "The public schema defines the meaning and format of `name`." }, "equipmentKind": { "type": [ "string", "null" ], "enum": [ "standard", "variant", "special", null ], "description": "The public schema defines the meaning and format of `equipmentKind`." }, "availability": { "type": [ "string", "null" ], "enum": [ "series", "option_free", "option_paid", "option_price_unknown", "option_unavailable", "mandatory_paid", null ], "description": "Documented availability: series equipment, free or paid option, option with unknown price, unavailable option, or mandatory paid equipment. `null` when unstated." }, "isPackage": { "type": [ "boolean", "null" ], "description": "`true` only for an explicitly identified package, `false` for an explicitly individual item, and otherwise `null`." }, "category": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `category`." }, "sourceSection": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `sourceSection`." }, "listPrice": { "type": "object", "additionalProperties": false, "required": [ "net", "gross", "currency" ], "properties": { "net": { "type": [ "number", "null" ], "description": "Explicitly printed net list price in currency units, not cents; otherwise `null`." }, "gross": { "type": [ "number", "null" ], "description": "Explicitly printed gross list price in currency units, not cents; otherwise `null`." }, "currency": { "type": [ "string", "null" ], "description": "ISO currency code or unambiguous printed currency of the list price; otherwise `null`." } }, "description": "Printed list price for this item. The block is always present; missing values remain `null` and are not calculated from totals." }, "quantity": { "type": [ "number", "null" ], "description": "Printed quantity of this equipment item as a unitless number. It is not derived from price or wording and is `null` when the document states no quantity." }, "sourcePage": { "type": [ "integer", "null" ], "description": "The public schema defines the meaning and format of `sourcePage`." } } }, "VehicleDocumentExtractionResponse": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "document", "vehicle", "equipment", "sensitiveData", "warnings" ], "properties": { "schemaVersion": { "type": "string", "enum": [ "1.0" ], "description": "Version of this closed, standardised response format. It is fixed at `1.0` for this contract; a semantic change to the fields requires a new version." }, "document": { "type": "object", "additionalProperties": false, "required": [ "type", "title", "number", "date", "language", "pageCount" ], "properties": { "type": { "type": [ "string", "null" ], "enum": [ "vehicle_order", "repair_cost_calculation", "appraisal", "invoice", "vehicle_configuration", "other", null ], "description": "The public schema defines the meaning and format of `type`." }, "title": { "type": [ "string", "null" ], "description": "Only with `includeSensitiveData: true`: the printed title or unambiguous document designation, copied without translation. It is `null` without opt-in or an identifiable title." }, "number": { "type": [ "string", "null" ], "description": "Only with `includeSensitiveData: true`: the document's own explicitly labelled order, invoice, appraisal or document number. Customer, bank and unrelated references are never substituted; it is `null` without opt-in or a matching number." }, "date": { "type": [ "string", "null" ], "description": "Only with `includeSensitiveData: true`: the document date itself, not a registration, delivery or customer date, at printed precision as `YYYY-MM-DD`, `YYYY-MM` or `YYYY`. It is `null` without opt-in or a labelled document date." }, "language": { "type": [ "string", "null" ], "description": "Detected primary language of the analysed document. `null` when it cannot be established reliably; vehicle names, descriptions and codes are therefore not translated." }, "pageCount": { "type": [ "integer", "null" ], "description": "The public schema defines the meaning and format of `pageCount`." } }, "description": "Metadata of the analysed vehicle document. The block is always present; values not printed explicitly or not determinable with confidence are `null`." }, "vehicle": { "type": "object", "additionalProperties": false, "required": [ "vin", "displayName", "manufacturer", "model", "modelCode", "mainTypeGroup", "type", "variant", "manufacturerVariantCode", "condition", "bodyType", "doors", "seats", "mileageKm", "modelYear", "productionDate", "firstRegistration", "constructionPeriod", "powertrain", "transmission", "energy", "colors", "identifiers", "kba" ], "properties": { "vin": { "type": [ "string", "null" ], "description": "Complete 17-character vehicle identification number explicitly labelled VIN/FIN/chassis number. `null` when missing, incomplete or conflicting; another 17-character number is never substituted." }, "displayName": { "type": [ "string", "null" ], "description": "Complete vehicle designation from the document, without external enrichment; otherwise `null`." }, "manufacturer": { "type": [ "string", "null" ], "description": "Manufacturer or make exactly as stated in the document. `null` when no unambiguous vehicle make is printed; it is not derived from codes." }, "model": { "type": [ "string", "null" ], "description": "Vehicle model or commercial designation as stated in the document. `null` when it cannot be identified explicitly." }, "modelCode": { "type": [ "string", "null" ], "description": "Explicitly labelled manufacturer/model code, such as `AB12`, not an equipment or engine code. `null` when no such code is stated." }, "mainTypeGroup": { "type": [ "string", "null" ], "description": "Main type group or vehicle series exactly as named in the document; otherwise `null`." }, "type": { "type": [ "string", "null" ], "description": "Vehicle type or type code exactly as stated in the document; otherwise `null`." }, "variant": { "type": [ "string", "null" ], "description": "Vehicle variant, trim or equipment line in the document's wording. `null` when no corresponding designation is printed." }, "manufacturerVariantCode": { "type": [ "string", "null" ], "description": "Explicitly printed manufacturer variant code; otherwise `null`. The same value is retained as `manufacturer_variant_code` in `identifiers`." }, "condition": { "type": [ "string", "null" ], "enum": [ "new", "used", null ], "description": "`new` or `used` only when the document states that condition; otherwise `null`. Mileage, date and document type are never used to infer it." }, "bodyType": { "type": [ "string", "null" ], "description": "Body style exactly as stated in the document. `null` when it is not printed explicitly; it is not inferred from model or series." }, "doors": { "type": [ "integer", "null" ], "description": "Number of doors as an integer, only when explicitly stated in the document; otherwise `null`." }, "seats": { "type": [ "integer", "null" ], "description": "Explicitly stated number of seats as an integer; otherwise `null`." }, "mileageKm": { "type": [ "number", "null" ], "description": "Printed odometer reading in kilometres as a unitless number. Miles are not converted and the value is not inferred; `null` without an unambiguous kilometre figure." }, "modelYear": { "type": [ "integer", "null" ], "description": "Explicitly stated model year as an integer; otherwise `null`." }, "productionDate": { "type": [ "string", "null" ], "description": "Production date at exactly the printed precision (`YYYY-MM-DD`, `YYYY-MM` or `YYYY`); otherwise `null`." }, "firstRegistration": { "type": [ "string", "null" ], "description": "First registration stated in the document, at the precision actually printed as `YYYY-MM-DD`, `YYYY-MM` or `YYYY`. Missing month/day parts are never invented; `null` when unstated." }, "constructionPeriod": { "type": "object", "additionalProperties": false, "required": [ "from", "until" ], "properties": { "from": { "type": [ "string", "null" ], "description": "Printed beginning of the build/production period at the available precision (`YYYY-MM-DD`, `YYYY-MM` or `YYYY`). `null` when no beginning is stated." }, "until": { "type": [ "string", "null" ], "description": "Printed end of the build/production period at the available precision. `null` for an open-ended or unstated end; the current date is never substituted." } }, "description": "Build or production period stated in the document. The block remains present when one or both boundaries are missing; unknown boundaries are `null`." }, "powertrain": { "type": "object", "additionalProperties": false, "required": [ "type", "fuelType", "powerKw", "powerPs", "displacementCcm", "engineDescription", "engineCodes", "driveType", "emissionClass" ], "properties": { "type": { "type": [ "string", "null" ], "description": "High-level powertrain type stated in the document, such as combustion, hybrid or electric. `null` when no classification is printed." }, "fuelType": { "type": [ "string", "null" ], "description": "Fuel or energy type exactly as stated in the document. `null` when unstated; it is not inferred from consumption values." }, "powerKw": { "type": [ "number", "null" ], "description": "Printed power in kilowatts as a decimal number. A value stated only in horsepower is not converted; `null` without a printed kW figure." }, "powerPs": { "type": [ "number", "null" ], "description": "Printed power in metric horsepower as a decimal number. A value stated only in kW is not converted; `null` without a printed PS figure." }, "displacementCcm": { "type": [ "number", "null" ], "description": "Printed displacement in cubic centimetres as a decimal number. Litres are not converted; `null` without an unambiguous cm³/ccm value." }, "engineDescription": { "type": [ "string", "null" ], "description": "Free-text engine or powertrain description from the document, such as displacement/power wording or a manufacturer designation. `null` when no separate description is printed." }, "engineCodes": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleDocumentCode" }, "description": "Every identifier explicitly labelled as an engine code. The list is empty when no engine code is printed; equipment codes are not copied here merely because they appear technically plausible." }, "driveType": { "type": [ "string", "null" ], "description": "Drive layout or driven axle(s) in the document's wording, such as front-, rear- or all-wheel drive. `null` when unstated." }, "emissionClass": { "type": [ "string", "null" ], "description": "Printed emissions class or stage, copied unchanged; otherwise `null`." } }, "description": "Powertrain and engine data stated in the document. The block is always present; unprinted scalars are `null`, and `engineCodes` is an empty list without a match." }, "transmission": { "type": "object", "additionalProperties": false, "required": [ "type", "description", "gears", "codes" ], "properties": { "type": { "type": [ "string", "null" ], "description": "Transmission type stated in the document, such as automatic, manual or dual-clutch. `null` when no type is stated explicitly." }, "description": { "type": [ "string", "null" ], "description": "Free-text transmission designation from the document, such as a manufacturer name or long description. `null` when none is printed." }, "gears": { "type": [ "integer", "null" ], "description": "Printed number of forward gears as an integer. `null` when no gear count is stated; it is not guessed from the transmission name." }, "codes": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleDocumentCode" }, "description": "Every value explicitly labelled as a transmission/gearbox code. `[]` without such a value; equipment and engine codes are not reassigned." } }, "description": "Transmission data stated in the document. The block is always present; unknown scalars are `null`, and its code list is empty without a printed identifier." }, "energy": { "type": "object", "additionalProperties": false, "required": [ "fuelConsumptionCombinedLPer100Km", "energyConsumptionCombinedKwhPer100Km", "electricRangeCombinedKm", "electricRangeCityKm", "co2EmissionsCombinedGPerKm", "co2Class", "acceleration0To100Seconds" ], "properties": { "fuelConsumptionCombinedLPer100Km": { "type": [ "number", "null" ], "description": "Printed combined fuel consumption in litres per 100 kilometres as a decimal number. `null` when the combined figure or this unit is not unambiguous." }, "energyConsumptionCombinedKwhPer100Km": { "type": [ "number", "null" ], "description": "Printed combined energy consumption in kilowatt-hours per 100 kilometres as a decimal number. `null` when the combined figure or this unit is not unambiguous." }, "electricRangeCombinedKm": { "type": [ "number", "null" ], "description": "Printed combined electric range in kilometres as a decimal number. A different range type is never used as a substitute." }, "electricRangeCityKm": { "type": [ "number", "null" ], "description": "Printed city electric range in kilometres as a decimal number. `null` when the document gives no clearly urban electric range." }, "co2EmissionsCombinedGPerKm": { "type": [ "number", "null" ], "description": "Printed combined CO₂ emissions in grams per kilometre as a decimal number. `null` unless the value, unit and combined scope are unambiguous." }, "co2Class": { "type": [ "string", "null" ], "description": "Printed CO₂ or efficiency class in the document's wording. `null` when no class is stated; it is not calculated from the emissions value." }, "acceleration0To100Seconds": { "type": [ "number", "null" ], "description": "Printed 0–100 km/h acceleration time in seconds as a decimal number. `null` when this measurement is not stated explicitly." } }, "description": "Printed consumption, range, emissions and acceleration figures. Each field fixes its unit in its name; missing values remain `null` and no conversion between test cycles or units is performed." }, "colors": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "type", "name", "codes" ], "properties": { "type": { "type": "string", "enum": [ "exterior", "interior", "other" ], "description": "Assignment to `exterior`, `interior` or `other`, based only on the printed label or the section in which the item occurs." }, "name": { "type": [ "string", "null" ], "description": "Colour, paint or upholstery name exactly as printed; `null` when the item provides a code but no name." }, "codes": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleDocumentCode" }, "description": "Every manufacturer, colour or paint code printed directly for this colour/upholstery. The list is empty without a code; the plain-text name is not repeated as a code." } } }, "description": "Printed exterior, interior and other colour or upholstery selections. The list is empty when no colour can be assigned safely; configured colours may also appear as equipment items." }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleDocumentCode" }, "description": "The public schema defines the meaning and format of `identifiers`." }, "kba": { "type": "object", "additionalProperties": false, "required": [ "hsn", "tsn" ], "properties": { "hsn": { "type": [ "string", "null" ], "description": "Manufacturer key number exactly as a printed string, including leading zeroes; otherwise `null`." }, "tsn": { "type": [ "string", "null" ], "description": "Type key number exactly as a printed string, including leading zeroes; otherwise `null`." } }, "description": "Direct German KBA identifiers. The block is always present; HSN or TSN values not printed are `null`." } }, "description": "Core and technical vehicle data explicitly stated in the document. The block is always present; missing scalar values are `null`, missing code/colour/identifier collections are empty, and no external vehicle enrichment is performed." }, "equipment": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleDocumentEquipment" }, "description": "The public schema defines the meaning and format of `equipment`." }, "sensitiveData": { "type": "object", "additionalProperties": false, "required": [ "included", "persons", "bankAccounts", "contract" ], "properties": { "included": { "type": "boolean", "description": "`true` when sensitive data was explicitly requested; otherwise `false`. This flag does not mean that the document actually contained sensitive values." }, "persons": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "role", "name", "company", "email", "phone", "address", "sourcePage" ], "properties": { "role": { "type": [ "string", "null" ], "description": "Printed role, such as customer, buyer, seller or contact; otherwise `null`." }, "name": { "type": [ "string", "null" ], "description": "Person name exactly as printed; otherwise `null`." }, "company": { "type": [ "string", "null" ], "description": "Printed company or organisation name; otherwise `null`." }, "email": { "type": [ "string", "null" ], "description": "Explicitly printed email address; otherwise `null`." }, "phone": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `phone`." }, "address": { "type": "object", "additionalProperties": false, "required": [ "fullText", "street", "houseNumber", "postalCode", "city", "country" ], "properties": { "fullText": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `fullText`." }, "street": { "type": [ "string", "null" ], "description": "Printed street name without inferred additions; otherwise `null`." }, "houseNumber": { "type": [ "string", "null" ], "description": "Printed house number including suffixes; otherwise `null`." }, "postalCode": { "type": [ "string", "null" ], "description": "Printed postal code as a string, retaining leading zeroes; otherwise `null`." }, "city": { "type": [ "string", "null" ], "description": "Printed city or locality; otherwise `null`." }, "country": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `country`." } }, "description": "Address block for this person or organisation. It is always present; unprinted parts remain `null`." }, "sourcePage": { "type": [ "integer", "null" ], "description": "One-based physical document page on which the person or organisation was read; otherwise `null`." } } }, "description": "People or organisations explicitly named in the document, with printed roles and contact details. The list is empty without opt-in or findings." }, "bankAccounts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "accountHolder", "iban", "bic", "bankName", "sourcePage" ], "properties": { "accountHolder": { "type": [ "string", "null" ], "description": "Printed account holder; otherwise `null`." }, "iban": { "type": [ "string", "null" ], "description": "IBAN exactly as printed, without completion or calculated correction; otherwise `null`." }, "bic": { "type": [ "string", "null" ], "description": "BIC exactly as printed; otherwise `null`." }, "bankName": { "type": [ "string", "null" ], "description": "Printed bank name; otherwise `null`." }, "sourcePage": { "type": [ "integer", "null" ], "description": "One-based physical document page carrying the bank account; otherwise `null`." } } }, "description": "Explicitly printed bank accounts, each kept as a separate item. The list is empty without opt-in or findings." }, "contract": { "type": "object", "additionalProperties": false, "required": [ "contractNumber", "customerNumber", "contractType", "status", "signedDate", "startDate", "endDate", "durationMonths", "annualMileageKm", "totalMileageKm", "monthlyRate", "totalAmount", "paymentTerms", "fields" ], "properties": { "contractNumber": { "type": [ "string", "null" ], "description": "Explicitly labelled contract number; otherwise `null`." }, "customerNumber": { "type": [ "string", "null" ], "description": "Explicitly labelled customer number; otherwise `null`." }, "contractType": { "type": [ "string", "null" ], "description": "Printed contract type, such as lease or purchase; otherwise `null`." }, "status": { "type": [ "string", "null" ], "description": "Printed contract status; otherwise `null`." }, "signedDate": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `signedDate`." }, "startDate": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `startDate`." }, "endDate": { "type": [ "string", "null" ], "description": "The public schema defines the meaning and format of `endDate`." }, "durationMonths": { "type": [ "integer", "null" ], "description": "Explicit contract duration in months as an integer; otherwise `null`." }, "annualMileageKm": { "type": [ "number", "null" ], "description": "Explicit agreed annual mileage in kilometres as a number; otherwise `null`." }, "totalMileageKm": { "type": [ "number", "null" ], "description": "Explicit agreed total mileage in kilometres as a number; otherwise `null`." }, "monthlyRate": { "type": "object", "additionalProperties": false, "required": [ "net", "gross", "currency" ], "properties": { "net": { "type": [ "number", "null" ], "description": "Explicitly printed net monthly rate; otherwise `null`." }, "gross": { "type": [ "number", "null" ], "description": "Explicitly printed gross monthly rate; otherwise `null`." }, "currency": { "type": [ "string", "null" ], "description": "Printed currency of the monthly rate, preferably as an ISO code; otherwise `null`." } }, "description": "Printed monthly rate. The block is always present; missing values remain `null` and are not calculated." }, "totalAmount": { "type": "object", "additionalProperties": false, "required": [ "net", "gross", "currency" ], "properties": { "net": { "type": [ "number", "null" ], "description": "Explicitly printed net total amount; otherwise `null`." }, "gross": { "type": [ "number", "null" ], "description": "Explicitly printed gross total amount; otherwise `null`." }, "currency": { "type": [ "string", "null" ], "description": "Printed currency of the total amount, preferably as an ISO code; otherwise `null`." } }, "description": "Printed total contract amount. The block is always present; missing values remain `null` and are not calculated." }, "paymentTerms": { "type": [ "string", "null" ], "description": "Short, explicitly printed payment terms; otherwise `null`. General terms or long legal text are excluded." }, "fields": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "label", "value", "sourcePage" ], "properties": { "label": { "type": "string", "description": "Printed label of the additional contract value." }, "value": { "type": "string", "description": "Printed value associated directly with the label." }, "sourcePage": { "type": [ "integer", "null" ], "description": "One-based physical document page of the additional contract value; otherwise `null`." } } }, "description": "Other short labelled contract values without a dedicated field. The list is empty without such values or opt-in; general terms and legal text are not transcribed." } }, "description": "Contract and payment data. The object is always present; without opt-in its scalar values are `null`, amount objects contain only `null`, and `fields` is empty." } }, "description": "Separate object block for sensitive document content. The object is always present. Without explicit `includeSensitiveData: true`, `persons` and `bankAccounts` are empty lists; nullable fields in `contract` are `null`, the amount objects contain only `null`, and `fields` is empty." }, "warnings": { "type": "array", "items": { "type": "string", "enum": [ "document_incomplete", "document_partially_unreadable", "empty_code_removed", "equipment_data_ambiguous", "vehicle_data_ambiguous", "vin_conflict", "vin_invalid_format", "vin_missing" ] }, "description": "Only fixed, non-value-bearing technical warning codes. Allowed values are `document_incomplete`, `document_partially_unreadable`, `empty_code_removed`, `equipment_data_ambiguous`, `vehicle_data_ambiguous`, `vin_conflict`, `vin_invalid_format` and `vin_missing`; free text and document values are removed." } } }, "PartOeFitment": { "type": "object", "additionalProperties": false, "required": [ "vehicleTypeKey", "criteria" ], "properties": { "vehicleTypeKey": { "type": "string", "minLength": 1, "description": "The public schema defines the meaning and format of `vehicleTypeKey`." }, "criteria": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 }, "description": "The public schema defines the meaning and format of `criteria`." } } }, "PartOeReferenceGroup": { "type": "object", "additionalProperties": false, "required": [ "manufacturer", "numbers" ], "properties": { "manufacturer": { "type": "string", "description": "Manufacturer label for the reference group; it can be empty when the group is recorded without one." }, "numbers": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 }, "description": "Confirmed reference and comparison numbers in this manufacturer group." } } }, "PartOeReferenceNumbers": { "type": "object", "additionalProperties": false, "required": [ "oe_oem_reference_numbers" ], "properties": { "oe_oem_reference_numbers": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 }, "description": "Confirmed consolidated OE/OEM reference and comparison numbers, including the confirmed OE number." } }, "description": "Consolidated view of the confirmed numbers in `references`, including the confirmed OE number." }, "PartIdentifyCandidate": { "type": "object", "additionalProperties": false, "required": [ "name", "number", "tapiGenArt", "category", "listPrice", "score", "reasons" ], "properties": { "name": { "type": "string", "example": "Scheinwerfer links komplett", "description": "The public schema defines the meaning and format of `name`." }, "number": { "type": "string", "example": "9677202480", "description": "The public schema defines the meaning and format of `number`." }, "tapiGenArt": { "type": [ "string", "null" ], "pattern": "^TGA-[0-9]{6}$", "example": "TGA-000651", "description": "The public schema defines the meaning and format of `tapiGenArt`." }, "category": { "type": [ "string", "null" ], "example": "lighting", "description": "The public schema defines the meaning and format of `category`." }, "listPrice": { "type": [ "number", "null" ], "example": 383.65, "description": "The public schema defines the meaning and format of `listPrice`." }, "score": { "type": "number", "minimum": 0, "maximum": 1, "example": 0.75, "description": "The public schema defines the meaning and format of `score`." }, "reasons": { "type": "array", "items": { "type": "string", "description": "The public schema defines the meaning and format of `reasons`." }, "example": [ "term_as_attribute", "side" ], "description": "The public schema defines the meaning and format of `reasons`." } }, "description": "Public data object defined by this schema." }, "PartIdentifyLabelReading": { "type": "object", "additionalProperties": false, "properties": { "extractAll": { "type": "object", "additionalProperties": true, "example": { "primaryPartNumber": "96 883 29 80 A 01", "otherPartNumbers": [ "9688329800" ] }, "description": "The public schema defines the meaning and format of `extractAll`." }, "numbers": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The public schema defines the meaning and format of `numbers`." }, "example": [ "9654310730" ], "description": "The public schema defines the meaning and format of `numbers`." } }, "description": "Public data object defined by this schema." }, "PartIdentifyRequest": { "type": "object", "additionalProperties": false, "properties": { "vin": { "type": "string", "minLength": 3, "maxLength": 17, "pattern": "^[A-HJ-NPR-Za-hj-npr-z0-9]{3,17}$", "example": "VF37J9HL0FJ604214", "description": "The public schema defines the meaning and format of `vin`." }, "manufacturer": { "type": "string", "minLength": 1, "maxLength": 100, "example": "PEUGEOT", "description": "The public schema defines the meaning and format of `manufacturer`." }, "customerOeNumbers": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The public schema defines the meaning and format of `customerOeNumbers`." }, "example": [ "9677202480" ], "description": "The public schema defines the meaning and format of `customerOeNumbers`." }, "labelReadings": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/PartIdentifyLabelReading" }, "description": "The public schema defines the meaning and format of `labelReadings`." }, "descriptions": { "type": "array", "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 160, "description": "The public schema defines the meaning and format of `descriptions`." }, "example": [ "Scheinwerfer links" ], "description": "The public schema defines the meaning and format of `descriptions`." } } }, "PartIdentifyResponse": { "type": "object", "additionalProperties": false, "required": [ "status", "oeNumber", "normalizedOeNumber", "tapiGenArt", "source", "confidence", "manufacturer", "vinPart", "candidates" ], "properties": { "status": { "type": "string", "enum": [ "matched", "candidates", "unresolved" ], "description": "The public schema defines the meaning and format of `status`." }, "oeNumber": { "type": [ "string", "null" ], "example": "9677202480", "description": "The public schema defines the meaning and format of `oeNumber`." }, "normalizedOeNumber": { "type": [ "string", "null" ], "example": "9677202480", "description": "The public schema defines the meaning and format of `normalizedOeNumber`." }, "tapiGenArt": { "type": [ "string", "null" ], "pattern": "^TGA-[0-9]{6}$", "example": "TGA-000651", "description": "The public schema defines the meaning and format of `tapiGenArt`." }, "source": { "type": [ "string", "null" ], "enum": [ "customer", "label", "vin_parts_list", null ], "description": "The public schema defines the meaning and format of `source`." }, "confidence": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "example": 0.99, "description": "The public schema defines the meaning and format of `confidence`." }, "manufacturer": { "type": [ "string", "null" ], "example": "PEUGEOT", "description": "The public schema defines the meaning and format of `manufacturer`." }, "vinPart": { "oneOf": [ { "$ref": "#/components/schemas/PartIdentifyVinPart" }, { "type": "null" } ], "description": "The public schema defines the meaning and format of `vinPart`." }, "candidates": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/PartIdentifyCandidate" }, "description": "The public schema defines the meaning and format of `candidates`." } } }, "PartIdentifyVinPart": { "type": "object", "additionalProperties": false, "required": [ "name", "number", "tapiGenArt", "category", "listPrice" ], "properties": { "name": { "type": "string", "example": "Scheinwerfer links komplett", "description": "The public schema defines the meaning and format of `name`." }, "number": { "type": "string", "example": "9677202480", "description": "The public schema defines the meaning and format of `number`." }, "tapiGenArt": { "type": [ "string", "null" ], "pattern": "^TGA-[0-9]{6}$", "example": "TGA-000651", "description": "The public schema defines the meaning and format of `tapiGenArt`." }, "category": { "type": [ "string", "null" ], "example": "lighting", "description": "The public schema defines the meaning and format of `category`." }, "listPrice": { "type": [ "number", "null" ], "example": 383.65, "description": "The public schema defines the meaning and format of `listPrice`." } } } }, "headers": { "Location": { "description": "URI of the accepted asynchronous job. Poll this address unchanged until the job reaches a terminal state.", "schema": { "type": "string", "format": "uri-reference" }, "example": "/vin/parts/jobs/6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21" }, "Retry-After": { "description": "Minimum number of seconds to wait before the next useful retry or status poll.", "schema": { "type": "integer", "minimum": 0 }, "example": 5 }, "X-Tapinoma-Billing-Bundle": { "description": "Machine-readable identifier of the billing bundle to which this call was assigned.", "schema": { "type": "string" }, "example": "VIN_MONTHLY_LOOKUP" }, "X-Tapinoma-Billing-Source": { "description": "The public schema defines the meaning and format of `X-Tapinoma-Billing-Source`.", "schema": { "type": "string", "enum": [ "plan", "balance", "bundle", "sandbox", "idempotent_replay" ] }, "example": "plan" }, "X-Tapinoma-Idempotent-Replay": { "description": "The public schema defines the meaning and format of `X-Tapinoma-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] }, "example": "true" }, "X-Tapinoma-Live-Available-At": { "description": "Earliest time at which temporarily paused live processing should be retried.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-18T14:05:00+00:00" }, "X-Tapinoma-Sponsorship-Grant": { "description": "Reference of the sponsorship grant associated with this call. It identifies the billing sponsor but does not prove a debit; sandbox calls and idempotent replays can retain a sponsor association without moving money.", "schema": { "type": "string" }, "example": "erp-customer-4711" }, "X-Tapinoma-Usage-Warning": { "description": "Human-readable, informational warning about plan or credit consumption; emitted from 90 percent usage and once the quota is exhausted. The English free text is not a stable machine code and must not be parsed; multiple warnings are joined with ` | `.", "schema": { "type": "string" }, "example": "Plan STANDARD for scanner.label.extract_all has reached at least 90% usage (90 of 100)." }, "X-Tapinoma-Idempotency-Stored": { "description": "`true`: An unchanged repeat with the same `Idempotency-Key` can return the earlier result. `false`: The same key returns `409 idempotency_result_unavailable`.", "schema": { "type": "string", "enum": [ "true", "false" ] }, "example": "true" } } }, "paths": { "/parts/intelligence": { "get": { "tags": [ "Intelligence" ], "x-intelligence-group": "parts-market", "operationId": "resolvePartIntelligence", "summary": "Resolves part identifiers to a part cluster and returns intelligence", "description": "**Service description**\n\nAt 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\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.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose.", "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.", "schema": { "type": "string", "minLength": 16, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "oeNumber", "in": "query", "description": "OE number used as the entry point into the versioned cluster graph.", "schema": { "type": "string", "minLength": 3, "maxLength": 80 } }, { "name": "oeManufacturer", "in": "query", "description": "Manufacturer namespace of the OE number.", "schema": { "type": "string", "minLength": 1, "maxLength": 120 } }, { "name": "aftermarketNumber", "in": "query", "description": "Aftermarket, MPN or GTIN reference.", "schema": { "type": "string", "minLength": 3, "maxLength": 120 } }, { "name": "aftermarketManufacturer", "in": "query", "description": "Manufacturer or namespace of the aftermarket reference.", "schema": { "type": "string", "minLength": 1, "maxLength": 120 } }, { "name": "kType", "in": "query", "description": "Optional kType for disambiguation; never an identity anchor on its own.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "natCode", "in": "query", "description": "Optional NatCode for disambiguation; never an identity anchor on its own.", "schema": { "type": "string", "minLength": 1, "maxLength": 80 } }, { "name": "genArt", "in": "query", "description": "Optional GenArt for classification; never an identity anchor on its own.", "schema": { "type": "string", "minLength": 1, "maxLength": 80 } }, { "name": "marketCountry", "in": "query", "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "default": "DE" } }, { "name": "currency", "in": "query", "schema": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "EUR" } }, { "name": "condition", "in": "query", "schema": { "type": "string", "enum": [ "new", "remanufactured", "used", "unknown" ], "default": "used" } }, { "name": "windowDays", "in": "query", "schema": { "type": "integer", "enum": [ 30, 60, 90, 180, 365 ], "default": 90 } }, { "name": "asOf", "in": "query", "description": "Historical cutoff; the most recent eligible snapshot is used when omitted.", "schema": { "type": "string", "format": "date-time" } }, { "name": "minimumEvidence", "in": "query", "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", "schema": { "type": "string", "enum": [ "any", "directional", "usable", "strong" ], "default": "any" } }, { "name": "freshnessPolicy", "in": "query", "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", "schema": { "type": "string", "enum": [ "allow_stale", "refresh_if_stale", "require_fresh" ], "default": "refresh_if_stale" } } ], "responses": { "200": { "description": "The cluster was resolved; the status may also be `insufficient_evidence`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketIntelligenceClusterIntelligenceResponse" } } }, "headers": { "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" } } }, "202": { "description": "A targeted refresh of a known cluster has been accepted.", "headers": { "Location": { "description": "Status resource for the job.", "schema": { "type": "string", "format": "uri" } }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketIntelligenceAsyncAccepted" }, "example": { "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" } } } }, "400": { "description": "The query, header or JSON body is syntactically invalid.", "content": { "application/json": { "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 } } }, "examples": { "invalid_query_parameter": { "value": { "error": "invalid_query_parameter", "details": { "parameter": "unknown" } } }, "invalid_minimum_evidence": { "value": { "error": "invalid_minimum_evidence" } }, "invalid_idempotency_key": { "value": { "error": "invalid_idempotency_key" } } } } } }, "401": { "description": "The session or API key is missing, invalid or cannot be assigned unambiguously to a pilot account.", "content": { "application/json": { "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 } } }, "examples": { "authentication_required": { "value": { "error": "authentication_required" } } } } } }, "403": { "description": "Pilot access is missing, the session email is unverified, or the CSRF proof is invalid for a session-authenticated POST request.", "content": { "application/json": { "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 } } }, "examples": { "market_intelligence_not_enabled": { "value": { "error": "market_intelligence_not_enabled" } }, "email_not_verified": { "value": { "error": "email_not_verified" } } } } } }, "404": { "description": "No matching identifier, cluster, VIN or job is known.", "content": { "application/json": { "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 } } }, "examples": { "cluster_not_found": { "value": { "error": "cluster_not_found", "message": "No known part cluster matches the requested scope.", "requestId": "ac6cffca-46e4-4fc8-8cd5-601892188c7c" } }, "snapshot_not_found": { "value": { "error": "snapshot_not_found" } } } } } }, "409": { "description": "The Idempotency-Key has already been used for a different business scope.", "content": { "application/json": { "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 } } }, "examples": { "idempotency_key_conflict": { "value": { "error": "idempotency_key_conflict" } } } } } }, "422": { "description": "The input is ambiguous or invalid, or the required evidence tier is missing.", "content": { "application/json": { "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 } } }, "examples": { "identifier_required": { "value": { "error": "identifier_required" } }, "invalid_identifier": { "value": { "error": "invalid_identifier" } }, "invalid_integer": { "value": { "error": "invalid_integer" } }, "invalid_enum": { "value": { "error": "invalid_enum" } }, "invalid_format": { "value": { "error": "invalid_format" } }, "invalid_instant": { "value": { "error": "invalid_instant" } }, "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" ] } } }, "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" ] } } }, "refresh_unavailable": { "value": { "error": "refresh_unavailable" } } } } } }, "429": { "description": "The shared tenant-wide per-minute limit across all API replicas has been reached.", "headers": { "Retry-After": { "description": "Earliest advisable retry interval, in seconds.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "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 } } }, "examples": { "rate_limit_exceeded": { "value": { "error": "rate_limit_exceeded" } } } } } }, "503": { "description": "The intelligence runtime or a required dependency is temporarily unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "market_intelligence_unavailable" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } }, "examples": { "market_intelligence_unavailable": { "value": { "error": "market_intelligence_unavailable" } } } } } } }, "security": [ { "apiKeyAuth": [] }, { "marketIntelligenceSessionCookie": [] } ] } }, "/parts/clusters/{clusterId}/intelligence": { "get": { "tags": [ "Intelligence" ], "x-intelligence-group": "parts-market", "operationId": "getPartClusterIntelligence", "summary": "Returns the current intelligence snapshot for a known part cluster", "description": "**Service description**\n\nReads 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\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.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose.", "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.", "schema": { "type": "string", "minLength": 16, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "clusterId", "in": "path", "required": true, "description": "Stable ID of a part cluster; its composition is versioned separately.", "schema": { "type": "string", "format": "uuid" } }, { "name": "clusterVersion", "in": "query", "description": "Optional historical cluster version; the active version is used when omitted.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "marketCountry", "in": "query", "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "default": "DE" } }, { "name": "currency", "in": "query", "schema": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "EUR" } }, { "name": "condition", "in": "query", "schema": { "type": "string", "enum": [ "new", "remanufactured", "used", "unknown" ], "default": "used" } }, { "name": "windowDays", "in": "query", "schema": { "type": "integer", "enum": [ 30, 60, 90, 180, 365 ], "default": 90 } }, { "name": "asOf", "in": "query", "description": "Historical cutoff; the most recent eligible snapshot is used when omitted.", "schema": { "type": "string", "format": "date-time" } }, { "name": "minimumEvidence", "in": "query", "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", "schema": { "type": "string", "enum": [ "any", "directional", "usable", "strong" ], "default": "any" } }, { "name": "freshnessPolicy", "in": "query", "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", "schema": { "type": "string", "enum": [ "allow_stale", "refresh_if_stale", "require_fresh" ], "default": "refresh_if_stale" } } ], "responses": { "200": { "description": "Materialized cluster intelligence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketIntelligenceClusterIntelligenceResponse" } } }, "headers": { "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" } } }, "202": { "description": "A targeted refresh of a known cluster has been accepted.", "headers": { "Location": { "description": "Status resource for the job.", "schema": { "type": "string", "format": "uri" } }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketIntelligenceAsyncAccepted" }, "example": { "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" } } } }, "400": { "description": "The query, header or JSON body is syntactically invalid.", "content": { "application/json": { "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 } } }, "examples": { "invalid_query_parameter": { "value": { "error": "invalid_query_parameter", "details": { "parameter": "unknown" } } }, "invalid_minimum_evidence": { "value": { "error": "invalid_minimum_evidence" } }, "invalid_idempotency_key": { "value": { "error": "invalid_idempotency_key" } } } } } }, "401": { "description": "The session or API key is missing, invalid or cannot be assigned unambiguously to a pilot account.", "content": { "application/json": { "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 } } }, "examples": { "authentication_required": { "value": { "error": "authentication_required" } } } } } }, "403": { "description": "Pilot access is missing, the session email is unverified, or the CSRF proof is invalid for a session-authenticated POST request.", "content": { "application/json": { "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 } } }, "examples": { "market_intelligence_not_enabled": { "value": { "error": "market_intelligence_not_enabled" } }, "email_not_verified": { "value": { "error": "email_not_verified" } } } } } }, "404": { "description": "No matching identifier, cluster, VIN or job is known.", "content": { "application/json": { "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 } } }, "examples": { "cluster_not_found": { "value": { "error": "cluster_not_found", "message": "No known part cluster matches the requested scope.", "requestId": "ac6cffca-46e4-4fc8-8cd5-601892188c7c" } }, "snapshot_not_found": { "value": { "error": "snapshot_not_found" } } } } } }, "409": { "description": "The Idempotency-Key has already been used for a different business scope.", "content": { "application/json": { "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 } } }, "examples": { "idempotency_key_conflict": { "value": { "error": "idempotency_key_conflict" } } } } } }, "422": { "description": "The input is ambiguous or invalid, or the required evidence tier is missing.", "content": { "application/json": { "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 } } }, "examples": { "invalid_integer": { "value": { "error": "invalid_integer" } }, "invalid_enum": { "value": { "error": "invalid_enum" } }, "invalid_format": { "value": { "error": "invalid_format" } }, "invalid_instant": { "value": { "error": "invalid_instant" } }, "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" ] } } }, "refresh_unavailable": { "value": { "error": "refresh_unavailable" } } } } } }, "429": { "description": "The shared tenant-wide per-minute limit across all API replicas has been reached.", "headers": { "Retry-After": { "description": "Earliest advisable retry interval, in seconds.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "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 } } }, "examples": { "rate_limit_exceeded": { "value": { "error": "rate_limit_exceeded" } } } } } }, "503": { "description": "The intelligence runtime or a required dependency is temporarily unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "market_intelligence_unavailable" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } }, "examples": { "market_intelligence_unavailable": { "value": { "error": "market_intelligence_unavailable" } } } } } } }, "security": [ { "apiKeyAuth": [] }, { "marketIntelligenceSessionCookie": [] } ] } }, "/parts/clusters/{clusterId}/history": { "get": { "tags": [ "Intelligence" ], "x-intelligence-group": "parts-market", "operationId": "getPartClusterIntelligenceHistory", "summary": "Returns versioned historical intelligence snapshots", "description": "**Service description**\n\nHistorical 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\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.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose.", "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.", "schema": { "type": "string", "minLength": 16, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "clusterId", "in": "path", "required": true, "description": "Stable ID of a part cluster; its composition is versioned separately.", "schema": { "type": "string", "format": "uuid" } }, { "name": "marketCountry", "in": "query", "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "default": "DE" } }, { "name": "currency", "in": "query", "schema": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "EUR" } }, { "name": "condition", "in": "query", "schema": { "type": "string", "enum": [ "new", "remanufactured", "used", "unknown" ], "default": "used" } }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "granularity", "in": "query", "schema": { "type": "string", "enum": [ "day", "week", "month" ], "default": "week" } }, { "name": "restated", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "minimumEvidence", "in": "query", "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", "schema": { "type": "string", "enum": [ "any", "directional", "usable", "strong" ], "default": "any" } } ], "responses": { "200": { "description": "Historical, versioned snapshot series.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketIntelligenceClusterHistoryResponse" } } }, "headers": { "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" } } }, "400": { "description": "The query, header or JSON body is syntactically invalid.", "content": { "application/json": { "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 } } }, "examples": { "invalid_query_parameter": { "value": { "error": "invalid_query_parameter", "details": { "parameter": "unknown" } } }, "invalid_minimum_evidence": { "value": { "error": "invalid_minimum_evidence" } }, "invalid_idempotency_key": { "value": { "error": "invalid_idempotency_key" } } } } } }, "401": { "description": "The session or API key is missing, invalid or cannot be assigned unambiguously to a pilot account.", "content": { "application/json": { "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 } } }, "examples": { "authentication_required": { "value": { "error": "authentication_required" } } } } } }, "403": { "description": "Pilot access is missing, the session email is unverified, or the CSRF proof is invalid for a session-authenticated POST request.", "content": { "application/json": { "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 } } }, "examples": { "market_intelligence_not_enabled": { "value": { "error": "market_intelligence_not_enabled" } }, "email_not_verified": { "value": { "error": "email_not_verified" } } } } } }, "404": { "description": "No matching identifier, cluster, VIN or job is known.", "content": { "application/json": { "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 } } }, "examples": { "cluster_not_found": { "value": { "error": "cluster_not_found", "message": "No known part cluster matches the requested scope.", "requestId": "ac6cffca-46e4-4fc8-8cd5-601892188c7c" } } } } } }, "409": { "description": "The Idempotency-Key has already been used for a different business scope.", "content": { "application/json": { "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 } } }, "examples": { "idempotency_key_conflict": { "value": { "error": "idempotency_key_conflict" } } } } } }, "422": { "description": "The input is ambiguous or invalid, or the required evidence tier is missing.", "content": { "application/json": { "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 } } }, "examples": { "invalid_format": { "value": { "error": "invalid_format" } }, "invalid_enum": { "value": { "error": "invalid_enum" } }, "invalid_date": { "value": { "error": "invalid_date" } }, "invalid_boolean": { "value": { "error": "invalid_boolean" } }, "invalid_history_window": { "value": { "error": "invalid_history_window" } }, "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" ] } } } } } } }, "429": { "description": "The shared tenant-wide per-minute limit across all API replicas has been reached.", "headers": { "Retry-After": { "description": "Earliest advisable retry interval, in seconds.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "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 } } }, "examples": { "rate_limit_exceeded": { "value": { "error": "rate_limit_exceeded" } } } } } }, "503": { "description": "The intelligence runtime or a required dependency is temporarily unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "market_intelligence_unavailable" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } }, "examples": { "market_intelligence_unavailable": { "value": { "error": "market_intelligence_unavailable" } } } } } } }, "security": [ { "apiKeyAuth": [] }, { "marketIntelligenceSessionCookie": [] } ] } }, "/parts/intelligence/jobs/{jobId}": { "get": { "tags": [ "Intelligence" ], "x-intelligence-group": "parts-market", "operationId": "getPartIntelligenceJob", "summary": "Retrieves a cluster refresh", "description": "**Service description**\n\nA 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\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.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose.", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The cluster refresh is complete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketIntelligenceClusterIntelligenceResponse" } } }, "headers": { "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" } } }, "202": { "description": "A targeted refresh of a known cluster has been accepted.", "headers": { "Location": { "description": "Status resource for the job.", "schema": { "type": "string", "format": "uri" } }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketIntelligenceAsyncAccepted" }, "example": { "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" } } } }, "400": { "description": "The query, header or JSON body is syntactically invalid.", "content": { "application/json": { "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 } } }, "examples": { "invalid_query_parameter": { "value": { "error": "invalid_query_parameter", "details": { "parameter": "unknown" } } } } } } }, "401": { "description": "The session or API key is missing, invalid or cannot be assigned unambiguously to a pilot account.", "content": { "application/json": { "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 } } }, "examples": { "authentication_required": { "value": { "error": "authentication_required" } } } } } }, "403": { "description": "Pilot access is missing, the session email is unverified, or the CSRF proof is invalid for a session-authenticated POST request.", "content": { "application/json": { "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 } } }, "examples": { "market_intelligence_not_enabled": { "value": { "error": "market_intelligence_not_enabled" } }, "email_not_verified": { "value": { "error": "email_not_verified" } } } } } }, "404": { "description": "No matching identifier, cluster, VIN or job is known.", "content": { "application/json": { "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 } } }, "examples": { "job_not_found": { "value": { "error": "job_not_found" } }, "snapshot_not_found": { "value": { "error": "snapshot_not_found" } }, "cluster_not_found": { "value": { "error": "cluster_not_found", "message": "No known part cluster matches the requested scope.", "requestId": "ac6cffca-46e4-4fc8-8cd5-601892188c7c" } } } } } }, "422": { "description": "The input is ambiguous or invalid, or the required evidence tier is missing.", "content": { "application/json": { "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 } } }, "examples": { "intelligence_job_failed": { "value": { "error": "intelligence_job_failed" } }, "refresh_timeout": { "value": { "error": "refresh_timeout" } }, "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" ] } } }, "refresh_failed": { "value": { "error": "refresh_failed" } }, "refresh_completed_without_snapshot": { "value": { "error": "refresh_completed_without_snapshot" } }, "refresh_job_missing": { "value": { "error": "refresh_job_missing" } } } } } }, "429": { "description": "The shared tenant-wide per-minute limit across all API replicas has been reached.", "headers": { "Retry-After": { "description": "Earliest advisable retry interval, in seconds.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "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 } } }, "examples": { "rate_limit_exceeded": { "value": { "error": "rate_limit_exceeded" } } } } } }, "503": { "description": "The intelligence runtime or a required dependency is temporarily unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "market_intelligence_unavailable" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } }, "examples": { "market_intelligence_unavailable": { "value": { "error": "market_intelligence_unavailable" } } } } } } }, "security": [ { "apiKeyAuth": [] }, { "marketIntelligenceSessionCookie": [] } ] } }, "/vin/economic-intelligence": { "post": { "tags": [ "Intelligence" ], "x-intelligence-group": "vehicle-economics", "operationId": "createVinEconomicIntelligence", "summary": "Aggregates vehicle-specific part candidates across part clusters into Economic Intelligence", "description": "**Service description**\n\nPipeline: 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.\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.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended 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.", "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.", "schema": { "type": "string", "minLength": 16, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, { "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.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketIntelligenceVinEconomicIntelligenceRequest" } } } }, "responses": { "200": { "description": "Complete or partial VIN Economic Intelligence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketIntelligenceVinEconomicIntelligenceResponse" } } }, "headers": { "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" } } }, "202": { "description": "Vehicle-specific parts determination or intelligence aggregation is running asynchronously.", "headers": { "Location": { "description": "Status resource for the job.", "schema": { "type": "string", "format": "uri" } }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketIntelligenceAsyncAccepted" }, "example": { "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" } } } }, "400": { "description": "The query, header or JSON body is syntactically invalid.", "content": { "application/json": { "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 } } }, "examples": { "invalid_query_parameter": { "value": { "error": "invalid_query_parameter", "details": { "parameter": "unknown" } } }, "invalid_request_property": { "value": { "error": "invalid_request_property" } }, "invalid_json": { "value": { "error": "invalid_json" } }, "invalid_json_object": { "value": { "error": "invalid_json_object" } }, "invalid_minimum_evidence": { "value": { "error": "invalid_minimum_evidence" } }, "invalid_idempotency_key": { "value": { "error": "invalid_idempotency_key" } } } } } }, "401": { "description": "The session or API key is missing, invalid or cannot be assigned unambiguously to a pilot account.", "content": { "application/json": { "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 } } }, "examples": { "authentication_required": { "value": { "error": "authentication_required" } } } } } }, "403": { "description": "Pilot access is missing, the session email is unverified, or the CSRF proof is invalid for a session-authenticated POST request.", "content": { "application/json": { "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 } } }, "examples": { "market_intelligence_not_enabled": { "value": { "error": "market_intelligence_not_enabled" } }, "invalid_csrf": { "value": { "error": "invalid_csrf" } }, "email_not_verified": { "value": { "error": "email_not_verified" } } } } } }, "404": { "description": "No matching identifier, cluster, VIN or job is known.", "content": { "application/json": { "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 } } }, "examples": { "vin_not_found": { "value": { "error": "vin_not_found", "message": "No vehicle parts result is available for this VIN.", "requestId": "8d918ef4-627b-4c66-a558-403b0e326355" } } } } } }, "409": { "description": "The Idempotency-Key has already been used for a different business scope.", "content": { "application/json": { "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 } } }, "examples": { "idempotency_key_conflict": { "value": { "error": "idempotency_key_conflict" } } } } } }, "413": { "description": "The JSON body exceeds the pilot limit of 32 KiB.", "content": { "application/json": { "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 } } }, "examples": { "request_body_too_large": { "value": { "error": "request_body_too_large" } } } } } }, "415": { "description": "The VIN request must be sent as `application/json`.", "content": { "application/json": { "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 } } }, "examples": { "unsupported_media_type": { "value": { "error": "unsupported_media_type" } } } } } }, "422": { "description": "The input is ambiguous or invalid, or the required evidence tier is missing.", "content": { "application/json": { "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 } } }, "examples": { "invalid_vin": { "value": { "error": "invalid_vin" } }, "invalid_format": { "value": { "error": "invalid_format" } }, "invalid_enum": { "value": { "error": "invalid_enum" } }, "invalid_instant": { "value": { "error": "invalid_instant" } }, "invalid_integer": { "value": { "error": "invalid_integer" } }, "invalid_string": { "value": { "error": "invalid_string" } }, "invalid_boolean": { "value": { "error": "invalid_boolean" } } } } } }, "429": { "description": "The shared tenant-wide per-minute limit across all API replicas has been reached.", "headers": { "Retry-After": { "description": "Earliest advisable retry interval, in seconds.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "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 } } }, "examples": { "rate_limit_exceeded": { "value": { "error": "rate_limit_exceeded" } } } } } }, "502": { "description": "The vehicle-specific parts determination could not be completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_vehicle_parts_response" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } }, "examples": { "invalid_vehicle_parts_response": { "value": { "error": "invalid_vehicle_parts_response" } } } } } }, "503": { "description": "VIN Intelligence is safely disabled or vehicle-specific parts determination is unavailable.", "content": { "application/json": { "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" } } }, "examples": { "market_intelligence_vin_not_enabled": { "value": { "error": "market_intelligence_vin_not_enabled" } }, "vehicle_parts_unavailable": { "value": { "error": "vehicle_parts_unavailable" } }, "market_intelligence_dependency_unavailable": { "value": { "error": "market_intelligence_dependency_unavailable" } }, "market_intelligence_unavailable": { "value": { "error": "market_intelligence_unavailable" } } } } } } }, "security": [ { "apiKeyAuth": [] }, { "marketIntelligenceSessionCookie": [] } ] } }, "/vin/economic-intelligence/jobs/{jobId}": { "get": { "tags": [ "Intelligence" ], "x-intelligence-group": "vehicle-economics", "operationId": "getVinEconomicIntelligenceJob", "summary": "Retrieves the status or result of a VIN intelligence job", "description": "**Service description**\n\nRetrieves 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`.\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.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended 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.", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The job is complete; the result is available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketIntelligenceVinEconomicIntelligenceResponse" } } }, "headers": { "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" } } }, "202": { "description": "Vehicle-specific parts determination or intelligence aggregation is running asynchronously.", "headers": { "Location": { "description": "Status resource for the job.", "schema": { "type": "string", "format": "uri" } }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketIntelligenceAsyncAccepted" }, "example": { "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" } } } }, "400": { "description": "The query, header or JSON body is syntactically invalid.", "content": { "application/json": { "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 } } }, "examples": { "invalid_query_parameter": { "value": { "error": "invalid_query_parameter", "details": { "parameter": "unknown" } } } } } } }, "401": { "description": "The session or API key is missing, invalid or cannot be assigned unambiguously to a pilot account.", "content": { "application/json": { "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 } } }, "examples": { "authentication_required": { "value": { "error": "authentication_required" } } } } } }, "403": { "description": "Pilot access is missing, the session email is unverified, or the CSRF proof is invalid for a session-authenticated POST request.", "content": { "application/json": { "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 } } }, "examples": { "market_intelligence_not_enabled": { "value": { "error": "market_intelligence_not_enabled" } }, "email_not_verified": { "value": { "error": "email_not_verified" } } } } } }, "404": { "description": "No matching identifier, cluster, VIN or job is known.", "content": { "application/json": { "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 } } }, "examples": { "job_not_found": { "value": { "error": "job_not_found" } }, "vin_not_found": { "value": { "error": "vin_not_found", "message": "No vehicle parts result is available for this VIN.", "requestId": "8d918ef4-627b-4c66-a558-403b0e326355" } } } } } }, "422": { "description": "The input is ambiguous or invalid, or the required evidence tier is missing.", "content": { "application/json": { "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 } } }, "examples": { "vin_intelligence_failed": { "value": { "error": "vin_intelligence_failed" } } } } } }, "429": { "description": "The shared tenant-wide per-minute limit across all API replicas has been reached.", "headers": { "Retry-After": { "description": "Earliest advisable retry interval, in seconds.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "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 } } }, "examples": { "rate_limit_exceeded": { "value": { "error": "rate_limit_exceeded" } } } } } }, "502": { "description": "The vehicle-specific parts determination could not be completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_vehicle_parts_response" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } }, "examples": { "invalid_vehicle_parts_response": { "value": { "error": "invalid_vehicle_parts_response" } } } } } }, "503": { "description": "VIN Intelligence is safely disabled or vehicle-specific parts determination is unavailable.", "content": { "application/json": { "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" } } }, "examples": { "market_intelligence_vin_not_enabled": { "value": { "error": "market_intelligence_vin_not_enabled" } }, "vehicle_parts_unavailable": { "value": { "error": "vehicle_parts_unavailable" } }, "market_intelligence_dependency_unavailable": { "value": { "error": "market_intelligence_dependency_unavailable" } }, "market_intelligence_unavailable": { "value": { "error": "market_intelligence_unavailable" } } } } } } }, "security": [ { "apiKeyAuth": [] }, { "marketIntelligenceSessionCookie": [] } ] } }, "/ping": { "get": { "tags": [ "System" ], "summary": "Check system status", "responses": { "200": { "description": "API system status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" }, "examples": { "documented": { "value": { "status": "ok", "service": "tapinoma hub" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "GetSystemStatus400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "example": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "GetSystemStatus401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "GetSystemStatus403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "invalid_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "GetSystemStatus500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "GetSystemStatus503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } } } }, "description": "**Service description**\n\nChecks API availability and returns a compact technical status. The endpoint performs no business data query.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose.", "operationId": "getSystemStatus" } }, "/client/users": { "get": { "tags": [ "Client Admin" ], "summary": "List sub-users of the current master client", "responses": { "200": { "description": "Sub-user list", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/ClientUser" } } } }, "examples": { "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" } ] } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "ListClientUsers400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "example": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "ListClientUsers401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "403": { "description": "Only master clients may manage sub-users", "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } }, "content": { "application/json": { "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" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "forbidden": { "summary": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "ListClientUsers500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "ListClientUsers503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } } } }, "description": "**Service description**\n\nReturns the authenticated master client’s managed sub-users and the status required for administration.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose.", "operationId": "listClientUsers" }, "post": { "tags": [ "Client Admin" ], "summary": "Create a sub-user with an initial API key", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientUserCreateRequest" }, "example": { "name": "Werkstatt Nord GmbH", "defaultProviderId": 1, "isActive": true, "applicationLabel": "erp-connector", "rateLimits": [ { "endpointKey": "vin.vehicle", "windowSeconds": 60, "maxRequests": 120, "isActive": true } ] } } } }, "responses": { "201": { "description": "Sub-user created; the raw API key is returned once", "content": { "application/json": { "schema": { "type": "object", "required": [ "user", "apiKey" ], "properties": { "user": { "$ref": "#/components/schemas/ClientUser" }, "apiKey": { "$ref": "#/components/schemas/ApiKeyCreateResponse" } } }, "examples": { "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" } } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } }, "content": { "application/json": { "schema": { "title": "CreateClientUser400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "idempotency_key_not_supported": { "summary": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } } } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "CreateClientUser401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "403": { "description": "Only master clients may manage sub-users", "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } }, "content": { "application/json": { "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" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "forbidden": { "summary": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "title": "CreateClientUser404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" } } }, "example": { "error": "not_found", "message": "No record matches the given identifier" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "CreateClientUser500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "CreateClientUser503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } } } }, "description": "**Service description**\n\nCreate a sub-user with an initial API key. The request and response follow the schemas documented below.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose.", "operationId": "createClientUser" } }, "/client/users/{clientId}": { "patch": { "tags": [ "Client Admin" ], "summary": "Update or deactivate a sub-user", "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Unique ID of a managed sub-user.", "example": 4711 }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientUserUpdateRequest" }, "example": { "name": "Werkstatt Nord GmbH & Co. KG", "isActive": true, "defaultProviderId": 2 } } } }, "responses": { "200": { "description": "Sub-user updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "user" ], "properties": { "user": { "$ref": "#/components/schemas/ClientUser" } } }, "examples": { "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" } } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "UpdateClientUser400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "example": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "UpdateClientUser401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "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" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "forbidden": { "summary": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "404": { "description": "Sub-user not found", "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } }, "content": { "application/json": { "schema": { "title": "UpdateClientUser404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" } } }, "example": { "error": "not_found", "message": "No record matches the given identifier" } } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "UpdateClientUser500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "UpdateClientUser503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } } } }, "description": "**Service description**\n\nChanges permitted master data or the active status of a managed sub-user.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose.", "operationId": "updateClientUser" } }, "/client/users/{clientId}/keys": { "post": { "tags": [ "Client Admin" ], "summary": "Create another API key for a sub-user", "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Unique ID of a managed sub-user.", "example": 4711 } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreateRequest" }, "example": { "label": "erp-connector-2" } } } }, "responses": { "201": { "description": "API key created", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "$ref": "#/components/schemas/ApiKeyCreateResponse" } } }, "examples": { "documented": { "value": { "apiKey": { "id": 9822, "label": "erp-connector-2", "key": "tap_7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a09f8e", "createdAt": "2026-08-18T11:20:05+00:00" } } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "CreateClientUserApiKey400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "example": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "CreateClientUserApiKey401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "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" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "forbidden": { "summary": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "title": "CreateClientUserApiKey404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" } } }, "example": { "error": "not_found", "message": "No record matches the given identifier" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "CreateClientUserApiKey500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "CreateClientUserApiKey503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } } } }, "description": "**Service description**\n\nCreate another API key for a sub-user. The request and response follow the schemas documented below.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose.", "operationId": "createClientUserApiKey" } }, "/client/users/{clientId}/rate-limits": { "put": { "tags": [ "Client Admin" ], "summary": "Replace rate limits for a sub-user", "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Unique ID of a managed sub-user.", "example": 4711 }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "rateLimits" ], "properties": { "rateLimits": { "type": "array", "items": { "$ref": "#/components/schemas/RateLimitInput" } } } }, "example": { "rateLimits": [ { "endpointKey": "vin.vehicle", "windowSeconds": 60, "maxRequests": 120, "isActive": true }, { "apiKeyId": 9821, "endpointKey": "parts.oe", "windowSeconds": 3600, "maxRequests": 5000, "isActive": true } ] } } } }, "responses": { "200": { "description": "Rate limits replaced", "content": { "application/json": { "schema": { "type": "object", "properties": { "rateLimits": { "type": "array", "items": { "$ref": "#/components/schemas/RateLimit" } } } }, "examples": { "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" } ] } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "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" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } }, "unsupported_rate_limit_window": { "summary": "unsupported_rate_limit_window", "value": { "error": "unsupported_rate_limit_window", "message": "windowSeconds must be one of the windows the operator defines" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "ReplaceClientUserRateLimits401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "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" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "forbidden": { "summary": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } }, "rate_limit_above_operator_default": { "summary": "rate_limit_above_operator_default", "value": { "error": "rate_limit_above_operator_default", "message": "A rate limit must not exceed the operator default" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "title": "ReplaceClientUserRateLimits404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" } } }, "example": { "error": "not_found", "message": "No record matches the given identifier" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "ReplaceClientUserRateLimits500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "ReplaceClientUserRateLimits503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } } } }, "description": "**Service description**\n\n\\n\\nSets the documented rate limits for a sub-user from the submitted configuration.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose.", "operationId": "replaceClientUserRateLimits" } }, "/client/users/{clientId}/usage": { "get": { "tags": [ "Client Admin" ], "summary": "Get usage and balance for a sub-user", "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Unique ID of a managed sub-user.", "example": 4711 } ], "responses": { "200": { "description": "Usage status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageStatus" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "GetClientUserUsage400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "example": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "GetClientUserUsage401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "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" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "forbidden": { "summary": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "404": { "description": "Sub-user not found", "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } }, "content": { "application/json": { "schema": { "title": "GetClientUserUsage404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" } } }, "example": { "error": "not_found", "message": "No record matches the given identifier" } } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "GetClientUserUsage500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "GetClientUserUsage503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } } } }, "description": "**Service description**\n\nReturns usage, balance and plan consumption for a managed sub-user.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose.", "operationId": "getClientUserUsage" } }, "/client/credits": { "get": { "tags": [ "Client Admin" ], "summary": "Get own balance", "responses": { "200": { "description": "Credit status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditStatus" }, "examples": { "documented": { "value": { "clientId": 1001, "billingMode": "own", "balanceCents": 250000, "balance": "2500.00", "currency": "EUR", "creditLimitCents": 50000, "availableCents": 300000 } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "GetClientCredits400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "example": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "GetClientCredits401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "GetClientCredits403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "GetClientCredits500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "GetClientCredits503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } } } }, "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.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose.", "operationId": "getClientCredits" } }, "/client/usage": { "get": { "tags": [ "Client Admin" ], "summary": "Get own usage and plan consumption", "responses": { "200": { "description": "Usage status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageStatus" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "GetClientUsage400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "example": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "GetClientUsage401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "GetClientUsage403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "GetClientUsage500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "GetClientUsage503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } } } }, "description": "**Service description**\n\nReturns the authenticated client’s current balance, plan consumption and endpoint-specific usage.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose.", "operationId": "getClientUsage" } }, "/vin/redirect-sessions": { "post": { "summary": "Create a browser redirect for the vehicle lookup", "tags": [ "VIN" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinRedirectSessionRequest" }, "example": { "vin": "TAPSANDBX00000001", "returnUrl": "https://client.example/vin/callback", "state": "opaque-client-state" } } } }, "responses": { "201": { "description": "Redirect session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinRedirectSessionResponse" }, "examples": { "sandbox": { "value": { "redirectUrl": "https://redirect.example.invalid/session/sandbox", "expiresAt": "2026-01-01T00:00:00+00:00" } }, "documented": { "value": { "redirectUrl": "https://redirect.example.invalid/session/sandbox", "expiresAt": "2026-01-01T00:10:00+00:00" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid VIN, returnUrl or state", "content": { "application/json": { "schema": { "title": "CreateVinRedirectSession400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "CreateVinRedirectSession401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "CreateVinRedirectSession403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "CreateVinRedirectSession500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "CreateVinRedirectSession503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } } } }, "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.", "operationId": "createVinRedirectSession", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ] } }, "/vin/{vin}/vehicle": { "get": { "summary": "Compare vehicle data by VIN", "tags": [ "VIN" ], "parameters": [ { "name": "vin", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vehicle identification number that the user must be authorised to transmit and process.", "example": "TAPSANDBX00000001" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "default": "de" }, "description": "Two-letter country code used for market and regional context.", "example": "de" }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2, 3 ], "default": 1 }, "description": "Optional numeric selection agreed by contract; the default value is `1`.", "example": 2 }, { "name": "includeEquipments", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "description": "Controls whether determined equipment attributes are returned.", "example": true }, { "name": "includeColors", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "description": "Controls whether determined colour information is returned.", "example": true }, { "name": "includeTechnical", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "description": "Controls whether determined technical data is returned.", "example": true } ], "responses": { "200": { "description": "Determined vehicle data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinVehicleResponse" }, "examples": { "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 } } } } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_not_supported": { "summary": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } }, "invalid_country": { "summary": "invalid_country", "value": { "error": "invalid_country", "message": "country must be a two-letter ISO 3166-1 code" } }, "invalid_provider": { "summary": "invalid_provider", "value": { "error": "invalid_provider", "message": "provider is not a supported selection value" } } } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "GetVehicleByVin401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "GetVehicleByVin403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "404": { "description": "Vehicle not found", "content": { "application/json": { "schema": { "title": "GetVehicleByVin404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found", "vehicle_not_found" ] }, "message": { "type": "string" } } }, "examples": { "not_found": { "summary": "not_found", "value": { "error": "not_found", "message": "No record matches the given identifier" } }, "vehicle_not_found": { "summary": "vehicle_not_found", "value": { "error": "vehicle_not_found", "message": "No vehicle is known for this identifier" } } } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "409": { "description": "Redirect flow required", "content": { "application/json": { "schema": { "title": "GetVehicleByVin409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "redirect_required" ] }, "message": { "type": "string" } } }, "example": { "error": "redirect_required", "message": "The VIN has to be confirmed through a redirect session first" } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "GetVehicleByVin500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "vin_service_unavailable": { "summary": "vin_service_unavailable", "value": { "error": "vin_service_unavailable", "message": "The service is temporarily unavailable." } }, "service_unavailable": { "summary": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "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.", "operationId": "getVehicleByVin" } }, "/vin/{vin}/parts": { "get": { "summary": "Compare parts assignments by VIN", "tags": [ "VIN" ], "parameters": [ { "name": "vin", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vehicle identification number that the user must be authorised to transmit and process.", "example": "TAPSANDBX00000001" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "default": "de" }, "description": "Two-letter country code used for market and regional context.", "example": "de" }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2, 3 ], "default": 1 }, "description": "Optional numeric selection agreed by contract; the default value is `1`.", "example": 1 } ], "responses": { "200": { "description": "Determined VIN parts assignments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinPartsResponse" }, "examples": { "vehicleSpecificBestAvailable": { "summary": "Example 1", "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": [] } ] } }, "vehicleTypeCandidates": { "summary": "Example 2", "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": [] } ] } }, "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" ] } ] } } } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "202": { "description": "Documented HTTP 202 response.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinPartsJobResponse" }, "examples": { "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" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_not_supported": { "summary": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } }, "invalid_country": { "summary": "invalid_country", "value": { "error": "invalid_country", "message": "country must be a two-letter ISO 3166-1 code" } }, "invalid_provider": { "summary": "invalid_provider", "value": { "error": "invalid_provider", "message": "provider is not a supported selection value" } } } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "GetPartsByVin401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "GetPartsByVin403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "title": "GetPartsByVin404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found", "vehicle_not_found" ] }, "message": { "type": "string" } } }, "examples": { "not_found": { "summary": "not_found", "value": { "error": "not_found", "message": "No record matches the given identifier" } }, "vehicle_not_found": { "summary": "vehicle_not_found", "value": { "error": "vehicle_not_found", "message": "No vehicle is known for this identifier" } } } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "409": { "description": "Documented HTTP 409 response.", "content": { "application/json": { "schema": { "title": "GetPartsByVin409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "vin_provider_mismatch" ] }, "message": { "type": "string" } } }, "example": { "error": "vin_provider_mismatch", "message": "The VIN is associated with a different selection value than requested" } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "GetPartsByVin500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "vin_service_unavailable": { "summary": "vin_service_unavailable", "value": { "error": "vin_service_unavailable", "message": "The service is temporarily unavailable." } }, "service_unavailable": { "summary": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "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.", "operationId": "getPartsByVin" } }, "/vin/parts/jobs/{jobId}": { "get": { "summary": "Get the status of a VIN parts lookup", "tags": [ "VIN" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Job ID returned by the associated 202 response.", "example": "6955b900-0100-459b-a0e2-e8fee6b51c20" } ], "responses": { "200": { "description": "Current job status, including the result on success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinPartsJobResponse" }, "examples": { "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" }, "summary": "Sandbox queued response" }, "succeeded": { "summary": "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": [] } ] } } }, "failed": { "summary": "Failed job", "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." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "GetVinPartsJob400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "example": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "GetVinPartsJob401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "GetVinPartsJob403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "404": { "description": "Job not found or not assigned to the authenticated client", "content": { "application/json": { "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" } } }, "examples": { "not_found": { "summary": "not_found", "value": { "error": "not_found", "message": "No record matches the given identifier" } }, "vin_parts_job_not_found": { "summary": "vin_parts_job_not_found", "value": { "error": "vin_parts_job_not_found", "message": "No parts job exists under this jobId" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "GetVinPartsJob500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } }, "vin_service_unavailable": { "summary": "vin_service_unavailable", "value": { "error": "vin_service_unavailable", "message": "The service is temporarily unavailable." } } } } } } }, "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.", "operationId": "getVinPartsJob" } }, "/vin/cart-check": { "post": { "summary": "Check an OE cart against a VIN", "tags": [ "VIN" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinCartCheckRequest" }, "example": { "vin": "TAPSANDBX00000001", "country": "de", "mode": "vehicle", "oeNumbers": [ "SBX0001A", "SBX0002B" ] } } } }, "responses": { "200": { "description": "VIN cart check result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinCartCheckResult" }, "examples": { "completeList": { "summary": "complete=true", "value": { "vin": "WVWZZZ1JZXW000001", "mode": "type", "complete": true, "results": [ { "oe": "1J0807417A", "fits": true }, { "oe": "5Q0919275C", "fits": false } ] } }, "incompleteList": { "summary": "complete=false", "value": { "vin": "WVWZZZ1JZXW000001", "mode": "vehicle", "complete": false, "results": [ { "oe": "1J0807417A", "fits": true }, { "oe": "5Q0919275C", "fits": false } ] } }, "sandbox": { "value": { "vin": "TAPSANDBX00000001", "mode": "type", "complete": true, "results": [] } } } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "202": { "description": "Cart check accepted for processing", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinCartCheckJobResponse" }, "examples": { "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" } } } } } }, "400": { "description": "Invalid VIN, mode or OE list", "content": { "application/json": { "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" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_country": { "summary": "invalid_country", "value": { "error": "invalid_country", "message": "country must be a two-letter ISO 3166-1 code" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } }, "invalid_mode": { "summary": "invalid_mode", "value": { "error": "invalid_mode", "message": "mode must be one of the documented values" } }, "invalid_oe_number": { "summary": "invalid_oe_number", "value": { "error": "invalid_oe_number", "message": "oeNumber must not be empty" } }, "invalid_oe_numbers": { "summary": "invalid_oe_numbers", "value": { "error": "invalid_oe_numbers", "message": "oeNumbers must contain at least one usable number" } }, "invalid_vin": { "summary": "invalid_vin", "value": { "error": "invalid_vin", "message": "vin must be 17 characters and must not contain I, O or Q" } }, "too_many_oe_numbers": { "summary": "too_many_oe_numbers", "value": { "error": "too_many_oe_numbers", "message": "oeNumbers exceeds the maximum number of entries per request" } } } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "CheckVinCart401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "CheckVinCart403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "title": "CheckVinCart404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "vehicle_not_found" ] }, "message": { "type": "string" } } }, "example": { "error": "vehicle_not_found", "message": "No vehicle is known for this identifier" } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "CheckVinCart500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "vin_service_unavailable": { "summary": "vin_service_unavailable", "value": { "error": "vin_service_unavailable", "message": "The service is temporarily unavailable." } }, "service_unavailable": { "summary": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "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.", "operationId": "checkVinCart", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ] } }, "/vin/cart-check/jobs/{jobId}": { "get": { "summary": "Get the status of a VIN cart check", "tags": [ "VIN" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Job ID returned by the associated 202 response.", "example": "6955b900-0200-466b-93c4-5b51907e8d94" } ], "responses": { "200": { "description": "Current job status, including the check result on success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinCartCheckJobResponse" }, "examples": { "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" }, "summary": "Sandbox queued response" }, "failed": { "summary": "Failed job", "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." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "GetVinCartCheckJob400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "example": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "GetVinCartCheckJob401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "GetVinCartCheckJob403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "404": { "description": "Job not found or not assigned to the authenticated client", "content": { "application/json": { "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" } } }, "examples": { "not_found": { "summary": "not_found", "value": { "error": "not_found", "message": "No record matches the given identifier" } }, "vin_cart_check_job_not_found": { "summary": "vin_cart_check_job_not_found", "value": { "error": "vin_cart_check_job_not_found", "message": "No cart check job exists under this jobId" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "GetVinCartCheckJob500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "GetVinCartCheckJob503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } } } }, "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.", "operationId": "getVinCartCheckJob" } }, "/parts/oe/{oeNumber}": { "get": { "summary": "Compare OE part name, fitment, comparison numbers and replacement chain", "tags": [ "Parts" ], "parameters": [ { "name": "oeNumber", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "OE part number compared with available reference information.", "example": "SBX0001A" }, { "name": "manufacturer", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "SANDBOX MOTORS", "description": "Optional manufacturer context for the request." } ], "responses": { "200": { "description": "Determined OE part information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartOeResponse" }, "examples": { "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" ] } } }, "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" ] } } }, "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" ] } } }, "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" ] } } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid OE part number or manufacturer", "content": { "application/json": { "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" } } }, "examples": { "invalid_manufacturer_type": { "summary": "invalid_manufacturer", "value": { "error": "invalid_manufacturer", "message": "manufacturer must be a string" } }, "invalid_manufacturer_length": { "summary": "invalid_manufacturer", "value": { "error": "invalid_manufacturer", "message": "manufacturer must not exceed 100 characters" } }, "invalid_oe_number_length": { "summary": "invalid_oe_number", "value": { "error": "invalid_oe_number", "message": "oeNumber must be between 1 and 128 characters" } }, "invalid_oe_number_format": { "summary": "invalid_oe_number", "value": { "error": "invalid_oe_number", "message": "oeNumber is not a valid OE number" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "GetOePart401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "GetOePart403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "404": { "description": "OE part not found", "content": { "application/json": { "schema": { "title": "GetOePart404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found", "oe_part_not_found" ] }, "message": { "type": "string" } } }, "examples": { "not_found": { "summary": "not_found", "value": { "error": "not_found", "message": "No record matches the given identifier" } }, "oe_part_not_found": { "summary": "oe_part_not_found", "value": { "error": "oe_part_not_found", "message": "No part is known for this OE number" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "422": { "description": "Ambiguous OE part number", "content": { "application/json": { "schema": { "title": "GetOePart422Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "ambiguous_oe_number" ] }, "message": { "type": "string" } } }, "example": { "error": "ambiguous_oe_number", "message": "The OE number could not be resolved uniquely" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "GetOePart500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "parts_service_unavailable": { "summary": "parts_service_unavailable", "value": { "error": "parts_service_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "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.", "operationId": "getOePart" } }, "/parts/oe/{oeNumber}/aftermarket-references": { "get": { "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.", "tags": [ "Parts" ], "parameters": [ { "name": "oeNumber", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "OE part number compared with available reference information.", "example": "SBX0001A" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "example": 100, "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." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "example": 0, "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`." } ], "x-error-codes": [ { "status": 400, "code": "invalid_oe_number", "description": "The OE part number is empty or invalid." }, { "status": 401, "code": "missing_api_key", "description": "The API key header is missing." }, { "status": 402, "code": "insufficient_credits", "description": "The available credit balance is insufficient." }, { "status": 403, "code": "invalid_api_key", "description": "The API key is invalid." }, { "status": 429, "code": "rate_limit_exceeded", "description": "The time-window rate limit was exceeded." }, { "status": 429, "code": "client_request_in_progress", "description": "A request is already being processed for this client." }, { "status": 500, "code": "internal_error", "description": "The public schema defines the meaning and format of `6`." }, { "status": 503, "code": "parts_service_unavailable", "description": "The service is temporarily unavailable." }, { "status": 503, "code": "billing_unavailable", "description": "Billing and rate-limit checks are temporarily unavailable." } ], "responses": { "200": { "description": "Determined aftermarket references", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AftermarketReferencesResponse" }, "examples": { "documented": { "value": { "oeNumber": "6RD615301", "aftermarketReferences": [ { "partNumber": "DF2803", "normalizedPartNumber": "DF2803", "manufacturer": "TRW" }, { "partNumber": "15830C", "normalizedPartNumber": "15830C", "manufacturer": "MAPCO" } ], "count": 2 } }, "sandbox": { "value": { "oeNumber": "SBX0001A", "aftermarketReferences": [], "count": 0 } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid OE part number", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_not_supported": { "summary": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } }, "invalid_oe_number": { "summary": "invalid_oe_number", "value": { "error": "invalid_oe_number", "message": "oeNumber must not be empty" } }, "invalid_query_parameter": { "summary": "invalid_query_parameter", "value": { "error": "invalid_query_parameter", "message": "A query parameter has the wrong type or format" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "GetOeAftermarketReferences401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "GetOeAftermarketReferences403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "title": "GetOeAftermarketReferences404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "oe_part_not_found" ] }, "message": { "type": "string" } } }, "example": { "error": "oe_part_not_found", "message": "No part is known for this OE number" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "GetOeAftermarketReferences500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "parts_service_unavailable": { "summary": "parts_service_unavailable", "value": { "error": "parts_service_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "operationId": "getOeAftermarketReferences" } }, "/parts/oe/{oeNumber}/seo": { "get": { "tags": [ "Parts" ], "operationId": "getPartSeo", "parameters": [ { "name": "oeNumber", "in": "path", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 64 }, "example": "5Q0919275C", "description": "OE part number compared with available reference information." }, { "name": "marketplaceId", "in": "query", "required": false, "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" ] }, "example": "EBAY_DE", "description": "Public parameter `marketplaceId` defined by this schema." }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "de", "en", "fr", "es", "it", "nl", "pl", "zh" ] }, "example": "de", "description": "ISO 639-1 language code for generated content." }, { "name": "vehicleType", "in": "query", "required": false, "schema": { "type": "string", "default": "car", "enum": [ "car", "motorcycle" ] }, "description": "Public parameter `vehicleType` defined by this schema." } ], "responses": { "200": { "description": "Generated SEO data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartSeoResponse" }, "examples": { "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": [] } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Live-Available-At": { "$ref": "#/components/headers/X-Tapinoma-Live-Available-At" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "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" } } }, "examples": { "conflicting_query_parameters": { "summary": "conflicting_query_parameters", "value": { "error": "conflicting_query_parameters", "message": "Two query parameters of this request contradict each other" } }, "idempotency_key_not_supported": { "summary": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } }, "invalid_marketplace_id": { "summary": "invalid_marketplace_id", "value": { "error": "invalid_marketplace_id", "message": "marketplaceId is not a supported marketplace" } }, "invalid_oe_number": { "summary": "invalid_oe_number", "value": { "error": "invalid_oe_number", "message": "oeNumber must not be empty" } }, "invalid_query_parameter": { "summary": "invalid_query_parameter", "value": { "error": "invalid_query_parameter", "message": "A query parameter has the wrong type or format" } }, "unsupported_marketplace_language": { "summary": "unsupported_marketplace_language", "value": { "error": "unsupported_marketplace_language", "message": "The marketplace does not support the requested language" } }, "unsupported_query_parameter": { "summary": "unsupported_query_parameter", "value": { "error": "unsupported_query_parameter", "message": "The request contains a query parameter this endpoint does not accept" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "GetPartSeo401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "GetPartSeo403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "404": { "description": "No exact match was found; commercial treatment follows the terms shown when ordering and agreed in the contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartSeoNoMatchResponse" }, "example": { "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" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Documented HTTP 429 response.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Live-Available-At": { "$ref": "#/components/headers/X-Tapinoma-Live-Available-At" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } }, "content": { "application/json": { "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" } ] }, "example": { "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 } } } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "GetPartSeo500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "seo_service_unavailable": { "summary": "seo_service_unavailable", "value": { "error": "seo_service_unavailable", "message": "The service is temporarily unavailable." } }, "service_unavailable": { "summary": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "summary": "Optimise an eBay or marketplace article (SEO enrichment)", "description": "**Service description**\n\nOptimises 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." } }, "/scanner/document/registration": { "post": { "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.", "tags": [ "Scanner" ], "requestBody": { "required": true, "content": { "application/json": { "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" } } }, "example": { "fileUrl": "https://example.com/registration-document.pdf", "quality": "standard" } } } }, "responses": { "200": { "description": "Vehicle document analysed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationDocumentEnvelopeResponse" }, "examples": { "production": { "summary": "Production response", "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 } } }, "sandbox": { "summary": "Sandbox response", "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 } } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "ExtractRegistrationDocument400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "ExtractRegistrationDocument401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "ExtractRegistrationDocument403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "ExtractRegistrationDocument500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "service_unavailable": { "summary": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "operationId": "extractRegistrationDocument", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ] } }, "/scanner/registration-document": { "post": { "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.", "tags": [ "Scanner" ], "requestBody": { "required": true, "content": { "application/json": { "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" } } }, "example": { "fileUrl": "https://example.com/registration-document.pdf", "quality": "standard" } } } }, "responses": { "200": { "description": "Vehicle document analysed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationDocumentEnvelopeResponse" }, "examples": { "production": { "summary": "Production response", "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 } } }, "sandbox": { "summary": "Sandbox response", "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 } } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "ExtractRegistrationDocumentLegacyPath400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "ExtractRegistrationDocumentLegacyPath401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "ExtractRegistrationDocumentLegacyPath403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "ExtractRegistrationDocumentLegacyPath500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "service_unavailable": { "summary": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "operationId": "extractRegistrationDocumentLegacyPath", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "deprecated": true, "x-successor-path": "/scanner/document/registration", "x-replaced-by": "/scanner/document/registration" } }, "/scanner/document/registration/international": { "post": { "tags": [ "Scanner" ], "operationId": "extractInternationalRegistrationDocument", "requestBody": { "required": true, "content": { "application/json": { "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" } } }, "example": { "fileUrl": "https://example.com/registration-document.pdf", "quality": "standard" } } } }, "responses": { "200": { "description": "Vehicle document analysed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationDocumentV2Response" }, "examples": { "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": [] } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "ExtractInternationalRegistrationDocument400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "ExtractInternationalRegistrationDocument401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "ExtractInternationalRegistrationDocument403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Document analysis failed", "content": { "application/json": { "schema": { "title": "ExtractInternationalRegistrationDocument500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "service_unavailable": { "summary": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "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." } }, "/scanner/registration-document/v2": { "post": { "tags": [ "Scanner" ], "operationId": "extractInternationalRegistrationDocumentLegacyPath", "requestBody": { "required": true, "content": { "application/json": { "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" } } } } } }, "responses": { "200": { "description": "Vehicle document analysed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationDocumentV2Response" }, "examples": { "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": [] } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "ExtractInternationalRegistrationDocumentLegacyPath400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "ExtractInternationalRegistrationDocumentLegacyPath401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "ExtractInternationalRegistrationDocumentLegacyPath403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Document analysis failed", "content": { "application/json": { "schema": { "title": "ExtractInternationalRegistrationDocumentLegacyPath500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "service_unavailable": { "summary": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "deprecated": true, "x-successor-path": "/scanner/document/registration/international", "x-replaced-by": "/scanner/document/registration/international", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "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." } }, "/scanner/label/basic": { "post": { "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.", "tags": [ "Scanner" ], "requestBody": { "required": true, "content": { "application/json": { "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" } } }, "example": { "imageUrl": "https://example.com/label.jpg", "quality": "standard" } } } }, "responses": { "200": { "description": "Basic label analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelBasicResponse" }, "examples": { "sandbox": { "value": { "hasPartNumber": true, "where": { "onLabel": false, "onPart": false } } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "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" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } }, "invalid_json": { "summary": "invalid_json", "value": { "error": "invalid_json", "message": "The request body is not valid JSON" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "ExtractLabelText401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "ExtractLabelText403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "ExtractLabelText500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "service_unavailable": { "summary": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "operationId": "extractLabelText", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ] } }, "/scanner/label/extract-partnumbers": { "post": { "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.", "tags": [ "Scanner" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelExtractPartNumbersRequest" }, "example": { "imageUrl": "https://example.com/label.jpg", "quality": "enhanced" } } } }, "responses": { "200": { "description": "Extracted part numbers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelExtractPartNumbersResponse" }, "examples": { "production": { "summary": "Production response", "value": { "partNumbers": [ "5Q0959655AA", "3G0907530AC" ] } }, "sandbox": { "summary": "Sandbox response", "value": { "partNumbers": [ "SBX0001A", "SBX0002B" ] } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "ExtractLabelPartNumbers400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "ExtractLabelPartNumbers401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "ExtractLabelPartNumbers403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "ExtractLabelPartNumbers500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "service_unavailable": { "summary": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "operationId": "extractLabelPartNumbers", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ] } }, "/scanner/label/extract-all": { "post": { "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.", "tags": [ "Scanner" ], "requestBody": { "required": true, "content": { "application/json": { "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" ] } ] }, "example": { "imageUrl": "https://example.com/label.jpg", "quality": "maximum" } } } }, "responses": { "200": { "description": "Full label extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelExtractAllEnvelopeResponse" }, "examples": { "production": { "summary": "Production response", "value": { "status": "ok", "data": { "primaryPartNumber": "5Q0959655AA", "otherPartNumbers": [ "3G0907530AC" ], "manufacturer": "Continental", "notes": [ "12 V" ] } } }, "sandbox": { "summary": "Sandbox response", "value": { "status": "ok", "data": { "primaryPartNumber": "SBX0001A", "otherPartNumbers": [ "SBX0002B" ], "manufacturer": "Sandbox Motors", "notes": [ "sandbox_fixture" ] } } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "ExtractLabelDetails400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "ExtractLabelDetails401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "ExtractLabelDetails403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "ExtractLabelDetails500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "service_unavailable": { "summary": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "operationId": "extractLabelDetails", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ] } }, "/scanner/document/calculation": { "post": { "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.", "operationId": "extractCalculationDocument", "tags": [ "Scanner" ], "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "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" } } }, "example": { "fileUrl": "https://example.com/gutachten.pdf", "quality": "standard" } } } }, "responses": { "200": { "description": "Document analysed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentCalculationResponse" }, "examples": { "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" ] } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "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" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } }, "invalid_request": { "summary": "invalid_request", "value": { "error": "invalid_request", "message": "The request is missing a required field" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key missing or invalid", "content": { "application/json": { "schema": { "title": "ExtractCalculationDocument401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "ExtractCalculationDocument403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Document analysis failed", "content": { "application/json": { "schema": { "title": "ExtractCalculationDocument500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "ExtractCalculationDocument503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "x-use-when": [ "Calculation totals or a repair assessment are required.", "Spare-parts, labour or paint line items are required.", "Documented equipment must be returned together with calculation data." ], "x-avoid-when": "Do not use for a rich vehicle record with powertrain, transmission, energy, colours or identifiers.", "x-alternative-operation": "extractVehicleDocument" } }, "/scanner/document/extract": { "post": { "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.", "operationId": "extractDocument", "tags": [ "Scanner" ], "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "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" } } }, "example": { "fileUrl": "https://example.com/gutachten.pdf", "quality": "standard" } } } }, "responses": { "200": { "description": "Document analysed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentExtractionResponse" }, "examples": { "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" ] } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "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" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } }, "invalid_request": { "summary": "invalid_request", "value": { "error": "invalid_request", "message": "The request is missing a required field" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key missing or invalid", "content": { "application/json": { "schema": { "title": "ExtractDocument401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "ExtractDocument403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Document analysis failed", "content": { "application/json": { "schema": { "title": "ExtractDocument500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "ExtractDocument503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "deprecated": true, "x-successor-path": "/scanner/document/calculation", "x-replaced-by": "/scanner/document/calculation" } }, "/scanner/document/vehicle": { "post": { "tags": [ "Scanner" ], "operationId": "extractVehicleDocument", "requestBody": { "required": true, "content": { "application/json": { "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`." } } }, "example": { "fileUrl": "https://example.com/vehicle-order.pdf", "quality": "standard", "includeSensitiveData": false } } } }, "responses": { "200": { "description": "Document analysed successfully", "headers": { "Cache-Control": { "description": "The public schema defines the meaning and format of `Cache-Control`.", "schema": { "type": "string", "enum": [ "no-store" ] }, "example": "no-store" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleDocumentExtractionResponse" }, "examples": { "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": [] } }, "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": [] } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "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" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "idempotency_key_not_supported": { "summary": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } }, "invalid_request": { "summary": "invalid_request", "value": { "error": "invalid_request", "message": "The request is missing a required field" } } } } }, "headers": { "Cache-Control": { "description": "The public schema defines the meaning and format of `Cache-Control`.", "schema": { "type": "string", "enum": [ "no-store" ] }, "example": "no-store" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "ExtractVehicleDocument401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } }, "headers": { "Cache-Control": { "description": "The public schema defines the meaning and format of `Cache-Control`.", "schema": { "type": "string", "enum": [ "no-store" ] }, "example": "no-store" } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "Cache-Control": { "description": "The public schema defines the meaning and format of `Cache-Control`.", "schema": { "type": "string", "enum": [ "no-store" ] }, "example": "no-store" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "ExtractVehicleDocument403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } }, "headers": { "Cache-Control": { "description": "The public schema defines the meaning and format of `Cache-Control`.", "schema": { "type": "string", "enum": [ "no-store" ] }, "example": "no-store" } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Cache-Control": { "description": "The public schema defines the meaning and format of `Cache-Control`.", "schema": { "type": "string", "enum": [ "no-store" ] }, "example": "no-store" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Cache-Control": { "description": "The public schema defines the meaning and format of `Cache-Control`.", "schema": { "type": "string", "enum": [ "no-store" ] }, "example": "no-store" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Document analysis failed", "content": { "application/json": { "schema": { "title": "ExtractVehicleDocument500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "Cache-Control": { "description": "The public schema defines the meaning and format of `Cache-Control`.", "schema": { "type": "string", "enum": [ "no-store" ] }, "example": "no-store" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "ExtractVehicleDocument503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } } } } }, "headers": { "Cache-Control": { "description": "The public schema defines the meaning and format of `Cache-Control`.", "schema": { "type": "string", "enum": [ "no-store" ] }, "example": "no-store" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "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.", "x-use-when": [ "A rich vehicle record with powertrain, transmission, energy, colours or identifiers is required.", "Documented equipment or optional sensitive document data is required." ], "x-avoid-when": "Do not use when calculation totals, repair assessment, parts, labour or paint line items are required.", "x-alternative-operation": "extractCalculationDocument" } }, "/scanner/vehicle-document/extract": { "post": { "tags": [ "Scanner" ], "operationId": "extractVehicleDocumentLegacyPath", "requestBody": { "required": true, "content": { "application/json": { "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`." } } } } } }, "responses": { "200": { "description": "Document analysed successfully", "headers": { "Cache-Control": { "description": "The public schema defines the meaning and format of `Cache-Control`.", "schema": { "type": "string", "enum": [ "no-store" ] }, "example": "no-store" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleDocumentExtractionResponse" }, "examples": { "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": [] } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "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" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "idempotency_key_not_supported": { "summary": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } }, "invalid_request": { "summary": "invalid_request", "value": { "error": "invalid_request", "message": "The request is missing a required field" } } } } }, "headers": { "Cache-Control": { "description": "The public schema defines the meaning and format of `Cache-Control`.", "schema": { "type": "string", "enum": [ "no-store" ] }, "example": "no-store" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "ExtractVehicleDocumentLegacyPath401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } }, "headers": { "Cache-Control": { "description": "The public schema defines the meaning and format of `Cache-Control`.", "schema": { "type": "string", "enum": [ "no-store" ] }, "example": "no-store" } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "Cache-Control": { "description": "The public schema defines the meaning and format of `Cache-Control`.", "schema": { "type": "string", "enum": [ "no-store" ] }, "example": "no-store" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "ExtractVehicleDocumentLegacyPath403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } }, "headers": { "Cache-Control": { "description": "The public schema defines the meaning and format of `Cache-Control`.", "schema": { "type": "string", "enum": [ "no-store" ] }, "example": "no-store" } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Cache-Control": { "description": "The public schema defines the meaning and format of `Cache-Control`.", "schema": { "type": "string", "enum": [ "no-store" ] }, "example": "no-store" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Cache-Control": { "description": "The public schema defines the meaning and format of `Cache-Control`.", "schema": { "type": "string", "enum": [ "no-store" ] }, "example": "no-store" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Document analysis failed", "content": { "application/json": { "schema": { "title": "ExtractVehicleDocumentLegacyPath500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "Cache-Control": { "description": "The public schema defines the meaning and format of `Cache-Control`.", "schema": { "type": "string", "enum": [ "no-store" ] }, "example": "no-store" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "ExtractVehicleDocumentLegacyPath503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } } } } }, "headers": { "Cache-Control": { "description": "The public schema defines the meaning and format of `Cache-Control`.", "schema": { "type": "string", "enum": [ "no-store" ] }, "example": "no-store" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "deprecated": true, "x-successor-path": "/scanner/document/vehicle", "x-replaced-by": "/scanner/document/vehicle", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "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." } }, "/translation/translations": { "get": { "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.", "tags": [ "Translation" ], "parameters": [ { "name": "sourceLanguage", "in": "query", "required": true, "description": "Language of the single submitted part designation.", "schema": { "type": "string", "maxLength": 20, "example": "de" }, "example": "de" }, { "name": "text", "in": "query", "required": true, "description": "Exactly one individual part designation. No titles, sentences, descriptions, lists or multiple part designations.", "schema": { "type": "string", "maxLength": 1000, "example": "Bremsscheibe" }, "example": "Stoßfänger vorne" } ], "responses": { "200": { "description": "Part designation translations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationResponse" }, "examples": { "sandbox": { "value": { "en": "Sandbox front bumper", "fr": "Pare-chocs avant sandbox", "es": "Parachoques delantero sandbox", "it": "Paraurti anteriore sandbox" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_not_supported": { "summary": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } }, "source_language_required": { "summary": "source_language_required", "value": { "error": "source_language_required", "message": "sourceLanguage is required because the text language could not be detected" } }, "source_language_too_long": { "summary": "source_language_too_long", "value": { "error": "source_language_too_long", "message": "sourceLanguage must be a two-letter language code" } }, "text_required": { "summary": "text_required", "value": { "error": "text_required", "message": "text must not be empty" } }, "text_too_long": { "summary": "text_too_long", "value": { "error": "text_too_long", "message": "text exceeds the maximum length for this endpoint" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "TranslatePartName401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "TranslatePartName403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "TranslatePartName500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "service_unavailable": { "summary": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "operationId": "translatePartName" } }, "/client/plans": { "get": { "tags": [ "Client Admin" ], "summary": "List available standard and custom plans", "responses": { "200": { "description": "Plan list", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "ListPlans400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "example": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "ListPlans401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "403": { "description": "Only master clients may manage plans", "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } }, "content": { "application/json": { "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" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "forbidden": { "summary": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } }, "sandbox_endpoint_unavailable": { "summary": "sandbox_endpoint_unavailable", "value": { "error": "sandbox_endpoint_unavailable", "message": "This endpoint has no sandbox fixture; use a production key" } } } } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "ListPlans500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "ListPlans503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } } } }, "description": "**Service description**\n\nReturns the standard and custom plans visible to the authenticated master client, including endpoint configuration.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose.", "operationId": "listPlans" } }, "/client/sponsorship-grants": { "get": { "tags": [ "Client Admin" ], "operationId": "listSponsorshipGrants", "responses": { "200": { "description": "Sponsorship grants", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SponsorshipGrantListResponse" }, "examples": { "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" } ] } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "ListSponsorshipGrants400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "example": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "ListSponsorshipGrants401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "403": { "description": "Not authorised to manage outgoing grants", "content": { "application/json": { "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" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "forbidden": { "summary": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } }, "sandbox_endpoint_unavailable": { "summary": "sandbox_endpoint_unavailable", "value": { "error": "sandbox_endpoint_unavailable", "message": "This endpoint has no sandbox fixture; use a production key" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "title": "ListSponsorshipGrants404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" } } }, "example": { "error": "not_found", "message": "No record matches the given identifier" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "ListSponsorshipGrants500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "ListSponsorshipGrants503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } } } }, "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.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose." } }, "/client/sponsorship-grants/received": { "get": { "tags": [ "Client Admin" ], "operationId": "listReceivedSponsorshipGrants", "responses": { "200": { "description": "Sponsorship grants", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SponsorshipGrantListResponse" }, "examples": { "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" } ] } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "ListReceivedSponsorshipGrants400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "example": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "ListReceivedSponsorshipGrants401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "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" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } }, "sandbox_endpoint_unavailable": { "summary": "sandbox_endpoint_unavailable", "value": { "error": "sandbox_endpoint_unavailable", "message": "This endpoint has no sandbox fixture; use a production key" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "title": "ListReceivedSponsorshipGrants404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" } } }, "example": { "error": "not_found", "message": "No record matches the given identifier" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "ListReceivedSponsorshipGrants500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "ListReceivedSponsorshipGrants503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } } } }, "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.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose." } }, "/client/sponsorship-grants/{grantReference}": { "put": { "tags": [ "Client Admin" ], "operationId": "upsertSponsorshipGrant", "parameters": [ { "name": "grantReference", "in": "path", "required": true, "description": "Stable sponsor-selected reference for idempotent changes.", "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "erp-customer-4711" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SponsorshipGrantUpsertRequest" }, "example": { "beneficiaryClientId": 4711, "endpointKeys": [ "vin.vehicle", "vin.parts", "vin.cart_check" ], "channels": [ "hub" ], "startsAt": "2026-08-16T00:00:00+02:00", "endsAt": null } } } }, "responses": { "200": { "description": "Sponsorship grant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SponsorshipGrantResponse" }, "examples": { "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" } } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid or non-executable sponsorship grant", "content": { "application/json": { "schema": { "title": "UpsertSponsorshipGrant400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "UpsertSponsorshipGrant401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "403": { "description": "Invalid or non-executable sponsorship grant", "content": { "application/json": { "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" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "forbidden": { "summary": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } }, "sandbox_endpoint_unavailable": { "summary": "sandbox_endpoint_unavailable", "value": { "error": "sandbox_endpoint_unavailable", "message": "This endpoint has no sandbox fixture; use a production key" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "404": { "description": "Invalid or non-executable sponsorship grant", "content": { "application/json": { "schema": { "title": "UpsertSponsorshipGrant404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" } } }, "example": { "error": "not_found", "message": "No record matches the given identifier" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "409": { "description": "Invalid or non-executable sponsorship grant", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } }, "sponsorship_conflict": { "summary": "sponsorship_conflict", "value": { "error": "sponsorship_conflict", "message": "A grant already exists under this grantReference with different terms" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "UpsertSponsorshipGrant500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "UpsertSponsorshipGrant503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } } } }, "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.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose." }, "delete": { "tags": [ "Client Admin" ], "operationId": "revokeSponsorshipGrant", "parameters": [ { "name": "grantReference", "in": "path", "required": true, "description": "Stable sponsor-selected reference for idempotent changes.", "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "erp-customer-4711" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "responses": { "200": { "description": "Sponsorship grant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SponsorshipGrantResponse" }, "examples": { "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" } } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "RevokeSponsorshipGrant400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "RevokeSponsorshipGrant401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "403": { "description": "Invalid or non-executable sponsorship grant", "content": { "application/json": { "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" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "forbidden": { "summary": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } }, "sandbox_endpoint_unavailable": { "summary": "sandbox_endpoint_unavailable", "value": { "error": "sandbox_endpoint_unavailable", "message": "This endpoint has no sandbox fixture; use a production key" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "404": { "description": "Invalid or non-executable sponsorship grant", "content": { "application/json": { "schema": { "title": "RevokeSponsorshipGrant404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" } } }, "example": { "error": "not_found", "message": "No record matches the given identifier" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "RevokeSponsorshipGrant500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "RevokeSponsorshipGrant503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } } } }, "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.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose." } }, "/scanner/vin/extract": { "post": { "tags": [ "Scanner" ], "operationId": "extractVinFromImage", "requestBody": { "required": true, "content": { "application/json": { "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" } } }, "example": { "imageUrl": "https://example.com/vehicle-vin.jpg", "quality": "standard" } } } }, "responses": { "200": { "description": "VIN extracted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinImageScanResponse" }, "examples": { "sandbox": { "value": { "vin": "TAPSANDBX00000001" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "ExtractVinFromImage400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "ExtractVinFromImage401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "ExtractVinFromImage403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "VIN extraction failed", "content": { "application/json": { "schema": { "title": "ExtractVinFromImage500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "ExtractVinFromImage503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "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." } }, "/vdi": { "get": { "tags": [ "VDI" ], "operationId": "getVdiCatalog", "responses": { "200": { "description": "Current VDI 4081 catalogue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VdiCatalogResponse" }, "examples": { "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 } ] } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_not_supported": { "summary": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } }, "invalid_query_parameter": { "summary": "invalid_query_parameter", "value": { "error": "invalid_query_parameter", "message": "A query parameter has the wrong type or format" } } } } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "GetVdiCatalog401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "GetVdiCatalog403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "GetVdiCatalog500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "vdi_catalog_unavailable": { "summary": "vdi_catalog_unavailable", "value": { "error": "vdi_catalog_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "example": 100, "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." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "example": 0, "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`." } ], "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.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose." } }, "/parts/oe/normalize": { "get": { "tags": [ "Parts" ], "operationId": "normalizeOeNumber", "parameters": [ { "name": "oeNumber", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "example": "SBX 0001 A", "description": "OE part number compared with available reference information." }, { "name": "manufacturer", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "SANDBOX MOTORS", "description": "Optional manufacturer context for the request." } ], "responses": { "200": { "description": "OE normalisation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OeNormalizationResponse" }, "examples": { "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" ] } ] } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid query parameter", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_not_supported": { "summary": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } }, "invalid_manufacturer": { "summary": "invalid_manufacturer", "value": { "error": "invalid_manufacturer", "message": "manufacturer is not a known manufacturer" } }, "invalid_oe_number": { "summary": "invalid_oe_number", "value": { "error": "invalid_oe_number", "message": "oeNumber must not be empty" } }, "invalid_query_parameter": { "summary": "invalid_query_parameter", "value": { "error": "invalid_query_parameter", "message": "A query parameter has the wrong type or format" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "NormalizeOeNumber401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "NormalizeOeNumber403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "NormalizeOeNumber500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "oe_normalizer_unavailable": { "summary": "oe_normalizer_unavailable", "value": { "error": "oe_normalizer_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "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." } }, "/vehicles/{tapiId}": { "get": { "tags": [ "Vehicles" ], "operationId": "getVehicleByTapiId", "parameters": [ { "name": "tapiId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "5b1a1000-0000-4000-8000-000000000001", "description": "Stable vehicle reference from a VIN flow previously completed successfully for this client." } ], "responses": { "200": { "description": "Determined vehicle data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleByTapiIdResponse" }, "examples": { "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" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "GetVehicleByTapiId400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "example": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "GetVehicleByTapiId401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "GetVehicleByTapiId403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "404": { "description": "Vehicle not found", "content": { "application/json": { "schema": { "title": "GetVehicleByTapiId404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found", "vehicle_not_found" ] }, "message": { "type": "string" } } }, "examples": { "not_found": { "summary": "not_found", "value": { "error": "not_found", "message": "No record matches the given identifier" } }, "vehicle_not_found": { "summary": "vehicle_not_found", "value": { "error": "vehicle_not_found", "message": "No vehicle is known for this identifier" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "GetVehicleByTapiId500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "GetVehicleByTapiId503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } } } }, "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\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended 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." } }, "/recalls/vehicles/{vin}": { "get": { "tags": [ "Recalls" ], "operationId": "matchVehicleRecalls", "parameters": [ { "name": "vin", "in": "path", "required": true, "schema": { "type": "string" }, "example": "TAPSANDBX00000001", "description": "Vehicle identification number that the user must be authorised to transmit and process." } ], "responses": { "200": { "description": "Match result for the vehicle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecallVehicleMatchResponse" }, "example": { "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." } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid VIN", "content": { "application/json": { "schema": { "title": "MatchVehicleRecalls400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "idempotency_key_not_supported": { "summary": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "MatchVehicleRecalls401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "MatchVehicleRecalls403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "404": { "description": "VIN cannot be resolved", "content": { "application/json": { "schema": { "title": "MatchVehicleRecalls404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "vin_not_resolvable" ] }, "message": { "type": "string" } } }, "example": { "error": "vin_not_resolvable", "message": "The VIN cannot be resolved to a vehicle series" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "MatchVehicleRecalls500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "recall_data_unavailable": { "summary": "recall_data_unavailable", "value": { "error": "recall_data_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "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\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended 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." } }, "/recalls/parts": { "post": { "tags": [ "Recalls" ], "operationId": "matchPartRecalls", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecallPartsMatchRequest" }, "example": { "positions": [ { "oeNumber": "SBX0001A", "reference": "pos-1", "vehicle": { "make": "Volkswagen", "model": "Golf VII", "productionFrom": 2012, "productionTo": 2019 } }, { "oeNumber": "SBX0002B", "reference": "pos-2" } ] } } } }, "responses": { "200": { "description": "Match result per position", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecallPartsMatchResponse" }, "example": { "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." } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid position list", "content": { "application/json": { "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" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } }, "invalid_positions": { "summary": "invalid_positions", "value": { "error": "invalid_positions", "message": "positions must be a non-empty list" } }, "invalid_recall_position": { "summary": "invalid_recall_position", "value": { "error": "invalid_recall_position", "message": "Every position needs an OE number or a vehicle make" } }, "too_many_recall_positions": { "summary": "too_many_recall_positions", "value": { "error": "too_many_recall_positions", "message": "A maximum of 100 positions is allowed per call" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "MatchPartRecalls401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "MatchPartRecalls403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "404": { "description": "No position could be resolved", "content": { "application/json": { "schema": { "title": "MatchPartRecalls404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "recall_positions_unresolvable" ] }, "message": { "type": "string" } } }, "example": { "error": "recall_positions_unresolvable", "message": "None of the submitted positions could be resolved to a manufacturer" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "MatchPartRecalls500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "recall_data_unavailable": { "summary": "recall_data_unavailable", "value": { "error": "recall_data_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "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.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ] } }, "/parts/oe/{oeNumber}/price": { "get": { "summary": "Evaluate the price of an OE part", "tags": [ "Intelligence" ], "parameters": [ { "name": "oeNumber", "in": "path", "required": true, "schema": { "type": "string" }, "description": "OE part number compared with available reference information.", "example": "SBX0001A" }, { "name": "condition", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "new", "used" ], "default": "used" }, "description": "Part condition considered by the indicative price evaluation.", "example": "used" }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "default": "EUR" }, "description": "ISO 4217 currency code for monetary values in the response.", "example": "EUR" }, { "name": "vehicleType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "car", "motorcycle" ], "default": "car" }, "description": "Public parameter `vehicleType` defined by this schema.", "example": "car" } ], "responses": { "200": { "description": "Indicative price evaluation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartPriceEvaluationResponse" }, "examples": { "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" } } }, "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" } } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "GetOePrice400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "example": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "GetOePrice401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "GetOePrice403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "404": { "description": "No price data available", "content": { "application/json": { "schema": { "title": "GetOePrice404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "oe_part_not_found" ] }, "message": { "type": "string" } } }, "example": { "error": "oe_part_not_found", "message": "No part is known for this OE number" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Live-Available-At": { "$ref": "#/components/headers/X-Tapinoma-Live-Available-At" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "GetOePrice500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "service_unavailable": { "summary": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "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.", "operationId": "getOePrice", "x-intelligence-group": "parts-market" } }, "/vision/damage/describe": { "post": { "tags": [ "Vision" ], "operationId": "describeDamageFromImages", "requestBody": { "required": true, "content": { "application/json": { "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" } } }, "example": { "imageUrls": [ "https://example.com/schaden-1.jpg", "https://example.com/schaden-2.jpg" ], "quality": "standard", "textQuality": "notes" } } } }, "responses": { "200": { "description": "Damage description generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisionDamageReportResponse" }, "examples": { "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 } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "DescribeDamageFromImages400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "DescribeDamageFromImages401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "DescribeDamageFromImages403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Damage analysis failed", "content": { "application/json": { "schema": { "title": "DescribeDamageFromImages500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "DescribeDamageFromImages503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "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." } }, "/vision/part/quality": { "post": { "tags": [ "Vision" ], "operationId": "gradePartQualityFromImages", "requestBody": { "required": true, "content": { "application/json": { "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" } } }, "example": { "imageUrls": [ "https://example.com/tuer-aussen.jpg", "https://example.com/tuer-innen.jpg" ], "quality": "standard", "partType": "Fahrertür" } } } }, "responses": { "200": { "description": "Quality grade determined", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisionPartQualityResponse" }, "examples": { "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 } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "GradePartQualityFromImages400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "GradePartQualityFromImages401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "GradePartQualityFromImages403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Quality assessment failed", "content": { "application/json": { "schema": { "title": "GradePartQualityFromImages500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "GradePartQualityFromImages503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "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." } }, "/vision/part/remove/bg": { "post": { "tags": [ "Vision" ], "operationId": "removePartBackground", "requestBody": { "required": true, "content": { "application/json": { "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" } } }, "example": { "imageUrl": "https://example.com/stossfaenger.jpg", "quality": "standard", "background": "transparent", "partType": "Stoßfänger vorn" } } } }, "responses": { "200": { "description": "Cutout created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisionCutoutResponse" }, "examples": { "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" ] } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "RemovePartBackground400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "RemovePartBackground401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "RemovePartBackground403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Background removal failed", "content": { "application/json": { "schema": { "title": "RemovePartBackground500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "RemovePartBackground503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "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." } }, "/vision/vehicle/remove/bg": { "post": { "tags": [ "Vision" ], "operationId": "removeVehicleBackground", "requestBody": { "required": true, "content": { "application/json": { "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." } } }, "example": { "imageUrl": "https://example.com/fahrzeug-hof.jpg", "quality": "standard", "background": "white" } } } }, "responses": { "200": { "description": "Cutout created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisionCutoutResponse" }, "examples": { "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" ] } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "RemoveVehicleBackground400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "RemoveVehicleBackground401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "RemoveVehicleBackground403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Background removal failed", "content": { "application/json": { "schema": { "title": "RemoveVehicleBackground500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "RemoveVehicleBackground503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "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." } }, "/client/sponsorship-grants/received/{grantReference}/billing-mode": { "put": { "tags": [ "Client Admin" ], "operationId": "chooseSponsorshipBillingMode", "parameters": [ { "name": "grantReference", "in": "path", "required": true, "description": "Stable sponsor-selected reference for idempotent changes.", "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9._:-]+$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SponsorshipBillingModeRequest" } } } }, "responses": { "200": { "description": "Sponsorship grant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SponsorshipGrantResponse" }, "examples": { "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" } } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid or non-executable sponsorship grant", "content": { "application/json": { "schema": { "title": "ChooseSponsorshipBillingMode400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "ChooseSponsorshipBillingMode401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "403": { "description": "Invalid or non-executable sponsorship grant", "content": { "application/json": { "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" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "forbidden": { "summary": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } }, "sandbox_endpoint_unavailable": { "summary": "sandbox_endpoint_unavailable", "value": { "error": "sandbox_endpoint_unavailable", "message": "This endpoint has no sandbox fixture; use a production key" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "404": { "description": "Invalid or non-executable sponsorship grant", "content": { "application/json": { "schema": { "title": "ChooseSponsorshipBillingMode404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" } } }, "example": { "error": "not_found", "message": "No record matches the given identifier" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "409": { "description": "Invalid or non-executable sponsorship grant", "content": { "application/json": { "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" } } }, "examples": { "ambiguous_grant_reference": { "summary": "ambiguous_grant_reference", "value": { "error": "ambiguous_grant_reference", "message": "Several sponsors use this reference for you; name sponsorClientId" } }, "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "ChooseSponsorshipBillingMode500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "ChooseSponsorshipBillingMode503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } } } }, "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.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose." } }, "/vision/part/generate": { "post": { "tags": [ "Vision" ], "operationId": "generatePartImagesFromOeNumber", "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.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Caller-selected key for a successful response retained for 24 hours. Reusing it returns the documented replay without another charge." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisionPartGenerationRequest" } } } }, "responses": { "202": { "description": "Generation job accepted", "headers": { "Location": { "description": "URL of the job status resource.", "schema": { "type": "string", "format": "uri" } }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisionPartGenerationAccepted" }, "example": { "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 } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "generatePartImagesFromOeNumber400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } } }, "401": { "description": "API key missing", "content": { "application/json": { "schema": { "title": "generatePartImagesFromOeNumber401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "examples": { "missing_api_key": { "summary": "missing_api_key", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } } } }, "402": { "description": "Insufficient credit", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "API key invalid or endpoint not enabled", "content": { "application/json": { "schema": { "title": "generatePartImagesFromOeNumber403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Conflict with an earlier idempotent request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or another request is active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Processing failed", "content": { "application/json": { "schema": { "title": "generatePartImagesFromOeNumber500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "examples": { "internal_error": { "summary": "internal_error", "value": { "error": "internal_error", "message": "The request could not be completed" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "generatePartImagesFromOeNumber503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } } } }, "/vision/part/generation-jobs/{jobId}": { "get": { "tags": [ "Vision" ], "operationId": "getPartImageGenerationJob", "summary": "Read product-image job status", "description": "**Service description**\n\nRead product-image job status. The request and response follow the schemas documented below.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose.", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job status read", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisionPartGenerationJobStatus" }, "example": { "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 } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "GetPartImageGenerationJob400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "example": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } } }, "401": { "description": "API key missing", "content": { "application/json": { "schema": { "title": "getPartImageGenerationJob401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "examples": { "missing_api_key": { "summary": "missing_api_key", "value": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } } } }, "403": { "description": "API key invalid or endpoint not enabled", "content": { "application/json": { "schema": { "title": "getPartImageGenerationJob403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "title": "getPartImageGenerationJob404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "vision_generation_job_not_found" ] }, "message": { "type": "string" } } }, "examples": { "vision_generation_job_not_found": { "summary": "vision_generation_job_not_found", "value": { "error": "vision_generation_job_not_found", "message": "Vision generation job not found" } } } } } }, "429": { "description": "Rate limit exceeded or another request is active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Processing failed", "content": { "application/json": { "schema": { "title": "getPartImageGenerationJob500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "examples": { "internal_error": { "summary": "internal_error", "value": { "error": "internal_error", "message": "The request could not be completed" } } } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "GetPartImageGenerationJob503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } } } } } }, "/vision/vehicle/elv-classification": { "post": { "tags": [ "Vision" ], "operationId": "classifyEndOfLifeVehicle", "requestBody": { "required": true, "content": { "application/json": { "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" } } } } }, "example": { "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": { "200": { "description": "End-of-life vehicle classification created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisionElvClassificationResponse" }, "examples": { "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 } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "ClassifyEndOfLifeVehicle400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "ClassifyEndOfLifeVehicle401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "ClassifyEndOfLifeVehicle403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "End-of-life vehicle classification failed", "content": { "application/json": { "schema": { "title": "ClassifyEndOfLifeVehicle500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "ClassifyEndOfLifeVehicle503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "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." } }, "/vehicles/intake": { "post": { "tags": [ "Vehicles" ], "operationId": "intakeVehicle", "requestBody": { "required": true, "content": { "application/json": { "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." } } }, "example": { "fileUrl": "https://example.com/fahrzeugschein.jpg", "photoUrls": [ "https://example.com/front.jpg", "https://example.com/heck.jpg" ], "includeOwner": false } } } }, "responses": { "200": { "description": "Vehicle file from document scan and vehicle data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleIntakeResponse" }, "examples": { "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 } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "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" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_country": { "summary": "invalid_country", "value": { "error": "invalid_country", "message": "country must be a two-letter ISO 3166-1 code" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } }, "invalid_provider": { "summary": "invalid_provider", "value": { "error": "invalid_provider", "message": "provider is not a supported selection value" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "IntakeVehicle401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "IntakeVehicle403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "IntakeVehicle500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "service_unavailable": { "summary": "service_unavailable", "value": { "error": "service_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "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." } }, "/vehicles/{tapiId}/listing": { "post": { "tags": [ "Vehicles" ], "operationId": "composeVehicleListing", "parameters": [ { "name": "tapiId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "5b1a1000-0000-4000-8000-000000000001", "description": "Stable vehicle reference from a VIN flow previously completed successfully for this client." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "requestBody": { "required": false, "content": { "application/json": { "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" } } }, "example": { "quality": "standard", "language": "de", "notes": "Nichtraucherfahrzeug, zwei Vorbesitzer" } } } }, "responses": { "200": { "description": "Marketplace-ready listing text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleListingResponse" }, "examples": { "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 } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "ComposeVehicleListing400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "ComposeVehicleListing401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "ComposeVehicleListing403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "404": { "description": "Vehicle not found", "content": { "application/json": { "schema": { "title": "ComposeVehicleListing404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "vehicle_not_found" ] }, "message": { "type": "string" } } }, "example": { "error": "vehicle_not_found", "message": "No vehicle is known for this identifier" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "ComposeVehicleListing500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "ComposeVehicleListing503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "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.\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." } }, "/vision/condition-report": { "post": { "tags": [ "Vision" ], "operationId": "reportVehicleCondition", "requestBody": { "required": true, "content": { "application/json": { "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" } } }, "example": { "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": { "200": { "description": "Structured condition report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisionConditionReportResponse" }, "examples": { "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 } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "ReportVehicleCondition400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "ReportVehicleCondition401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "ReportVehicleCondition403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "ReportVehicleCondition500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "ReportVehicleCondition503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "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." } }, "/client/partner-workspaces": { "post": { "tags": [ "Client Admin" ], "operationId": "createPartnerWorkspace", "requestBody": { "required": true, "content": { "application/json": { "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." } } }, "example": { "name": "Autohaus Nord GmbH", "externalReference": "dms-kunde-4711", "endpointKeys": [ "vehicles.intake", "vehicles.listing", "vision.condition_report" ], "sponsorship": true } } } }, "responses": { "201": { "description": "Partner workspace created; the raw API key is returned once", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerWorkspaceResponse" }, "examples": { "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" } } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "CreatePartnerWorkspace400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "idempotency_key_not_supported": { "summary": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "CreatePartnerWorkspace401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "403": { "description": "Only master clients may manage sub-users", "content": { "application/json": { "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" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "forbidden": { "summary": "forbidden", "value": { "error": "forbidden", "message": "This API key may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } }, "sandbox_endpoint_unavailable": { "summary": "sandbox_endpoint_unavailable", "value": { "error": "sandbox_endpoint_unavailable", "message": "This endpoint has no sandbox fixture; use a production key" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "409": { "description": "Workspace reference already taken", "content": { "application/json": { "schema": { "title": "CreatePartnerWorkspace409Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "workspace_reference_exists" ] }, "message": { "type": "string" } } }, "example": { "error": "workspace_reference_exists", "message": "A workspace with this externalReference already exists" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "CreatePartnerWorkspace500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "CreatePartnerWorkspace503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } } } }, "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.\n\n**Usage and legal notice**\n\nUse of this operation and its results is governed by the agreed scope of service and applicable law. Before any technical, commercial or legal onward use, the customer must independently verify that the inputs and results are suitable, complete and lawful for the intended purpose." } }, "/vin/{vin}/economic-evaluation": { "get": { "summary": "Create an economic evaluation by VIN", "tags": [ "Intelligence" ], "parameters": [ { "name": "vin", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vehicle identification number that the user must be authorised to transmit and process.", "example": "TAPSANDBX00000001" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "default": "de" }, "description": "Two-letter country code used for market and regional context.", "example": "de" }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1 ], "default": 1 }, "description": "Optional numeric selection agreed by contract; the default value is `1`.", "example": 1 }, { "name": "condition", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "used", "new" ], "default": "used" }, "description": "Part condition considered by the indicative price evaluation.", "example": "used" }, { "name": "vehicleType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "car", "motorcycle" ], "default": "car" }, "description": "Public parameter `vehicleType` defined by this schema.", "example": "car" }, { "name": "maxPricedParts", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "description": "Upper limit of parts to include in the evaluation. Default and maximum are 100.", "example": 100 }, { "name": "recoveryRate", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0.05, "maximum": 1, "default": 0.5 }, "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.", "example": 0.5 }, { "name": "costPerPart", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1000, "default": 0 }, "description": "Assumed cost per priced part in EUR for removal, storage and shipping (0 to 1000; default 0). Feeds the purchase recommendation.", "example": 0 } ], "responses": { "200": { "description": "Economic evaluation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinEconomicEvaluationResponse" }, "examples": { "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" } } } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "202": { "description": "Economic evaluation accepted for asynchronous processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinEconomicEvaluationJobResponse" }, "examples": { "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" } } } } }, "headers": { "Location": { "$ref": "#/components/headers/Location" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_not_supported": { "summary": "idempotency_key_not_supported", "value": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } }, "invalid_country": { "summary": "invalid_country", "value": { "error": "invalid_country", "message": "country must be a two-letter ISO 3166-1 code" } }, "invalid_provider": { "summary": "invalid_provider", "value": { "error": "invalid_provider", "message": "provider is not a supported selection value" } }, "invalid_query_parameter": { "summary": "invalid_query_parameter", "value": { "error": "invalid_query_parameter", "message": "A query parameter has the wrong type or format" } }, "invalid_vehicle_type": { "summary": "invalid_vehicle_type", "value": { "error": "invalid_vehicle_type", "message": "vehicleType must be car or motorcycle" } } } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "GetVinEconomicEvaluation401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "GetVinEconomicEvaluation403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "title": "GetVinEconomicEvaluation404Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "not_found", "vehicle_not_found" ] }, "message": { "type": "string" } } }, "examples": { "not_found": { "summary": "not_found", "value": { "error": "not_found", "message": "No record matches the given identifier" } }, "vehicle_not_found": { "summary": "vehicle_not_found", "value": { "error": "vehicle_not_found", "message": "No vehicle is known for this identifier" } } } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "GetVinEconomicEvaluation500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "vin_service_unavailable": { "summary": "vin_service_unavailable", "value": { "error": "vin_service_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Bundle": { "$ref": "#/components/headers/X-Tapinoma-Billing-Bundle" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "operationId": "getVinEconomicEvaluation", "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.", "x-intelligence-group": "vehicle-economics" } }, "/vin/economic-evaluation/jobs/{jobId}": { "get": { "summary": "Get the status of an economic evaluation", "tags": [ "Intelligence" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Job ID returned by the associated 202 response.", "example": "6955b900-0400-4548-9632-06e2f302e3d7" } ], "responses": { "200": { "description": "Current state of the evaluation job; on success including the result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinEconomicEvaluationJobResponse" }, "examples": { "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" }, "summary": "Sandbox queued response" }, "failed": { "summary": "Failed job", "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." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "GetVinEconomicEvaluationJob400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "idempotency_key_not_supported" ] }, "message": { "type": "string" } } }, "example": { "error": "idempotency_key_not_supported", "message": "This endpoint does not accept an Idempotency-Key header" } } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "GetVinEconomicEvaluationJob401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "GetVinEconomicEvaluationJob403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "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" } } }, "examples": { "not_found": { "summary": "not_found", "value": { "error": "not_found", "message": "No record matches the given identifier" } }, "vin_economic_evaluation_job_not_found": { "summary": "vin_economic_evaluation_job_not_found", "value": { "error": "vin_economic_evaluation_job_not_found", "message": "No economic evaluation job exists under this jobId" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "GetVinEconomicEvaluationJob500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "GetVinEconomicEvaluationJob503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } } } }, "operationId": "getVinEconomicEvaluationJob", "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.", "x-intelligence-group": "vehicle-economics" } }, "/vision/license-plate": { "post": { "tags": [ "Vision" ], "operationId": "readLicensePlates", "requestBody": { "required": true, "content": { "application/json": { "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" } } } } } }, "responses": { "200": { "description": "Licence plates found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisionLicensePlateResponse" }, "examples": { "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": [] } ] } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "ReadLicensePlates400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "ReadLicensePlates401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "ReadLicensePlates403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Documented HTTP 500 response.", "content": { "application/json": { "schema": { "title": "ReadLicensePlates500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "ReadLicensePlates503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "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." } }, "/vision/part/composite": { "post": { "tags": [ "Vision" ], "operationId": "compositePartIntoBackground", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisionPartCompositeRequest" }, "example": { "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": { "200": { "description": "New part composited into the background image", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisionPartCompositeResponse" }, "examples": { "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": [] } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "CompositePartIntoBackground400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "CompositePartIntoBackground401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "API key invalid or endpoint not enabled", "content": { "application/json": { "schema": { "title": "CompositePartIntoBackground403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Idempotency-Key already used for a different request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "422": { "description": "Output could not be verified safely", "content": { "application/json": { "schema": { "title": "CompositePartIntoBackground422Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "part_segmentation_failed", "image_edit_unverified" ] }, "message": { "type": "string" } } }, "examples": { "part_segmentation_failed": { "summary": "part_segmentation_failed", "value": { "error": "part_segmentation_failed", "message": "The part could not be reliably separated from its surroundings" } }, "image_edit_unverified": { "summary": "image_edit_unverified", "value": { "error": "image_edit_unverified", "message": "The edited image could not be verified against the source, so no image is returned" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Image processing failed", "content": { "application/json": { "schema": { "title": "CompositePartIntoBackground500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "CompositePartIntoBackground503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "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.", "x-client-timeout-seconds": 300 } }, "/vision/part/damage-transfer": { "post": { "tags": [ "Vision" ], "operationId": "transferVisibleDamageToPartViews", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisionDamageTransferRequest" }, "example": { "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": { "200": { "description": "Visible damage transferred to target views", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisionDamageTransferResponse" }, "examples": { "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 } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "TransferVisibleDamageToPartViews400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "TransferVisibleDamageToPartViews401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "API key invalid or endpoint not enabled", "content": { "application/json": { "schema": { "title": "TransferVisibleDamageToPartViews403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Idempotency-Key already used for a different request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "422": { "description": "Output could not be verified safely", "content": { "application/json": { "schema": { "title": "TransferVisibleDamageToPartViews422Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "damage_not_transferable", "image_edit_unverified" ] }, "message": { "type": "string" } } }, "examples": { "damage_not_transferable": { "summary": "damage_not_transferable", "value": { "error": "damage_not_transferable", "message": "The visible damage could not be reliably transferred to the standard views" } }, "image_edit_unverified": { "summary": "image_edit_unverified", "value": { "error": "image_edit_unverified", "message": "The edited image could not be verified against the source, so no image is returned" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Image processing failed", "content": { "application/json": { "schema": { "title": "TransferVisibleDamageToPartViews500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "TransferVisibleDamageToPartViews503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "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.", "x-client-timeout-seconds": 300 } }, "/vision/identifiers/redact": { "post": { "tags": [ "Vision" ], "operationId": "redactPartIdentifiers", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisionIdentifierRedactRequest" }, "example": { "imageUrls": [ "https://example.com/steuergeraet.jpg" ], "quality": "standard", "output": { "size": "1536x1024", "format": "jpeg" } } } } }, "responses": { "200": { "description": "Identifiers redacted and result verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisionIdentifierRedactResponse" }, "examples": { "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" } } ] } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "RedactPartIdentifiers400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "RedactPartIdentifiers401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "API key invalid or endpoint not enabled", "content": { "application/json": { "schema": { "title": "RedactPartIdentifiers403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Idempotency-Key already used for a different request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "422": { "description": "Output could not be verified safely", "content": { "application/json": { "schema": { "title": "RedactPartIdentifiers422Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "identifier_redaction_unverified" ] }, "message": { "type": "string" } } }, "examples": { "identifier_redaction_unverified": { "summary": "identifier_redaction_unverified", "value": { "error": "identifier_redaction_unverified", "message": "The identifier redaction could not be verified, so no image is returned" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Image processing failed", "content": { "application/json": { "schema": { "title": "RedactPartIdentifiers500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "title": "RedactPartIdentifiers503Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "billing_unavailable", "endpoint_not_priced" ] }, "message": { "type": "string" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "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.", "x-client-timeout-seconds": 300 } }, "/parts/identify": { "post": { "tags": [ "Parts" ], "operationId": "identifyPart", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartIdentifyRequest" }, "example": { "vin": "TAPSANDBX00000001", "manufacturer": "SANDBOX MOTORS", "customerOeNumbers": [ "SBX 0001 A" ], "labelReadings": [ { "extractAll": { "primaryPartNumber": "SBX 0001 A", "otherPartNumbers": [ "SBX0009Z" ] } } ], "descriptions": [ "Sandbox Scheinwerfer links" ] } } } }, "responses": { "200": { "description": "Part identification completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartIdentifyResponse" }, "examples": { "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": [] } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Idempotency-Stored": { "$ref": "#/components/headers/X-Tapinoma-Idempotency-Stored" }, "X-Tapinoma-Idempotent-Replay": { "$ref": "#/components/headers/X-Tapinoma-Idempotent-Replay" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "title": "IdentifyPart400Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_idempotency_key" ] }, "message": { "type": "string" } } }, "examples": { "bad_request": { "summary": "bad_request", "value": { "error": "bad_request", "message": "The request body is not valid for this endpoint" } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": "invalid_idempotency_key", "message": "Idempotency-Key must be 8 to 255 printable characters" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "401": { "description": "API key is missing", "content": { "application/json": { "schema": { "title": "IdentifyPart401Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key" ] }, "message": { "type": "string" } } }, "example": { "error": "missing_api_key", "message": "Missing X-Api-Key header" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "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" } } }, "examples": { "insufficient_credits": { "summary": "insufficient_credits", "value": { "error": "insufficient_credits", "message": "The account has no credit left for this endpoint" } }, "partner_terms_not_covered": { "summary": "partner_terms_not_covered", "value": { "error": "partner_terms_not_covered", "message": "Your partner does not cover this endpoint" } }, "sponsorship_cap_reached": { "summary": "sponsorship_cap_reached", "value": { "error": "sponsorship_cap_reached", "message": "Monthly sponsorship cap reached" } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "403": { "description": "Invalid API key", "content": { "application/json": { "schema": { "title": "IdentifyPart403Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "endpoint_not_allowed", "invalid_api_key" ] }, "message": { "type": "string" } } }, "examples": { "endpoint_not_allowed": { "summary": "endpoint_not_allowed", "value": { "error": "endpoint_not_allowed", "message": "This client may not use this endpoint" } }, "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": "invalid_api_key", "message": "The API key is unknown or no longer active" } } } } } }, "409": { "description": "Conflict with an earlier request", "content": { "application/json": { "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" } } }, "examples": { "idempotency_key_conflict": { "summary": "idempotency_key_conflict", "value": { "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body" } }, "idempotency_request_in_progress": { "summary": "idempotency_request_in_progress", "value": { "error": "idempotency_request_in_progress", "message": "Another request with this Idempotency-Key is still running" } }, "idempotency_result_unavailable": { "summary": "idempotency_result_unavailable", "value": { "error": "idempotency_result_unavailable", "message": "The earlier operation may have completed, but its replay response is unavailable" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "429": { "description": "Rate limit exceeded or parallel request active", "content": { "application/json": { "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" } } }, "examples": { "client_request_in_progress": { "summary": "client_request_in_progress", "value": { "error": "client_request_in_progress", "message": "Another request for this client is still running" } }, "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": "rate_limit_exceeded", "message": "The rate limit for this endpoint has been reached" } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Part identification failed", "content": { "application/json": { "schema": { "title": "IdentifyPart500Error", "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string" } } }, "example": { "error": "internal_error", "message": "The request could not be completed" } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "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" } } }, "examples": { "billing_unavailable": { "summary": "billing_unavailable", "value": { "error": "billing_unavailable", "message": "The service is temporarily unavailable." } }, "parts_identify_unavailable": { "summary": "parts_identify_unavailable", "value": { "error": "parts_identify_unavailable", "message": "The service is temporarily unavailable." } }, "endpoint_not_priced": { "summary": "endpoint_not_priced", "value": { "error": "endpoint_not_priced", "message": "The service is temporarily unavailable." } } } } }, "headers": { "X-Tapinoma-Billing-Source": { "$ref": "#/components/headers/X-Tapinoma-Billing-Source" }, "X-Tapinoma-Sponsorship-Grant": { "$ref": "#/components/headers/X-Tapinoma-Sponsorship-Grant" }, "X-Tapinoma-Usage-Warning": { "$ref": "#/components/headers/X-Tapinoma-Usage-Warning" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "6f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21", "description": "Public parameter `Idempotency-Key` defined by this schema." } ], "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." } } }, "x-usage": { "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." }, "tags": [ { "name": "System", "description": "Technical API status." }, { "name": "VDI", "description": "The public schema defines the meaning and format of `1`." }, { "name": "Client Admin", "description": "Administration of sub-users, balances, usage, limits, plans and Hub sponsorships." }, { "name": "VIN", "description": "Automated comparison of VIN-related reference information." }, { "name": "Vehicles", "description": "The dealer's vehicle file: intake from the registration document, technical vehicle data per tapiId and marketplace-ready listing texts." }, { "name": "Parts", "description": "Automated comparison and analysis of OE and parts information." }, { "name": "Intelligence", "description": "Price, market and economic analyses with evidence, price ranges, history and transparent confidence. The paid production pilot remains closed until positive prices and atomic billing are approved." }, { "name": "Recalls", "description": "Series-level match against the recall and safety measures of the official registers, with a data version per register." }, { "name": "Scanner", "description": "Automated analysis of duly authorised images and documents." }, { "name": "Vision", "description": "Automated condition assessment of duly authorised images." }, { "name": "Translation", "description": "Translation of exactly one individual part designation per request." } ], "x-error-codes": [ { "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" } ], "x-response-headers": [ { "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`." } ], "x-glossary": { "client": { "term": "Client", "definition": "An account in tapinomahub, addressed by its `clientId`. Every API key belongs to exactly one client. Billing, credit, plans and rate limits always attach to the client itself, never to a parent account." }, "masterClient": { "term": "Master client", "definition": "A client with no parent account and an administrative role. Only a master client may create and manage sub-users and issue sponsorships. Every directly contracted customer is a master client." }, "subUser": { "term": "Sub-user", "definition": "A client with a master client above it. It has its own API keys, credit, plans and limits, but no administrative rights — it cannot create sub-users of its own. The hierarchy is exactly two levels deep. Deactivating the master client deactivates its sub-users with it." }, "workspace": { "term": "Workspace", "definition": "Not an object of its own, but the everyday word for a client together with its keys, credit and plans. Where this contract says “workspace”, it means a client. The beneficiary of a sponsorship can be any active client, master client and sub-user alike." }, "tenant": { "term": "Tenant", "definition": "The API has no tenant field. Customer systems that separate end customers should use separate clients or sub-users with dedicated API keys and keep tenant identifiers only in their own system." } }, "x-intelligence-release": { "status": "closed_production_pilot", "commercialAccess": "disabled", "billing": "disabled_pending_approved_positive_prices", "accountAccess": "disabled", "adaptiveRefresh": "disabled", "vinEconomicIntelligence": "disabled", "crossTenantBenchmarks": "disabled", "dataPanel": "not_connected", "limitations": [ "No prices have been approved; real-data paths remain locked without 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 Intelligence are currently disabled.", "Scores remain null or non-publishable without sufficient evidence." ] } }