Tema
Referência da API
API REST v1. Erros em application/problem+json (RFC 9457). Paginação por cursor. Webhooks assinados com HMAC-SHA256.
Versão 0.1.0. Gerado de openapi.json — não edite à mão.
Sessão do painel web
Entrar (painel web)
http
POST /api/v1/auth/loginCorpo: LoginInput
Respostas: 200 Me — Define o cookie de sessão · 401 · 429
Sair
http
POST /api/v1/auth/logoutRespostas: 204
Usuário logado
http
GET /api/v1/auth/meAutenticação: session
Respostas: 200 Me · 401
Uso das telas (painel)
http
POST /api/v1/telemetryLote de até 50 eventos do painel: tela aberta e tempo nela, ou ação marcada. Uso interno do painel (sessão).
Autenticação: session
Corpo: UiBatch
Respostas: 204 · 400 · 401
Espaços: times ou clientes; a key é o prefixo dos cartões
Listar espaços
http
GET /api/v1/spacesAutenticação: api_key (boards:read) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
limit | query | integer | 1 a 100 (padrão 50). |
cursor | query | string |
Respostas: 200 SpacePage · 400 — Parâmetros inválidos · 401
Criar espaço
http
POST /api/v1/spacesAceita o header Idempotency-Key: repetir a chamada com a mesma chave em até 24 h devolve a mesma resposta sem duplicar.
Autenticação: api_key (boards:write) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
Idempotency-Key | header | string (opcional) | Chave única da operação (até 100 caracteres) |
Corpo: NewSpace
Respostas: 201 Space · 400 · 403 · 409 — Key já usada na empresa
Buscar espaço
http
GET /api/v1/spaces/{id}Autenticação: api_key (boards:read) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
id | path | integer |
Respostas: 200 Space · 404
Apagar espaço
http
DELETE /api/v1/spaces/{id}Autenticação: api_key (boards:write) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
id | path | integer |
Respostas: 204 · 404 · 409 — Espaço com quadros
Alterar espaço
http
PATCH /api/v1/spaces/{id}Autenticação: api_key (boards:write) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
id | path | integer |
Corpo: SpacePatch
Respostas: 200 Space · 400 · 404
Quadros e suas colunas
Listar quadros
http
GET /api/v1/boardsAutenticação: api_key (boards:read) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
space_id | query | integer | Só os quadros deste espaço. |
limit | query | integer | 1 a 100 (padrão 50). |
cursor | query | string |
Respostas: 200 BoardPage · 400 — Parâmetros inválidos · 401
Criar quadro
http
POST /api/v1/boardsCria o quadro com as colunas A fazer, Fazendo e Feito. Aceita o header Idempotency-Key.
Autenticação: api_key (boards:write) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
Idempotency-Key | header | string (opcional) | Chave única da operação (até 100 caracteres) |
Corpo: NewBoard
Respostas: 201 Board · 400 · 403 · 404 — Espaço não encontrado
Buscar quadro (com colunas)
http
GET /api/v1/boards/{id}Autenticação: api_key (boards:read) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
id | path | integer |
Respostas: 200 Board · 404
Apagar quadro
http
DELETE /api/v1/boards/{id}Autenticação: api_key (boards:write) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
id | path | integer |
Respostas: 204 · 404 · 409 — Quadro com cartões
Alterar quadro
http
PATCH /api/v1/boards/{id}Autenticação: api_key (boards:write) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
id | path | integer |
Corpo: BoardPatch
Respostas: 200 Board · 400 · 404
Cartões: aceitam id ou chave (DEV-12)
Listar cartões
http
GET /api/v1/cardsAutenticação: api_key (cards:read) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
board_id | query | integer | Só os cartões deste quadro. |
column_id | query | integer | Só os cartões desta coluna. |
assignee_id | query | integer | Só os cartões desta pessoa. |
label | query | string | Só os cartões com esta etiqueta (sem diferença de maiúsculas). |
limit | query | integer | 1 a 100 (padrão 50). |
cursor | query | string |
Respostas: 200 CardPage · 400 — Parâmetros inválidos · 401
Criar cartão
http
POST /api/v1/cardsCria o cartão no fim da coluna (padrão: a primeira do quadro) com a próxima chave do espaço. Aceita o header Idempotency-Key.
Autenticação: api_key (cards:write) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
Idempotency-Key | header | string (opcional) | Chave única da operação (até 100 caracteres) |
Corpo: NewCard
Respostas: 201 Card · 400 · 403 · 404 — Quadro não encontrado
Buscar cartão
http
GET /api/v1/cards/{card}Autenticação: api_key (cards:read) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
card | path | string | Id ou chave (ex.: DEV-12) |
Respostas: 200 Card · 404
Apagar cartão
http
DELETE /api/v1/cards/{card}Autenticação: api_key (cards:write) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
card | path | string | Id ou chave (ex.: DEV-12) |
Respostas: 204 · 404
Alterar cartão
http
PATCH /api/v1/cards/{card}Autenticação: api_key (cards:write) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
card | path | string | Id ou chave (ex.: DEV-12) |
Corpo: CardPatch
Respostas: 200 Card · 400 · 404
Trocar etiquetas do cartão
http
PUT /api/v1/cards/{card}/labelsSubstitui a lista inteira de etiquetas ([] tira todas). Até 10, de 1 a 30 caracteres; repetidas contam uma vez.
Autenticação: api_key (cards:write) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
card | path | string | Id ou chave (ex.: DEV-12) |
Corpo: CardLabels
Respostas: 200 Card · 400 · 404
Mover cartão
http
POST /api/v1/cards/{card}/moveMove para o fim de outra coluna do mesmo quadro. Entrar numa coluna done marca completed_at.
Autenticação: api_key (cards:write) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
card | path | string | Id ou chave (ex.: DEV-12) |
Corpo: CardMove
Respostas: 200 Card · 400 · 404
Comentários dos cartões
Listar comentários do cartão
http
GET /api/v1/cards/{card}/commentsAutenticação: api_key (cards:read) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
card | path | string | Id ou chave (ex.: DEV-12) |
limit | query | integer | 1 a 100 (padrão 50). |
cursor | query | string |
Respostas: 200 CommentPage · 400 — Parâmetros inválidos · 404
Comentar no cartão
http
POST /api/v1/cards/{card}/commentsAceita o header Idempotency-Key.
Autenticação: api_key (comments:write) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
card | path | string | Id ou chave (ex.: DEV-12) |
Idempotency-Key | header | string (opcional) | Chave única da operação (até 100 caracteres) |
Corpo: NewComment
Respostas: 201 Comment · 400 · 403 · 404
Apagar comentário
http
DELETE /api/v1/comments/{id}Só quem escreveu ou o dono da empresa.
Autenticação: api_key (comments:write) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
id | path | integer |
Respostas: 204 · 403 · 404
Pessoas da empresa (responsáveis pelos cartões)
Listar pessoas
http
GET /api/v1/usersPessoas da empresa que podem ser responsáveis por cartões (só id e nome).
Autenticação: api_key (cards:read) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
limit | query | integer | 1 a 100 (padrão 50). |
cursor | query | string |
Respostas: 200 PersonPage · 400 — Parâmetros inválidos · 401
Chaves para integrações
Listar API keys ativas
http
GET /api/v1/api-keysAutenticação: session
Respostas: 200 ApiKey[]
Criar API key
http
POST /api/v1/api-keysAutenticação: session
Corpo: NewApiKey
Respostas: 201 CreatedApiKey · 400
Revogar API key
http
DELETE /api/v1/api-keys/{id}Autenticação: session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
id | path | integer |
Respostas: 204 · 404
Notificações de eventos para sistemas externos
Reenviar uma entrega
http
POST /api/v1/webhook-deliveries/{id}/retryAutenticação: api_key (webhooks:manage) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
id | path | integer |
Respostas: 202 · 404
Listar endpoints de webhook
http
GET /api/v1/webhooksAutenticação: api_key (webhooks:manage) ou session
Respostas: 200 Endpoint[]
Cadastrar endpoint de webhook
http
POST /api/v1/webhooksAutenticação: api_key (webhooks:manage) ou session
Corpo: NewEndpoint
Respostas: 201 CreatedEndpoint · 400
Remover endpoint de webhook
http
DELETE /api/v1/webhooks/{id}Autenticação: api_key (webhooks:manage) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
id | path | integer |
Respostas: 204 · 404
Últimas 100 entregas de um endpoint
http
GET /api/v1/webhooks/{id}/deliveriesAutenticação: api_key (webhooks:manage) ou session
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
id | path | integer |
Respostas: 200 Delivery[] · 404
Modelos
ApiKey
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | integer | sim | |
name | string | sim | |
prefix | string | sim | Início da chave, para identificá-la (ex.: pk_live_a1b2). |
scopes | string[] | sim | |
created_at | integer | sim | |
last_used_at | integer (opcional) | não |
Board
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | integer | sim | |
space_id | integer | sim | |
name | string | sim | |
columns | Column[] | sim | |
created_at | integer | sim | Milissegundos desde 1970 (UTC). |
updated_at | integer | sim |
BoardPage
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
data | Board[] | sim | |
next_cursor | string (opcional) | não | Passe em cursor para buscar a próxima página; null quando acabou. |
BoardPatch
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string (opcional) | não |
Card
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | integer | sim | |
key | string | sim | Chave legível (ex.: DEV-12): aceita no lugar do id nas rotas e no MCP. |
space_id | integer | sim | |
board_id | integer | sim | |
column_id | integer | sim | |
title | string | sim | |
description | string | sim | |
position | integer | sim | Ordem dentro da coluna (menor = mais acima). |
created_at | integer | sim | Milissegundos desde 1970 (UTC). |
updated_at | integer | sim | |
completed_at | integer (opcional) | não | Quando entrou numa coluna done; null se não está concluído. |
priority | string (opcional) | não | low, medium, high ou urgent; null = sem prioridade. |
due_on | string (opcional) | não | Prazo AAAA-MM-DD; null = sem prazo. |
assignee_id | integer (opcional) | não | Pessoa responsável (veja GET /api/v1/users); null = ninguém. |
labels | string[] | sim | Etiquetas em ordem alfabética (ex.: cliente-acme, urgente). |
CardLabels
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
labels | string[] | sim | Lista completa de etiquetas do cartão (substitui a atual; [] tira todas). Até 10, de 1 a 30 caracteres. |
CardMove
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
column_id | integer | sim | Coluna de destino (do mesmo quadro). O cartão vai para o fim dela. |
CardPage
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
data | Card[] | sim | |
next_cursor | string (opcional) | não | Passe em cursor para buscar a próxima página; null quando acabou. |
CardPatch
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
title | string (opcional) | não | |
description | string (opcional) | não | |
priority | string (opcional) | não | low, medium, high ou urgent; null tira a prioridade. |
due_on | string (opcional) | não | Prazo AAAA-MM-DD; null tira o prazo. |
assignee_id | integer (opcional) | não | Pessoa responsável; null tira o responsável. |
Column
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | integer | sim | |
name | string | sim | |
kind | string | sim | backlog, todo, in_progress, review ou done (base das métricas de fluxo). |
position | integer | sim | Ordem da esquerda para a direita (1, 2, 3…). |
wip_limit | integer (opcional) | não | Limite de cartões em andamento; null = sem limite. |
Comment
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | integer | sim | |
card_id | integer | sim | |
author | string | sim | Nome de quem escreveu (pessoa ou "Integração pk_live_…"). |
author_user_id | integer (opcional) | não | Id da pessoa que escreveu; null quando veio de uma integração. |
body | string | sim | |
created_at | integer | sim | Milissegundos desde 1970 (UTC). |
CommentPage
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
data | Comment[] | sim | |
next_cursor | string (opcional) | não | Passe em cursor para buscar a próxima página; null quando acabou. |
CreatedApiKey
CreatedEndpoint
Delivery
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | integer | sim | |
event_id | string | sim | |
event_type | string | sim | |
status | string | sim | pending, delivered ou failed. |
attempts | integer | sim | |
last_status | integer (opcional) | não | |
last_error | string (opcional) | não | |
created_at | integer | sim | |
delivered_at | integer (opcional) | não |
Endpoint
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | integer | sim | |
url | string | sim | |
events | string[] | sim | |
active | boolean | sim | |
created_at | integer | sim |
LoginInput
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
email | string | sim | |
password | string | sim |
Me
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | integer | sim | |
name | string | sim | |
email | string | sim | |
role | string | sim | owner ou member. |
tenant_id | integer | sim | |
tenant_name | string | sim | |
scopes | string[] | sim |
NewApiKey
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | sim | |
scopes | string[] | sim |
NewBoard
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
space_id | integer | sim | |
name | string | sim | 1 a 80 caracteres. |
NewCard
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
board_id | integer | sim | |
column_id | integer (opcional) | não | Coluna inicial; sem ela, a primeira coluna do quadro. |
title | string | sim | 1 a 200 caracteres. |
description | string (opcional) | não | Até 10000 caracteres. |
priority | string (opcional) | não | low, medium, high ou urgent. |
due_on | string (opcional) | não | Prazo AAAA-MM-DD. |
assignee_id | integer (opcional) | não | Pessoa responsável (id de GET /api/v1/users). |
labels | string[] | não | Até 10 etiquetas de 1 a 30 caracteres (repetidas contam uma vez). |
NewComment
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
body | string | sim | 1 a 5000 caracteres (texto simples, quebras de linha permitidas). |
NewEndpoint
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
url | string | sim | URL https:// pública que receberá os eventos. |
events | string[] | sim | Eventos assinados; ["*"] para todos. |
NewSpace
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
key | string | sim | 2 a 10 caracteres: letras maiúsculas sem acento e números, começando por letra. Não muda depois. |
name | string | sim | 1 a 80 caracteres. |
description | string (opcional) | não | Até 2000 caracteres. |
Person
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | integer | sim | |
name | string | sim |
PersonPage
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
data | Person[] | sim | |
next_cursor | string (opcional) | não | Passe em cursor para buscar a próxima página; null quando acabou. |
Space
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | integer | sim | |
key | string | sim | Prefixo dos cartões (ex.: DEV → DEV-142). |
name | string | sim | |
description | string | sim | |
created_at | integer | sim | Milissegundos desde 1970 (UTC). |
updated_at | integer | sim |
SpacePage
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
data | Space[] | sim | |
next_cursor | string (opcional) | não | Passe em cursor para buscar a próxima página; null quando acabou. |
SpacePatch
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string (opcional) | não | |
description | string (opcional) | não |
UiBatch
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
events | UiEvent[] | sim |
UiEvent
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
kind | string | sim | view (tela aberta, com ms) ou action (com name). |
screen | string | sim | Padrão da rota, ex.: /itens/:id. |
ms | integer (opcional) | não | |
name | string (opcional) | não |