API REST Pública

Conecte o Cadenio a todo o seu stack

Automatize workflows de compliance, sincronize dados de runs com sistemas externos e construa dashboards personalizados usando API keys com escopo e uma interface REST padrão.

Crie uma API key

Acesse Configurações → Integrações e crie uma nova key. Selecione apenas os escopos que a integração exige.

Faça uma requisição

Inclua a key no header Authorization: Bearer. A URL base é https://api.cadenio.com/v1.

Trate a resposta

Todas as respostas são JSON com campos em snake_case. Erros incluem um campo code legível por máquina.

Autenticação

Autenticação via Bearer token

Todas as requisições à API precisam incluir uma API key válida no header Authorization usando o esquema Bearer. As keys têm prefixo sk_live_ e estão disponíveis para organizações Enterprise em Configurações → Integrações.

Atenção: A API key é exibida apenas uma vez no momento da criação. Armazene-a com segurança — ela não pode ser recuperada depois. Se perdida, revogue e crie uma nova.

Header obrigatório

Authorizationstringobrigatório

Deve ser Bearer seguido da sua API key sk_live_.

Content-Typestringopcional

Obrigatório para requisições POST e PATCH. Definir como application/json.

Requisição

curl https://api.cadenio.com/v1/runs \
  -H "Authorization: Bearer sk_live_a1b2c3..." \
  -H "Content-Type: application/json"

Escopos

Referência de escopos

Cada API key possui um conjunto de escopos que define exatamente quais operações ela pode executar. Requisições de sessão (UI) são sempre permitidas independentemente dos escopos configurados. O controle de escopo se aplica apenas a requisições via API key.

Escopo	Descrição
`runs:read`	Leitura de lista e detalhes de runs
`runs:write`	Atualização de tarefas em um run
`runs:execute`	Iniciar novos runs a partir de um template
`templates:read`	Leitura de lista e detalhes de templates
`templates:write`	Criação e atualização de templates
`templates:publish`	Publicar um rascunho de template
`files:read`	Download de arquivos anexados a runs
`files:write`	Upload de arquivos para tarefas de runs
`data-sources:read`	Leitura de registros de fontes de dados
`data-sources:write`	Criação e atualização de registros de fontes de dados
`users:read`	Leitura da lista de membros da organização
`webhooks:manage`	Criar, listar e excluir endpoints de webhook

Rate limits

Limites de requisição

Os rate limits são aplicados por API key — não por organização. Cada key tem sua própria cota independente.

600 requisições por minuto por API key
As respostas incluem os headers X-RateLimit-Remaining e X-RateLimit-Reset
Exceder o limite retorna HTTP 429 com header Retry-After
Keys diferentes na mesma org não compartilham cota

Headers de rate limit

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594
X-RateLimit-Reset: 1746000060

Resposta 429

HTTP/1.1 429 Too Many Requests
Retry-After: 8

{
  "code": "RATE_LIMITED",
  "message": "Rate limit exceeded. Retry after 8 seconds."
}

Códigos de erro

Todos os erros retornam um corpo JSON com o campo code (legível por máquina) e o campo message (legível por humano). O status HTTP reflete a classe do erro.

Status	Código / descrição
400	`INVALID_REQUEST`JSON malformado ou campo obrigatório ausente
401	`UNAUTHORIZED`API key ausente ou inválida
401	`KEY_EXPIRED`API key expirada
401	`KEY_REVOKED`API key foi revogada
403	`MISSING_SCOPE`Key não possui o escopo necessário para esta ação
403	`PLAN_REQUIRED`Recurso exige um plano superior
404	`NOT_FOUND`Recurso não existe ou não está acessível
409	`CONFLICT`Conflito de estado — ex.: run já concluído
422	`UNPROCESSABLE`Requisição semanticamente inválida — ex.: valor de escopo inválido
429	`RATE_LIMITED`Rate limit excedido. Verifique o header Retry-After
500	`INTERNAL_ERROR`Erro interno do servidor. Contate o suporte se persistir

Resposta de erro

HTTP/1.1 403 Forbidden

{
  "code": "MISSING_SCOPE",
  "message": "This action requires the 'runs:write' scope.",
  "required_scope": "runs:write"
}

Runs

Um run é uma instância de execução de um template. Representa um processo em andamento ou concluído, com tarefas atribuídas, prazos e trilha de auditoria.

