# API
Canonical URL: https://mbretrofit.it/guides/api
Description: Programmatic access to Mercedes‑Benz map code generation (NTG 5/5.5/5s1/5s2, regions like Europe), VIN decode and service history, plus diagnostic seed keys. Secure, credit‑based REST API.


The MBRetrofit API lets you programmatically access the same features available in your dashboard - including Mercedes‑Benz navigation map code generation, VIN decode and service history lookup, and diagnostic seed keys - for platforms such as NTG 5, NTG 5.5, NTG 5s1, and NTG 5s2 across regions like Europe.

## Overview

The MBRetrofit API is a simple, secure REST API for Mercedes‑Benz retrofit and diagnostics workflows:

* Generate navigation map activation codes for NTG 5/5.5/5s1/5s2 and region/version combinations
* Retrieve diagnostic seed keys to unlock ECUs/modules (UDS seed/key exchange)
* Look up vehicle data: VIN decode and official service history

## Authentication

All requests require an API key sent in the request header. Keep your key secret and never embed it in client-side code.

Header:

```text
x-api-key: YOUR_API_KEY
```

Environments:

* Production: `https://mbretrofit.it/api/v1`
* Test: `https://mbretrofit.it/api/test/v1` (uses the same `x-api-key`)

Need access? Email us and describe your use case and expected volume.

[Request API access](mailto:contact@mbretrofit.it?subject=API%20Access%20Request)

Once your account has API access, [manage API keys in the professional dashboard](/app/professional/api). Each key is subject to its account permissions and enabled products.

## Quickstart in the test environment

Use your API key with the test base URL before making production requests. Test responses use example data and do not perform the production operation. Authentication, permissions, input validation, and rate limits still apply.

```bash
curl --fail-with-body \
  -H "x-api-key: $MBRETROFIT_API_KEY" \
  https://mbretrofit.it/api/test/v1/seed/definitions
```

This read-only endpoint returns example ECU definitions in test mode and takes no parameters. The [OpenAPI specification](/api/v1/openapi) describes all operations, inputs, response schemas, and both server URLs. It is public and does not require an API key. An endpoint without a sandbox handler, such as map form options, returns `501 TEST_MODE_UNSUPPORTED` in test mode.

## When to use the API

Use the API to integrate vehicle lookup, service-history retrieval, map activation codes, or diagnostic seed keys into an authorized workshop workflow. Use the public guides for preparation instructions and email [contact@mbretrofit.it](mailto:contact@mbretrofit.it) for VIN-specific coding work that has no API endpoint.

Before a production request that spends credits, confirm the exact operation and cost with the account owner. Keep VINs, vehicle records, and API keys out of public logs. A timeout does not prove an operation failed; check the dashboard or contact support before retrying a paid request.

## Rate limits and retries

Limits use a sliding 60-second window per API key. Vehicle lookup and service-history requests allow 60 requests per window, vehicle info allows 120, and each of the map and seed groups allows 30. Other REST endpoints default to 60 requests per window. Test and production requests share these limits. Administrative keys bypass this limiter.

After a request reaches the limiter, responses include `RateLimit-Policy` and `RateLimit`, plus the compatibility fields `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset`. Remaining quota reflects the request just processed. Reset is a number of seconds until the oldest counted request leaves the sliding window, when capacity starts returning. These values are hints; concurrent requests may consume the same key's quota.

A `429` response also includes `Retry-After` in seconds. Wait at least that long before retrying. Authentication failures, public documentation, and keys that bypass the limiter do not report a measured quota. Quota headers are omitted if the limiter cannot measure it.

## API versioning and deprecation

The current API uses `/api/v1`, with `/api/test/v1` for test requests. Use the published OpenAPI specification for the current request and response contract.

No deprecation or sunset date is currently announced for v1. Current endpoints do not send `Sunset` or `Deprecation` headers. Check the [changelog](/changelog) for published API changes and contact support before depending on an undocumented operation.

## Credits & billing

Some endpoints are premium and consume credits. For example, generating a map code uses 1 map credit. Credits are deducted from your balance at request time.

[Manage credits](/app/professional/profile)

## Quick links

[Map Codes APIGenerate Mercedes‑Benz navigation map activation codes and fetch
NTG/region options.Endpoints: form options, generate code](./api/map-code)

[VIN & Service Lookup APIVIN decode and official service history retrieval for
Mercedes‑Benz.Endpoints: lookup, service history](./api/car-lookup)

[Seed Keys APIList definitions, generate and retrieve diagnostic seed keys for
ECU unlock.Endpoints: definitions, generate, get](./api/seed)