Canal API

O Canal API é a superfície REST pública da Diska: um conjunto de endpoints versionados, autenticados com as chaves API da organização, pensados para integrações servidor-a-servidor — sincronizar chamadas e transcrições com o seu CRM, criar e publicar agentes, alimentar bases de conhecimento e receber webhooks de eventos sem polling.

Base URL

https://api.diska.ai/v1

Nota: a base do Canal API é /v1, separada da API interna do backoffice (/api/v1). Só os endpoints documentados nesta página aceitam chaves API.

Autenticação

Crie uma chave em Definições → Chaves API no backoffice (a chave completa dsk_… só é mostrada uma vez). Envie-a em cada pedido:

GET /v1/agents
Authorization: Bearer dsk_a1b2c3…

Em alternativa, o cabeçalho X-API-Key: dsk_… também é aceite.

Âmbitos (scopes)

Ao criar a chave pode restringi-la a âmbitos específicos. Uma chave sem âmbitos tem acesso total (o contrato original); com âmbitos, só esses endpoints respondem — os restantes devolvem 403.

Expiração

Uma chave pode ter expires_at (definido na criação). Depois dessa data responde 401 com "Chave de API expirada". Sem expires_at, a chave vale até ser revogada.

Primeiro pedido

Confirme a que organização e chave o token pertence:

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

{
  "organization": { "id": "…", "name": "A Minha Empresa", "slug": "a-minha-empresa" },
  "key": { "id": "…", "name": "Integração CRM", "key_preview": "dsk_a1b2…F5A4", "scopes": [], "expires_at": null, "created_at": "…", "last_used_at": "…" }
}

A especificação OpenAPI completa do canal está disponível em GET /v1/openapi.json (sem autenticação) — importe-a no Postman ou gere um cliente tipado.

Endpoints

Todos os endpoints devolvem JSON. Os recursos pertencem sempre à organização da chave — identificadores de outra organização respondem 404.

Identidade

Agentes

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

Corpo de POST /v1/agents: name, agent_type, editing_mode (prompt | flow) e, opcionalmente, template_id para instalar a partir de um modelo. O agente nasce como rascunho — publique-o para o tornar utilizável.

Cada agente devolve os campos operacionais (id, name, slug, description, status, agent_type, editing_mode, version, phone_number, public_channel_enabled, created_at, updated_at) — a configuração interna do builder não é exposta.

Chamadas

Parâmetros de /v1/calls: search, agent_id, status (created, active, completed, failed, cancelled, abandoned), channel, limit (1–200, padrão 50), offset, cursor.

Paginação por cursor (recomendada para exportar históricos grandes — custo constante a qualquer profundidade):

1. Primeiro pedido: GET /v1/calls?cursor=start&limit=100.
2. A resposta traz next_cursor; repita com cursor=<next_cursor>.
3. Quando next_cursor for null, chegou ao fim.

Em modo cursor, total vem null (contar exigiria o varrimento completo que o cursor evita) e search não é suportado. O modo offset clássico (limit/offset com total exacto) continua disponível.

Análises

Parâmetros: period (daily, weekly, monthly), agent_id, agent_type (all, inbound, outbound).

Números

Conhecimento

Webhooks

Eventos, assinatura HMAC e política de retries: ver Webhooks.

Limites de utilização

Os pedidos são limitados por chave (por omissão 120 pedidos/minuto; chaves podem ter um limite próprio definido na criação via rate_limit_per_minute). Acima do limite, a API responde 429 com os cabeçalhos Retry-After, X-RateLimit-Limit e X-RateLimit-Remaining.

Erros

O corpo do erro segue o formato FastAPI: { "detail": "…" }.

Futuro

Nas próximas iterações do canal estão previstos: iniciar chamadas por API (quando a telefonia de saída estiver ligada), eventos de webhook adicionais (call.failed, estados em tempo real), gestão programática de chaves e exportações em massa.