Basics

Base URL

https://api.alia.cx/api/v1

Every request uses HTTPS. Request and response bodies are JSON, and timestamps are ISO 8601 strings in UTC.

Authentication

Send your API key as a bearer token on every request:

Authorization: Bearer alia_live.<key id>.<secret>

A missing, revoked, or malformed key gets 401. A valid key gets 403 when it lacks the scope, or when the agency ID is not one of its agencies. The 403 is the same whether or not that agency exists. See API keys.

Errors

Every error has the same body:

{
  "_tag": "PartnerBadRequest",
  "message": "Invalid query parameter \"pageSize\": expected a value between 1 and 100"
}

_tag names the error type and message explains it. Show or log message, but don't match on its text: it may change. Match on the status code or _tag.

Every response carries an X-Correlation-Id header. Include it when you contact Alia support.

Pagination

List endpoints return one page at a time.

• pageSize sets the page size: 1 to 100, default 50.
• The response includes nextCursor. While it is not null, pass it as cursor to get the next page.
• Treat cursors as opaque strings. Don't build or edit them, and don't store them for later. An invalid cursor gets 400.

Phone numbers

Conversations are keyed by the contact's phone number. Use E.164 format, such as +32470123456, and write the + as %2B in URL paths. See Conversations.

Endpoints

OpenAPI file

The contract is available as OpenAPI 3.1 at /openapi/openapi.json and at https://api.alia.cx/api/v1/openapi.json.