Início › Desenvolvedores › Referência da API

Referência da API

Todos os endpoints da API v1, gerados da mesma especificação OpenAPI que a API usa.

Base: https://aideed.com.br/api/developers/v1. Especificação OpenAPI 3.1 em /api/developers/v1/openapi.json para gerar clientes e importar no Postman ou Insomnia.

Endpoints

Método	Caminho	Scope	O que faz
GET	/me	qualquer	A integração da chave: empresa, ambiente, permissões, agentes e limites
GET	/workforce	workforce:read	O Workforce que esta integração enxerga
GET	/agents	agents:read	Os funcionários digitais autorizados para esta integração
GET	/agents/{agent_id}	agents:read	Um agente autorizado
GET	/agents/{agent_id}/capabilities	agents:read	O que o agente faz, quando chama uma pessoa, o que nunca faz e os sistemas conectados
POST	/agents/{agent_id}/tasks	tasks:write	Pedir uma tarefa ao agente (assíncrona; aceita Idempotency-Key)
GET	/tasks	tasks:read	As tarefas desta integração, das mais novas para as mais antigas
GET	/tasks/{task_id}	tasks:read	O status de uma tarefa
GET	/tasks/{task_id}/result	tasks:read	O resultado (409 enquanto a tarefa não terminou)
POST	/tasks/{task_id}/cancel	tasks:cancel	Cancelar (aguardando aprovação, na fila ou em execução)
GET	/integrations/current/usage	workforce:read	Tarefas do mês por agente, cota incluída no salário e hora extra
GET	/webhooks	webhooks:manage	Os webhooks desta integração (nunca o segredo)
POST	/webhooks	webhooks:manage	Cadastrar um webhook (o segredo aparece só nesta resposta)
GET	/webhooks/{webhook_id}	webhooks:manage	Um webhook
PATCH	/webhooks/{webhook_id}	webhooks:manage	Alterar URL, eventos, descrição ou pausar
DELETE	/webhooks/{webhook_id}	webhooks:manage	Remover um webhook
POST	/webhooks/{webhook_id}/test	webhooks:manage	Enviar agora um evento webhook.test assinado
POST	/webhooks/{webhook_id}/rotate-secret	webhooks:manage	Novo segredo (o anterior continua assinando por 24 horas)
GET	/webhooks/{webhook_id}/deliveries	webhooks:manage	Entregas recentes (status: pending, retrying, delivered, failed)
POST	/webhooks/{webhook_id}/deliveries/{delivery_id}/resend	webhooks:manage	Reenviar uma entrega

GET /me

A integração da chave: empresa, ambiente, permissões, agentes e limites. Scope: qualquer.

GET /workforce

O Workforce que esta integração enxerga. Scope: workforce:read.

GET /agents

Os funcionários digitais autorizados para esta integração. Scope: agents:read.

GET /agents/{agent_id}

Um agente autorizado. Scope: agents:read.

Parâmetro	Onde	Tipo	Obrigatório
agent_id	caminho	string	sim

GET /agents/{agent_id}/capabilities

O que o agente faz, quando chama uma pessoa, o que nunca faz e os sistemas conectados. Scope: agents:read.

Parâmetro	Onde	Tipo	Obrigatório
agent_id	caminho	string	sim

POST /agents/{agent_id}/tasks

Pedir uma tarefa ao agente (assíncrona; aceita Idempotency-Key). Scope: tasks:write.

Parâmetro	Onde	Tipo	Obrigatório
agent_id	caminho	string	sim
Idempotency-Key	cabeçalho	string	não

Campo do corpo	Tipo	Obrigatório	Descrição
input	string	sim	O pedido, em texto (até 8.000 caracteres)
context	object	não	Dados de apoio em JSON (até 16 KB)
external_ref	string	não	Seu identificador, devolvido na tarefa

GET /tasks

As tarefas desta integração, das mais novas para as mais antigas. Scope: tasks:read.

Parâmetro	Onde	Tipo	Obrigatório
status	query	string	não
agent_id	query	string	não
since	query	string	não
limit	query	integer	não
before	query	string	não

