Migration Guide - Essal Developer Docs

This guide covers how to migrate from earlier Essal API versions or from third-party tools to the Essal v1 API across all six apps.

What Changed in v1

v1 is a full redesign of the Essal API. Key changes from the legacy API:

Legacy	v1
Separate base URLs per app	Single base URL: `https://api.essal.cloud/v1`
Per-app API keys	Single workspace API key with scopes
App-specific auth headers	Unified `X-API-Key` or `Authorization: Bearer`
Inconsistent pagination	Cursor-based pagination on all list endpoints
No cross-app references	`linked_resources` on all entities
Per-app webhook subscriptions	Single `/v1/webhooks` endpoint for all events

Step-by-Step Migration

1. Generate a v1 API Key

Create a new API key from Settings → Developer → API Keys and assign the scopes your integration needs. Existing legacy keys continue working during the transition period.

2. Update the Base URL

- https://office.api.essal.cloud/v1/documents
+ https://api.essal.cloud/v1/office/documents

All endpoints follow the pattern /v1/{app}/{resource}.

3. Update the Auth Header

- X-Office-API-Key: legacy_key
+ X-API-Key: esk_live_xxxxxxxxxxxxxxxxxxxx

4. Update Pagination Logic

List endpoints previously returned page and total_pages. v1 uses cursor-based pagination:

- GET /v1/documents?page=2&per_page=20
+ GET /v1/office/documents?cursor=doc_01HXYZ5555&limit=20

Read the meta.next_cursor from each response and pass it as cursor in the next request.

5. Migrate Webhook Subscriptions

Delete per-app webhook subscriptions and create a unified subscription:

POST /v1/webhooks
{
  "url": "https://your-endpoint.example.com/essal",
  "events": ["office.document.created", "sales.deal.won", "guard.alert.triggered"]
}

Transition Period

Legacy API endpoints remain available until December 31, 2026. After that date, all legacy endpoints will return 410 Gone.

Begin migrating now. The transition period will not be extended. Legacy API keys will stop working at the same time as the legacy endpoints.

Support During Migration

If you encounter issues during migration, contact developer-support@essal.cloud with your workspace ID and a description of the issue.

​What Changed in v1

​Step-by-Step Migration

​1. Generate a v1 API Key

​2. Update the Base URL

​3. Update the Auth Header

​4. Update Pagination Logic

​5. Migrate Webhook Subscriptions

​Transition Period

​Support During Migration

What Changed in v1

Step-by-Step Migration

1. Generate a v1 API Key

2. Update the Base URL

3. Update the Auth Header

4. Update Pagination Logic

5. Migrate Webhook Subscriptions

Transition Period

Support During Migration