Os endpoints da API v1 agrupados por tema, com o scope que cada um pede, e quais áreas são só do painel.

O contrato legível por máquina está no repositório, em packages/openapi/openapi.yaml (OpenAPI 3.1). Esta página resume o que você pode usar com uma chave de API. As áreas marcadas como "só painel" usam a sessão de uma pessoa da equipe (veja Autenticação).

Agenda: horários e agendamentos

Método	Path	Scope	Descrição
GET	`/slots`	`slots:read`	Horários disponíveis para um serviço
POST	`/holds`	`bookings:write`	Criar pré-reserva de 10 minutos
POST	`/holds/{id}/confirm`	`bookings:write`	Confirmar (ou `pending_payment` se exigir sinal)
DELETE	`/holds/{id}`	`bookings:write`	Liberar pré-reserva
POST	`/bookings`	`bookings:write`	Pré-reserva e confirmação em uma chamada
GET	`/bookings`	`bookings:read`	Listar (`from`, `to`, `status`, `resource_id`, `customer_id`)
GET / PATCH	`/bookings/{id}`	`bookings:read` / `write`	Ler, atualizar notas ou dados de entrada
POST	`/bookings/{id}/cancel`, `/reschedule`, `/check-in`, `/no-show`, `/complete`, `/fail`	`bookings:write`	Mudar o estado

Trabalho: tarefas e ações

Um agendamento é uma tarefa com etapas. As tarefas sem horário (por exemplo entregas) ficam na fila de um grupo até alguém pegá-las. Veja Trabalho e ações.

Método	Path	Scope	Descrição
GET	`/work-items`	`bookings:read`	Consulta unificada: filtros por `view` (`inbox`, `today`, `upcoming`), `status`, `stage`, `unassigned`, `priority`, `tag`, `origin`, `q`, intervalo de datas e caixa geográfica
PATCH	`/work-items/{id}`	`bookings:write`	Mudar prioridade, etiquetas ou prazo (com `expected_version` opcional)
POST	`/bookings/{id}/actions/{key}`	`bookings:write`	Executar uma ação da etapa (pegar, soltar, concluir, "não estava"…) com `Idempotency-Key`
GET	`/bookings/{id}/stage-history`	`bookings:read`	Histórico de etapas
GET	`/bookings/{id}/comments`, `/timeline`	`bookings:read`	Comentários e linha do tempo
GET	`/bookings/{id}/attachments`, `/location-events`	`bookings:read`	Evidência de trabalho
GET	`/conversations/{id}/work-items`	`bookings:read`	Tarefas criadas a partir de uma conversa
GET	`/team/overview`, `/resources/{id}/stats`	`bookings:read`	Ocupação e estatísticas da equipe

Catálogo e etapas

Método	Path	Scope
GET / POST	`/services`, `/resources`, `/resource-groups`, `/schedules`	`config:read` / `config:write`
GET / PATCH / DELETE	`/services/{id}`, `/resources/{id}`, `/resource-groups/{id}`, `/schedules/{id}`	`config:read` / `config:write`
POST / DELETE	`/schedules/{id}/overrides`, `/schedules/{id}/overrides/{date}`	`config:write`
GET	`/schedule-overrides`	`config:read`
GET	`/stage-config`, `/stage-config/versions`, `/stage-config/versions/{version}`	`config:read`
PUT	`/stage-config`	`settings:write`
POST	`/stage-config/versions/{version}/revert`	`settings:write`

Clientes

Método	Path	Scope	Descrição
GET	`/customers`	`customers:read`	Listar e buscar (`q`: nome, e-mail, empresa, etiqueta ou telefone; `phone`, `tag`)
POST	`/customers`	`customers:write`	Cadastro manual. O telefone é único: se já existir, `409 customer_exists`
GET / PATCH	`/customers/{id}`	`customers:read` / `write`	Ler ou editar (inclui endereço com `formatted`, `lat` e `lng`)
GET	`/customers/{id}/bookings`, `/summary`, `/timeline`, `/comments`	`customers:read`	Histórico, resumo ao vivo, linha do tempo e comentários

Um cliente pode ter várias identidades (WhatsApp, Telegram, WebChat) em identities[].

Conversas

Método	Path	Scope
GET	`/conversations`, `/conversations/{id}`, `/conversations/{id}/messages`	`messages:read`
POST	`/conversations/{id}/messages`	`messages:write` (responde `409 channel_paused` se o canal está pausado)
POST	`/conversations/{id}/mode`, `/read`, `/resolve`	`messages:write`