GET /tasks/{task_id}

O status de uma tarefa. Scope: tasks:read.

Parâmetro	Onde	Tipo	Obrigatório
task_id	caminho	string	sim

GET /tasks/{task_id}/result

O resultado (409 enquanto a tarefa não terminou). Scope: tasks:read.

Parâmetro	Onde	Tipo	Obrigatório
task_id	caminho	string	sim

POST /tasks/{task_id}/cancel

Cancelar (aguardando aprovação, na fila ou em execução). Scope: tasks:cancel.

Parâmetro	Onde	Tipo	Obrigatório
task_id	caminho	string	sim

GET /integrations/current/usage

Tarefas do mês por agente, cota incluída no salário e hora extra. Scope: workforce:read.

GET /webhooks

Os webhooks desta integração (nunca o segredo). Scope: webhooks:manage.

POST /webhooks

Cadastrar um webhook (o segredo aparece só nesta resposta). Scope: webhooks:manage.

Campo do corpo	Tipo	Obrigatório	Descrição
url	string	sim	https://… que recebe os eventos (http só no ambiente de testes)
events	lista de string	não	Eventos desejados; vazio = todos (lista em GET /me)
description	string	não

GET /webhooks/{webhook_id}

Um webhook. Scope: webhooks:manage.

Parâmetro	Onde	Tipo	Obrigatório
webhook_id	caminho	string	sim

PATCH /webhooks/{webhook_id}

Alterar URL, eventos, descrição ou pausar. Scope: webhooks:manage.

Parâmetro	Onde	Tipo	Obrigatório
webhook_id	caminho	string	sim

Campo do corpo	Tipo	Obrigatório	Descrição
url	string	não
events	lista de string	não
description	string	não
status	string	não	active | disabled

DELETE /webhooks/{webhook_id}

Remover um webhook. Scope: webhooks:manage.

Parâmetro	Onde	Tipo	Obrigatório
webhook_id	caminho	string	sim

POST /webhooks/{webhook_id}/test

Enviar agora um evento webhook.test assinado. Scope: webhooks:manage.

Parâmetro	Onde	Tipo	Obrigatório
webhook_id	caminho	string	sim

POST /webhooks/{webhook_id}/rotate-secret

Novo segredo (o anterior continua assinando por 24 horas). Scope: webhooks:manage.

Parâmetro	Onde	Tipo	Obrigatório
webhook_id	caminho	string	sim

GET /webhooks/{webhook_id}/deliveries

Entregas recentes (status: pending, retrying, delivered, failed). Scope: webhooks:manage.

Parâmetro	Onde	Tipo	Obrigatório
webhook_id	caminho	string	sim
status	query	string	não
limit	query	integer	não

POST /webhooks/{webhook_id}/deliveries/{delivery_id}/resend

Reenviar uma entrega. Scope: webhooks:manage.

Parâmetro	Onde	Tipo	Obrigatório
webhook_id	caminho	string	sim
delivery_id	caminho	string	sim

Objetos

Tarefa

{
  "id": "tsk_…", "object": "task", "agent_id": "agt_…", "agent_name": "Laura",
  "status": "running", "external_ref": "erp-4821", "input": "…", "context": {},
  "created_at": "…", "started_at": "…", "finished_at": null,
  "approval": {"required": true, "decided_at": "…", "reason": null},
  "overtime": false, "sandbox": false, "error": null, "source": "api"
}

Resultado

{"task_id": "tsk_…", "status": "completed", "output": {"text": "…"}, "error": null, "finished_at": "…"}

Pedido, dados e resultado ficam guardados por 180 dias; depois disso input, context e output voltam como null.

Mais do portal

Comece aqui: Visão geral · Primeiros passos

Guias: Autenticação · Conceitos · Tarefas e aprovações · Webhooks · Erros · Limites e cota · Ambiente de testes · MCP do Workforce

Referência: Referência da API · Exemplos de código · Versões e mudanças

Dados públicos: API pública do catálogo · MCP do catálogo público