# tapinomahub API

> tapinomahub API v1 – the central interface for VIN, parts, VDI, scanner, translation, vision, vehicle and recall services, plus public client administration. The published OpenAPI 3.1.0 contract (version 1.71.0) is authoritative.

Base URL: `https://api.tapinomahub.com`. Authentication: send the API key in the `X-Api-Key` header on every request. Use exact methods, paths, schemas and enum values from the contract; do not infer undocumented fields or behaviour.

Important integration rules:

- Branch on the stable `error` code of non-2xx responses, never on the human-readable `message`.
- A successful job-status response with `status: "failed"` is an operation result, not an HTTP error. Follow that operation's embedded error schema.
- For `202`, poll the validated full `statusUrl`, honour `Retry-After`, compare `Location`, and never reconstruct its root-relative example or resubmit the order.
- Personal docs use `/scanner/document`, only `quality=standard`; old paths are POST aliases.
- `GET /parts/oe/{oeNumber}/seo` (`getPartSeo`) is the eBay and marketplace article optimisation: listing title (`content.ebayTitle`, 80 characters), marketplace category (`categoryId`), item specifics (`itemSpecifics[]`), keywords and shop SEO text, per `marketplaceId` (`EBAY_DE` by default) and `language`.
- Use the generated domain dictionary for canonical terminology. A contract field that is absent from that dictionary is not automatically a canonical domain term.
- Do not infer undocumented storage, retention, rate-limit, compatibility or lifecycle behaviour.

## API contract

- [Full generated integration context](https://docs.tapinomahub.com/llms-full.txt): Complete generated API context.
- [OpenAPI 3.1, English](https://docs.tapinomahub.com/specs/tapinoma-hub.en.json): Authoritative Hub contract.
- [Commerce OpenAPI preview, English](https://docs.tapinomahub.com/specs/tapinoma-commerce.en.json): Versioned, non-operational Commerce contract.
- [Generated API catalogue](https://docs.tapinomahub.com/machine/api-catalog.json): Operation-level contract index.
- [Field origins](https://docs.tapinomahub.com/machine/field-origins.json): Request consumers and response producers.

## Domain, decisions and integration

- [Integration knowledge base](https://docs.tapinomahub.com/knowledge/): Authority model and complete human/agent navigation.
- [Domain model and terminology](https://docs.tapinomahub.com/knowledge/domain-model/): Canonical terms and public contract concepts.
- [Capability map](https://docs.tapinomahub.com/knowledge/capabilities/): Inputs, outputs and operation mapping.
- [Identifiers and data flow](https://docs.tapinomahub.com/knowledge/identifiers-and-data-flow/): Identifier producers and consumers.
- [Decision guides](https://docs.tapinomahub.com/knowledge/decision-guides/): Evidence-based input-to-goal routing.
- [Integration recipes](https://docs.tapinomahub.com/knowledge/integration-recipes/): End-to-end integration workflows.
- [Runtime, errors and security](https://docs.tapinomahub.com/knowledge/runtime-and-security/): Authentication, jobs, retry, idempotency, limits, pagination and data protection.
- [Integration, onboarding and go-live](https://docs.tapinomahub.com/integration/?lang=en): Access, tenant setup, acceptance and production operations.
- [Parts process, end to end](https://docs.tapinomahub.com/processes/?lang=en): From a loose part or registration document to a confirmed OE and VIN workflow.
- [Commerce concept preview](https://docs.tapinomahub.com/commerce/?lang=en): Setup, sync, pricing, formats and production gates.
- [Master key and clients](https://docs.tapinomahub.com/clients/?lang=en): The two-level client model, key handling, limits and billing separation.
- [MCP](https://docs.tapinomahub.com/mcp/): Preview.

## Reference data

- [Vehicle registration field mapping](https://docs.tapinomahub.com/mappings/vehicle-registration-field-mapping.md): Country-aware mapping for normalized registration-document fields.
- [Domain dictionary](https://docs.tapinomahub.com/machine/domain-dictionary.json): Exact released x-glossary terms in German, English and French.
- [Knowledge graph](https://docs.tapinomahub.com/machine/knowledge-graph.json): Evidence-bearing relations among concepts, capabilities, operations, schemas and identifiers.

## Optional

- [OpenAPI 3.1, German](https://docs.tapinomahub.com/specs/tapinoma-hub.json): Structurally identical contract with German descriptions.
- [OpenAPI 3.1, French](https://docs.tapinomahub.com/specs/tapinoma-hub.fr.json): Structurally identical contract with French descriptions.
- [Human-readable API reference](https://docs.tapinomahub.com/): Interactive reference and error catalogue.
- [System status](https://docs.tapinomahub.com/status/): Current availability of the API and related services.