GET/v1/runsruns:read

Listar runs

Retorna uma lista paginada de runs da organização. Resultados são ordenados por data de criação, mais recentes primeiro. Use parâmetros de consulta para filtrar por status, template ou responsável.

Parâmetros

statusstringopcional

Filtrar por status do run. Um de: IN_PROGRESS, COMPLETED, OVERDUE, CANCELLED.

template_idstringopcional

Filtrar runs iniciados de um template específico.

assignee_idstringopcional

Filtrar pelo usuário atribuído como responsável.

limitintegeropcional

Número de runs por página. Padrão: 20, máximo: 100.

cursorstringopcional

Cursor de paginação do campo next_cursor da resposta anterior.

Requisição

curl -G https://api.cadenio.com/v1/runs \
  -H "Authorization: Bearer sk_live_..." \
  -d status=IN_PROGRESS \
  -d limit=20

Resposta

{
  "data": [
    {
      "id": "run_abc123",
      "name": "Vendor Onboarding — ACME Corp",
      "status": "IN_PROGRESS",
      "template_id": "tmpl_def456",
      "assignee_id": "usr_ghi789",
      "due_date": "2026-05-01T00:00:00Z",
      "created_at": "2026-04-10T14:22:00Z",
      "completed_at": null
    }
  ],
  "next_cursor": "cur_xyz",
  "has_more": true
}

POST/v1/runsruns:execute

Iniciar um run

Cria um novo run a partir de um template publicado. O run abre imediatamente com status IN_PROGRESS e todas as tarefas geradas da definição do template.

Parâmetros

template_idstringobrigatório

ID do template a ser iniciado.

namestringopcional

Nome de exibição personalizado. Padrão: nome do template.

assignee_idstringopcional

ID do usuário a ser atribuído como responsável.

due_datedatetimeopcional

Timestamp ISO 8601 para o prazo SLA do run.

form_dataobjectopcional

Mapa chave-valor de IDs de campos do formulário para pré-preencher.

Requisição

curl -X POST https://api.cadenio.com/v1/runs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tmpl_def456",
    "name": "Vendor Onboarding — ACME Corp",
    "assignee_id": "usr_ghi789",
    "due_date": "2026-05-01T00:00:00Z"
  }'

Resposta

HTTP/1.1 201 Created

{
  "id": "run_abc123",
  "name": "Vendor Onboarding — ACME Corp",
  "status": "IN_PROGRESS",
  "template_id": "tmpl_def456",
  "assignee_id": "usr_ghi789",
  "due_date": "2026-05-01T00:00:00Z",
  "created_at": "2026-04-10T14:22:00Z"
}

PATCH/v1/runs/:id/tasks/:taskIdruns:write

Atualizar uma tarefa

Atualiza o status, valor, responsável ou prazo de uma tarefa em um run. Concluir a última tarefa obrigatória de um run transiciona automaticamente o status do run para COMPLETED.

Parâmetros

statusstringopcional

Definir status da tarefa. Um de: COMPLETED, SKIPPED.

valueanyopcional

Valor do campo do formulário. O tipo depende da definição do campo.

assignee_idstringopcional

Reatribuir a tarefa a outro usuário.

due_datedatetimeopcional

Atualizar o prazo SLA da tarefa.

Requisição

curl -X PATCH \
  https://api.cadenio.com/v1/runs/run_abc123/tasks/task_jkl012 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "COMPLETED",
    "value": "Approved by legal review on 2026-04-10"
  }'

Resposta

HTTP/1.1 200 OK

{
  "id": "task_jkl012",
  "run_id": "run_abc123",
  "status": "COMPLETED",
  "value": "Approved by legal review on 2026-04-10",
  "completed_at": "2026-04-10T16:05:00Z",
  "completed_by": "usr_ghi789"
}

Templates

Templates são os blueprints de processo. Um template define a sequência de tarefas, regras de atribuição, campos de formulário e critérios de aprovação que cada run herda.

Método	Endpoint	Escopo	Descrição
GET	/v1/templates	`templates:read`	Listar todos os templates publicados
GET	/v1/templates/:id	`templates:read`	Obter um template
POST	/v1/templates	`templates:write`	Criar um rascunho de template
PATCH	/v1/templates/:id	`templates:write`	Atualizar um rascunho de template
POST	/v1/templates/:id/publish	`templates:publish`	Publicar um rascunho de template

