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

# Migration Guide

> Guide for teams migrating existing integrations to the Essal v1 API.

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

```diff theme={null}
- 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

```diff theme={null}
- 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:

```diff theme={null}
- 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:

```bash theme={null}
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`.

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

## Support During Migration

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