Bot e conhecimento

Método	Path	Scope
GET / PUT	`/bot`	`config:read` / `config:write`
GET / POST	`/knowledge`, `/knowledge/files`	`config:read` / `config:write`
POST	`/knowledge/search`	`config:read`
PATCH / DELETE	`/knowledge/{id}`	`config:write`
GET / POST / PATCH	`/automations`, `/automations/{id}`	`config:read` / `config:write`

Webhooks de saída

Método	Path	Scope
GET / POST	`/webhook-endpoints`	`webhooks:manage`
GET / PATCH / DELETE	`/webhook-endpoints/{id}`	`webhooks:manage`
POST	`/webhook-endpoints/{id}/rotate-secret`, `/ping`, `/deliveries/{delivery_id}/resend`	`webhooks:manage`
GET	`/webhook-endpoints/{id}/deliveries`	`webhooks:manage`

Detalhes em Webhooks.

Plataforma

Método	Path	Scope
GET	`/me`	qualquer

Só painel (não aceitam chaves de API)

Área	Rotas
Canais e pausas	`/channels`, `/channels/whatsapp`, `/channels/telegram`, `/channels/service-status`, `/channels/pauses`, `/channels/{channel}/pause` e `/resume`; veja Pausas e Status
Política do bot por canal	`/bot/channel-policies` (veja WebChat)
Fontes de conhecimento	`/knowledge/sources` (veja Conhecimento)
Fluxos	`/automation-flows` (veja Fluxos)
IA do projeto	`/ai/usage`, `/ai/pause`, `/ai/resume`, `/ai/spam-guard`, `/ai/notices`
Wagy	`/assistant/*`, o assistente de configuração do painel
Equipe e conta	`/team/*`, `/api-keys`, `/workspaces`, `/me/telegram`, `/me/notification-preferences`
WebChat	`/webchat-site` (gestão) e `/public/webchat/*` (públicos, com a chave publicável do widget)

Exemplo: slots

GET /v1/slots?service_id=svc_laser&from=2026-10-20T09:00:00-03:00&to=2026-10-20T20:00:00-03:00&around=2026-10-20T18:00:00-03:00

{
  "data": [
    { "start": "2026-10-20T17:45:00-03:00", "end": "2026-10-20T18:30:00-03:00", "resource_ids": ["res_ana", "res_laser1", "res_room2"] },
    { "start": "2026-10-20T18:45:00-03:00", "end": "2026-10-20T19:30:00-03:00", "resource_ids": ["res_carla", "res_laser1", "res_room1"] }
  ],
  "unavailable_reason": null
}

Exemplo: objeto de agendamento

{
  "id": "bkg_7Qx1",
  "status": "confirmed",
  "stage": "confirmed",
  "service_id": "svc_laser",
  "start": "2026-10-20T17:45:00-03:00",
  "end": "2026-10-20T18:30:00-03:00",
  "party_size": 1,
  "customer": { "id": "cus_31", "name": "Marina", "phone": "+5521988887777", "locale": "pt" },
  "allocations": [
    { "resource_id": "res_ana", "start": "2026-10-20T17:45:00-03:00", "end": "2026-10-20T18:40:00-03:00" },
    { "resource_id": "res_laser1", "start": "2026-10-20T17:45:00-03:00", "end": "2026-10-20T18:40:00-03:00" },
    { "resource_id": "res_room2", "start": "2026-10-20T17:45:00-03:00", "end": "2026-10-20T18:40:00-03:00" }
  ],
  "priority": "normal",
  "tags": [],
  "source": "whatsapp",
  "created_at": "2026-10-19T11:02:13-03:00"
}

As alocações incluem o buffer (aqui, 10 minutos depois do serviço). Nas tarefas com fila, start e end vêm como null até alguém pegá-las.

Novidades recentes

Estas são as novidades da API, todas aditivas. O histórico completo está no repositório (docs/api/CHANGELOG.md).

Clientes: cadastro manual, dados ampliados, endereço com formatted, lat e lng, e identities[] multicanal.
Tarefas e ações: consulta unificada GET /work-items, executor de ações com efeitos (pegar, soltar, resultados) e 409 already_claimed.
Mensagens com localização: WhatsApp, Telegram e WebChat guardam a localização compartilhada na conversa.
Pausas: ao pausar um canal, enviar uma mensagem responde 409 channel_paused.
Conhecimento: fontes do tipo site com max_pages e erros por causa.

Endpoints