Skip to content
Thirdlane

API Basics

This page covers the fundamentals every integration needs: authentication, base URLs, tenant scoping, pagination, and error handling. Examples use https://your-server.thirdlane.com as the server and acme as the tenant - substitute your own.

Authentication

Three methods are supported; pick one per request.

  • API key (recommended for integrations) - send an X-API-Key header. Create and revoke keys in API Keys. Keys can be scoped to a single tenant for least privilege.
  • Basic authentication - username and password.
  • Session cookie (sid) - used by the interactive docs UI and browser sessions.
Terminal window
curl -H "X-API-Key: YOUR_KEY" \
  https://your-server.thirdlane.com/api/endpoints

Prefer a dedicated key per integration so you can revoke one without disturbing the others.

Service plane discovery

The platform exposes a discovery endpoint that returns the base URL for each service plane. Resolve these once at startup instead of hardcoding paths - when a plane later moves to its own server, your code keeps working unchanged.

Terminal window
curl -H "X-API-Key: YOUR_KEY" \
  https://your-server.thirdlane.com/api/endpoints
{
  "management": "https://your-server.thirdlane.com/api",
  "reporting":  "https://your-server.thirdlane.com/api/reports",
  "messaging":  "https://your-server.thirdlane.com/api/messaging",
  "media":      "https://your-server.thirdlane.com",
  "connect_ws": "wss://your-server.thirdlane.com/xmpp-websocket"
}

Tenant scoping

Configuration and reporting objects are tenant-scoped on multi-tenant systems. Tenant-scoped endpoints include the tenant in the path, for example:

GET /api/reports/cdr/acme

A tenant-scoped API key is automatically limited to its own tenant. A global key can target any tenant. Single-tenant systems omit tenant scoping.

Pagination

List endpoints accept limit and offset query parameters and return pagination metadata in response headers.

Terminal window
curl -H "X-API-Key: YOUR_KEY" \
  "https://your-server.thirdlane.com/api/reports/cdr/acme?limit=100&offset=0"

Response headers:

  • X-Total-Count - total number of matching records
  • X-Pagination-Limit - the applied limit
  • X-Pagination-Offset - the applied offset

Without limit/offset, list endpoints return all matching records.

Errors

Errors return a non-2xx status and a JSON body with an error message (and sometimes diagnostic output).

{
  "error": "access denied: channel is not in your tenant"
}

Always check the HTTP status and the error field. For bulk operations, also check per-record results so a single bad row does not silently skip the rest.