API Overview

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

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:

{
  "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:

GET /v1/office/documents?limit=20&cursor=doc_01HXYZ5555

{
  "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.

Office

Access

Sales

Careers

Project

Guard

Webhooks

API Overview

Base URLs

Versioning

Request Format

Error Format

​Base URLs

​Versioning

​Request Format

​Error Format

​Pagination

Base URLs

Versioning

Request Format

Error Format

Pagination