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

# API Overview

> Overview of the Essal API — base URLs, versioning, request format, error codes, and pagination.

The Essal API is a RESTful HTTP API that provides programmatic access to all six apps in the Essal platform. All endpoints return JSON and use standard HTTP verbs.

## Base URLs

| Environment | Base URL                             |
| ----------- | ------------------------------------ |
| Production  | `https://api.essal.cloud/v1`         |
| Staging     | `https://staging.api.essal.cloud/v1` |
| Sandbox     | `https://sandbox.essal.cloud/v1`     |

## Versioning

The API is versioned by URL path (`/v1`). Breaking changes are introduced in new major versions with a 12-month deprecation notice. The current version is **v1**.

## Request Format

All requests must include:

* `Content-Type: application/json` for `POST`, `PUT`, and `PATCH` requests
* `X-API-Key: esk_live_...` or `Authorization: Bearer {token}` for authentication

```bash theme={null}
curl -X POST https://api.essal.cloud/v1/office/documents \
  -H "X-API-Key: esk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "title": "My Document" }'
```

## Error Format

All errors follow a consistent structure:

```json theme={null}
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Document doc_01HXYZ9999 does not exist in this workspace.",
    "request_id": "req_01HXYZ_REQ1"
  }
}
```

Common error codes:

| HTTP Status | Code                  | Meaning                        |
| ----------- | --------------------- | ------------------------------ |
| 400         | `VALIDATION_ERROR`    | Invalid request body           |
| 401         | `UNAUTHORIZED`        | Missing or invalid credentials |
| 403         | `FORBIDDEN`           | Insufficient permissions       |
| 404         | `RESOURCE_NOT_FOUND`  | Entity does not exist          |
| 409         | `CONFLICT`            | Duplicate or state conflict    |
| 429         | `RATE_LIMIT_EXCEEDED` | Too many requests              |
| 500         | `INTERNAL_ERROR`      | Server-side error              |

## Pagination

List endpoints return paginated results using cursor-based pagination:

```bash theme={null}
GET /v1/office/documents?limit=20&cursor=doc_01HXYZ5555
```

```json theme={null}
{
  "data": [...],
  "meta": {
    "total": 342,
    "next_cursor": "doc_01HXYZ6666",
    "has_more": true
  }
}
```

Pass `next_cursor` as the `cursor` parameter in your next request to retrieve the following page.