> For the complete documentation index, see [llms.txt](https://docs.claret.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.claret.app/api-guide/migration.md).

# Migrating from Legacy Endpoints

Claret's original API is still available, but the current REST API is the recommended way to integrate. This page explains the differences and how to move across.

{% hint style="info" %}
If you are building a new integration, start with the current API and ignore the legacy column below. This page is for existing integrations and for understanding older code.
{% endhint %}

## What changed

| Area           | Legacy API                                                                            | Current API                                                                                                                                                                            |
| -------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authentication | `POST /tokens/create` with email + password, returns a session-style token (`1\|...`) | Tokens created in **API Access** UI with scopes; begin with `clrt_`. See [Authentication](/api-guide/authentication.md).                                                               |
| Authorization  | Implicit (the user's session)                                                         | [Two gates](/api-guide/authentication.md#two-gate-authorization): token scope + creator's permissions                                                                                  |
| Pagination     | `current_index` / `next_index` index walking                                          | [Offset](/api-guide/pagination.md#offset-pagination-reference-data) for reference data, [cursor](/api-guide/pagination.md#cursor-pagination-transactional-data) for transactional data |
| Response shape | Flat JSON with pagination keys mixed in                                               | Envelope: `data`, `meta`, `links`                                                                                                                                                      |
| Errors         | Ad-hoc JSON                                                                           | [RFC 9457](/api-guide/errors.md) `application/problem+json`                                                                                                                            |
| Metering       | None                                                                                  | [Credits](/api-guide/credits-and-usage.md) and [rate limits](/api-guide/rate-limiting.md)                                                                                              |

## Endpoint mapping

| Legacy endpoint                          | Current endpoint                                                                         | Notes                                                                                                      |
| ---------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `POST /tokens/create` (email + password) | Create a token in **API Access → Tokens**                                                | The new flow is UI-driven and scoped. See [Authentication](/api-guide/authentication.md).                  |
| `GET /sales`                             | `GET /sales-data`                                                                        | Cursor pagination; `filter[...]`, `sort`, `include`. See [Sales Data](/api-guide/migration/sales-data.md). |
| `GET /supply-plan/get/process`           | `GET /supply-plans`                                                                      | Cursor pagination and structured filters.                                                                  |
| `POST /inventory/import/process`         | `POST /workflows/sync-inventory` (JSON) or `POST /workflows/sync-inventory/import` (CSV) | Async with `job_id` polling, `dry_run`, idempotency.                                                       |

## Migrating authentication

The legacy flow exchanged credentials for a token on every run:

```bash
# Legacy — do not use for new integrations
curl -X POST "https://plan.claret.app/{tenant}/api/v1/tokens/create" \
  -d "email=user@example.com&password=secret"
# → { "token": "1|bfDoNPffjU6k541RYSLB68oEfHySweWJ2HSx34sZ" }
```

Replace it with a token created once in the **API Access** UI, stored as a secret, and sent on each request:

```bash
curl "https://plan.claret.app/{tenant}/api/v1/uoms" \
  -H "Authorization: Bearer 42|clrt_..." \
  -H "Accept: application/json"
```

This removes passwords from your integration, scopes access to only what's needed, and lets you revoke a single token without rotating credentials.

{% hint style="warning" %}
The legacy `POST /tokens/create` endpoint is **deprecated and scheduled for removal on 2027-01-01**. Migrate authentication before then. The legacy token-exchange flow will stop working after that date.
{% endhint %}

## Migrating pagination

Legacy endpoints returned an index to carry forward:

```
Legacy:  first call has no current_index → response gives next_index
         pass next_index as &current_index=... until next_index is null
```

The current API replaces this with two clearer models:

* **Reference data** uses page numbers: increment `page` until `current_page == last_page`.
* **Transactional data** uses cursors: follow `meta.pagination.next_cursor` until `has_more` is `false`.

See [Pagination](/api-guide/pagination.md) for full examples.

## Why the new endpoints use distinct paths

The new REST endpoints were deliberately given distinct paths (for example, `/sales-data` rather than `/sales`) so that existing integrations against the legacy paths keep working unchanged. There is **no forced cut-over date for the data endpoints** — only the legacy authentication endpoint has a dated sunset (above).

If clean paths are reclaimed for the REST API in the future, it will be communicated in advance. Any permanent redirect introduced at that time would use **HTTP 308** (which preserves the request method and body) rather than **301** (which historically allowed clients to downgrade `POST` to `GET`), so automated `POST` clients would continue to work across the redirect.

## Related documentation

* [Authentication & Tokens](/api-guide/authentication.md)
* [Pagination](/api-guide/pagination.md)
* The **API Reference**