Webhooks

Webhooks entregam notificações de eventos em tempo real para o seu sistema. Cada payload inclui um header X-Cadenio-Signature com uma assinatura HMAC-SHA256 para validação.

POST/v1/webhookswebhooks:manage

Registrar um webhook

Registra um novo endpoint de webhook. O Cadenio enviará requisições POST para a URL especificada quando os eventos assinados ocorrerem. Verifique o header X-Cadenio-Signature para garantir que os payloads são originados do Cadenio.

Parâmetros

urlstringobrigatório

Endpoint HTTPS para entrega dos payloads de evento.

eventsstring[]obrigatório

Lista de eventos para assinar. Use ["*"] para todos os eventos.

run.completedrun.overduetask.completedrun.created

descriptionstringopcional

Rótulo legível por humano para este endpoint de webhook.

secretstringopcional

Segredo de assinatura para verificar autenticidade do payload via HMAC-SHA256.

Requisição

curl -X POST https://api.cadenio.com/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-system.com/hooks/cadenio",
    "events": ["run.completed", "run.overdue"],
    "description": "Sync to ERP on run completion"
  }'

Payload de exemplo

POST https://your-system.com/hooks/cadenio
X-Cadenio-Signature: sha256=...

{
  "event": "run.completed",
  "timestamp": "2026-04-10T16:05:00Z",
  "data": {
    "run_id": "run_abc123",
    "template_id": "tmpl_def456",
    "completed_at": "2026-04-10T16:05:00Z"
  }
}

Arquivos

Upload e download de arquivos anexados a tarefas de runs. Os arquivos são limitados à organização e acessíveis apenas por meio de runs pertencentes a ela.

Método	Endpoint	Escopo	Descrição
GET	/v1/files/:id	`files:read`	Baixar um arquivo anexado
POST	/v1/files	`files:write`	Upload de arquivo (multipart/form-data)

Fontes de dados

Leitura e escrita de registros em fontes de dados da organização. Fontes de dados são tabelas estruturadas usadas para preencher campos de formulário e orientar lógica condicional em templates.

Método	Endpoint	Escopo	Descrição
GET	/v1/data-sources	`data-sources:read`	Listar fontes de dados
GET	/v1/data-sources/:id/records	`data-sources:read`	Listar registros
POST	/v1/data-sources/:id/records	`data-sources:write`	Criar um registro
PATCH	/v1/data-sources/:id/records/:rid	`data-sources:write`	Atualizar um registro

Usuários

Leitura da lista de membros da organização. Use os IDs de membros para atribuir runs e tarefas via API de Runs.

Método	Endpoint	Escopo	Descrição
GET	/v1/users	`users:read`	Listar membros da organização

Gerenciamento de API keys

Gerenciando API keys

API keys são criadas e revogadas em Configurações → Integrações. Cada key tem nome, conjunto de escopos, data de expiração opcional e modo de recurso (todos os recursos ou um subconjunto selecionado de templates e pastas). Proprietários e admins da organização podem gerenciar as keys. Cada key é exibida por completo apenas uma vez na criação.

Importante: Esses endpoints exigem autenticação de sessão (cookie), não via API key. Uma API key não pode gerenciar outras API keys.

Endpoints

GET/v1/api-keysListar API keys ativas

POST/v1/api-keysCriar uma nova API key

DELETE/v1/api-keys/:idRevogar uma API key

Requisição

curl -X POST https://api.cadenio.com/v1/api-keys \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ERP Sync Integration",
    "scopes": ["runs:read", "runs:execute"],
    "resource_mode": "ALL"
  }'

Resposta

HTTP/1.1 201 Created

{
  "id": "key_mno345",
  "name": "ERP Sync Integration",
  "plain_key": "sk_live_a1b2c3d4e5f6...",
  "key_prefix": "sk_live_...a1b2",
  "scopes": ["runs:read", "runs:execute"],
  "resource_mode": "ALL",
  "expires_at": null,
  "created_at": "2026-04-10T12:00:00Z"
}

// plain_key is shown only once — store it securely.

Acesso à API pública requer plano Enterprise

API keys, permissões com escopo e acesso programático aos dados de runs estão disponíveis no plano Enterprise. Fale conosco para habilitar na sua organização.

Falar com especialista Ver plano Enterprise