API Channel

The API Channel is Diska's public REST surface: a set of versioned endpoints, authenticated with organization API keys, built for server-to-server integrations — sync calls and transcripts into your CRM, create and publish agents, feed knowledge bases and receive event webhooks instead of polling.

Base URL

https://api.diska.ai/v1

Note: the API Channel base is /v1, separate from the backoffice's internal API (/api/v1). Only the endpoints documented on this page accept API keys.

Authentication

Create a key under Settings → API Keys in the backoffice (the full dsk_… key is shown only once). Send it with every request:

GET /v1/agents
Authorization: Bearer dsk_a1b2c3…

Alternatively, the X-API-Key: dsk_… header is also accepted.

Scopes

When creating a key you can restrict it to specific scopes. A key without scopes has full access (the original contract); with scopes, only those endpoints respond — the rest return 403.

Expiry

A key may carry expires_at (set at creation). Past that date it responds 401 with "Chave de API expirada". Without expires_at, the key is valid until revoked.

First request

Confirm which organization and key the token belongs to:

curl https://api.diska.ai/v1/me \
  -H "Authorization: Bearer dsk_a1b2c3…"

{
  "organization": { "id": "…", "name": "My Company", "slug": "my-company" },
  "key": { "id": "…", "name": "CRM integration", "key_preview": "dsk_a1b2…F5A4", "scopes": [], "expires_at": null, "created_at": "…", "last_used_at": "…" }
}

The channel's full OpenAPI specification is available at GET /v1/openapi.json (no authentication) — import it into Postman or generate a typed client.

Endpoints

All endpoints return JSON. Resources always belong to the key's organization — identifiers from another organization respond 404.

Identity

Agents

GET /v1/agents parameters: agent_type (inbound, outbound, voice_widget, chat), status (draft, active, inactive, archived), search.

POST /v1/agents body: name, agent_type, editing_mode (prompt | flow) and optionally template_id to install from a template. The agent is born as a draft — publish it to make it usable.

Each agent returns the operational fields (id, name, slug, description, status, agent_type, editing_mode, version, phone_number, public_channel_enabled, created_at, updated_at) — internal builder configuration is not exposed.

Calls

/v1/calls parameters: search, agent_id, status (created, active, completed, failed, cancelled, abandoned), channel, limit (1–200, default 50), offset, cursor.

Cursor pagination (recommended for exporting large histories — constant cost at any depth):

1. First request: GET /v1/calls?cursor=start&limit=100.
2. The response carries next_cursor; repeat with cursor=<next_cursor>.
3. When next_cursor is null, you reached the end.

In cursor mode, total comes back null (counting would require the very scan cursors avoid) and search is not supported. The classic offset mode (limit/offset with exact total) remains available.

Analytics

Parameters: period (daily, weekly, monthly), agent_id, agent_type (all, inbound, outbound).

Phone numbers

Knowledge

Webhooks

Events, HMAC signature and retry policy: see Webhooks.

Rate limits

Requests are limited per key (default 120 requests/minute; keys may carry their own limit set at creation via rate_limit_per_minute). Over the limit, the API responds 429 with the Retry-After, X-RateLimit-Limit and X-RateLimit-Remaining headers.

Errors

Error bodies follow the FastAPI format: { "detail": "…" }.

Future

Coming in later iterations of the channel: starting calls via API (once outbound telephony is connected), additional webhook events (call.failed, realtime call states), programmatic key management and bulk exports.