Conventions

Purpose

Describe the conventions every Get2Dial API endpoint shares so you only have to learn them once.

Overview

Base URL — application routes are under /api/v1 (e.g. https://api.get2dial.com/api/v1/...). Health/metrics (/healthz, /readyz, /metrics) and WebSockets (/ws/...) are at the root.
Content type — request and response bodies are JSON (Content-Type: application/json). Request bodies are capped at 1 MB and unknown fields are rejected, so send exactly the documented fields.
Tenant scoping — every authenticated request is pinned to the caller’s tenant from its JWT. A platform_admin may target another tenant with a ?tenant_id=<uuid> query parameter on tenant-scoped endpoints; other roles cannot.

The response envelope

Every endpoint returns the same shell:

{
  "status": "success",
  "message": "optional human-readable message",
  "data": { },
  "total": 0,
  "limit": 0,
  "offset": 0
}

status is success or error.
data carries the result (an object or an array); omitted when empty.
message is present mainly on errors.
total / limit / offset appear on list endpoints for pagination.

Pagination

List endpoints accept limit and offset query parameters and echo them back alongside total (the full count before paging):

curl -s 'https://api.get2dial.com/api/v1/cdrs?limit=50&offset=100' \
  -H 'Authorization: Bearer <jwt>'

{
  "status": "success",
  "data": [ { "call_id": "…", "direction": "outbound", "status": "answered" } ],
  "total": 1342,
  "limit": 50,
  "offset": 100
}

Examples

A single-object response (GET /api/v1/auth/me):

{
  "status": "success",
  "data": {
    "id": "…",
    "tenant_id": "…",
    "email": "agent@example.com",
    "role": "agent",
    "status": "active",
    "must_change_password": false,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
  }
}

Notes

Timestamps are RFC 3339 / ISO 8601 in UTC (e.g. 2026-07-01T12:00:00Z).
Because unknown request fields are rejected, a typo’d field name returns 400, not a silent no-op.
List filters are endpoint-specific (e.g. CDRs accept from, to, disposition) — see Endpoints.