Migrating from Legacy Endpoints

How the legacy Claret API differs from the current REST API, and how to migrate.

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.

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.

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.
Authorization	Implicit (the user's session)	Two gates: token scope + creator's permissions
Pagination	current_index / next_index index walking	Offset for reference data, cursor for transactional data
Response shape	Flat JSON with pagination keys mixed in	Envelope: data, meta, links
Errors	Ad-hoc JSON	RFC 9457 application/problem+json
Metering	None	Credits and rate limits

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.
GET /sales	GET /sales-data	Cursor pagination; filter[...], sort, include. See Sales Data.
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:

# Legacy — do not use for new integrations
curl -X POST "https://plan.claret.app/{tenant}/api/v1/tokens/create" \
  -d "email=[e-mail]&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:

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.

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.

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 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

• Pagination

• The API Reference