> ## Documentation Index
> Fetch the complete documentation index at: https://docs.remapdb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate from API v1 to v2

> Keep your existing API key and prepare your integration for the customized vehicle catalog.

## Choose your API version

Use `https://api.remapdb.com/v2` for new REST integrations. Existing integrations can continue using `https://api.remapdb.com/v1` during the migration period. The same Bearer API key works with both versions, and both share your existing request allowance.

V1 retains the shared-catalog behavior. Enabling Customizations in your account does not change v1 responses. V2 uses your customized catalog when your subscription includes Customizations; otherwise it returns the shared catalog using the v2 response contract.

The hosted MCP endpoint, widgets, and WordPress integration use the updated catalog directly. Their URLs are unchanged.

## Update your client before switching URLs

| Area | Required preparation for v2 |
| - | - |
| IDs and cursors | Keep them numeric. Support integers through `9007199254740991`, including database columns and generated client types. Private IDs start at `4294967296`. |
| Catalog contents | Expect account-specific names, performance, equipment, hidden branches, and private records beneath shared parents. |
| Stage identity | Use stage `id` as the key. `stage_number` is a display value and can repeat. |
| Asset URLs | Handle nullable manufacturer `logo` and `logo_dark`. Keep durable custom logo URLs, not the temporary signed URLs they may redirect to. |
| Response fields | Update strict response validators for fields such as `origin` and stage/equipment identity. |
| Charts | Handle empty dyno arrays and the v2 shared-template fallback. |
| Lists and search | Recheck ordering, pagination, language fallback, and saved IDs. Hidden or unavailable ancestors suppress their descendants. |
| Caching | Separate v1 and v2 caches. Scope v2 entries by account, language, and catalog profile; refresh them after account catalog changes. |

Changing only the base URL may break an older generated client. Regenerate or update it against [the v2 OpenAPI specification](/openapi-v2.json), then test representative list, detail, search, and chart responses.

```bash theme={null}
curl "https://api.remapdb.com/v2/types" \
  -H "Authorization: Bearer <API_KEY>"
```

## Migration checklist

1. Update your field types, stage keys, nullable assets, and cache scope.
2. Test v2 using your existing API key, including any customized or hidden records.
3. Compare your rendered results and pagination with your current integration.
4. Switch your integration to `/v2` and clear its v1 response cache.
5. Monitor errors and missing records. While v1 remains supported, reverting the URL restores the legacy contract.

## Deprecation and retirement

V1 support is planned for approximately three months after the v2 launch. The exact retirement date will be announced at launch; no date is fixed by this guide.

V1 responses link to this guide. Once configured at launch, `Deprecation` identifies the deprecation date and `Sunset` identifies the announced retirement date. These headers do not change the response body or automatically stop requests.

Retirement will happen in a separate release. Retired v1 endpoints will return `410 Gone` with migration guidance, rather than silently redirecting requests to v2. The [v1 specification](/openapi.json) and existing reference pages remain available during the transition.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.