API Docs

API getting started

Create a server-side integration, authenticate it safely, and learn the conventions shared by the customer API.

Find your endpoint

Open Console Settings and use the API access information for your deployment. Examples use API_BASE_URL; do not copy a URL from another deployment.

Keep the endpoint in application configuration so it can be changed without rebuilding your integration.

Authentication

Create an organization API token in Console Settings. Use a read token for inspection and a read_write token only when the integration must create or change resources.

Send the token as Authorization: Bearer <token>. Store it in a secret manager, never browser code, source control, URLs, logs, or support messages. A secret is shown only once; rotate and revoke it in Console when exposure is suspected.

Test your token

GET /api/v1/account returns the principal and organization represented by the token. It is a safe first request before enabling an integration.

curl --fail-with-body   --header "Authorization: Bearer $EMAIA_API_TOKEN"   "$API_BASE_URL/api/v1/account"

Request conventions

  • Use HTTPS and JSON unless a guide explicitly specifies another content type.
  • Treat unknown response fields as additive and ignore them.
  • Use the documented idempotency mechanism before retrying a write after an uncertain network result.
  • Do not send organization IDs with an organization token; its organization scope is fixed.

Errors and retries

Native API failures contain an error object with a machine-readable code and human-readable message. Handle the code rather than matching message text.

Correct 400, 401, 403, and 409 requests before retrying. Follow Retry-After for 429. Retry transient server or network failures with bounded exponential backoff and idempotency where supported.

Choose a guide