Skip to content

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/login

Corpo: LoginInput

Respostas: 200 Me — Define o cookie de sessão · 401 · 429

Sair ​

http
POST /api/v1/auth/logout

Respostas: 204

Usuário logado ​

http
GET /api/v1/auth/me

Autenticação: session

Respostas: 200 Me · 401

Uso das telas (painel) ​

http
POST /api/v1/telemetry

Lote 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/spaces

Autenticação: api_key (boards:read) ou session

ParâmetroOndeTipoDescrição
limitqueryinteger1 a 100 (padrão 50).
cursorquerystring

Respostas: 200 SpacePage · 400 — Parâmetros inválidos · 401

Criar espaço ​

http
POST /api/v1/spaces

Aceita 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âmetroOndeTipoDescrição
Idempotency-Keyheaderstring (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âmetroOndeTipoDescrição
idpathinteger

Respostas: 200 Space · 404

Apagar espaço ​

http
DELETE /api/v1/spaces/{id}

Autenticação: api_key (boards:write) ou session

ParâmetroOndeTipoDescrição
idpathinteger

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âmetroOndeTipoDescrição
idpathinteger

Corpo: SpacePatch

Respostas: 200 Space · 400 · 404

Quadros e suas colunas ​

Listar quadros ​

http
GET /api/v1/boards

Autenticação: api_key (boards:read) ou session

ParâmetroOndeTipoDescrição
space_idqueryintegerSó os quadros deste espaço.
limitqueryinteger1 a 100 (padrão 50).
cursorquerystring

Respostas: 200 BoardPage · 400 — Parâmetros inválidos · 401

Criar quadro ​

http
POST /api/v1/boards

Cria o quadro com as colunas A fazer, Fazendo e Feito. Aceita o header Idempotency-Key.

Autenticação: api_key (boards:write) ou session

ParâmetroOndeTipoDescrição
Idempotency-Keyheaderstring (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âmetroOndeTipoDescrição
idpathinteger

Respostas: 200 Board · 404

Apagar quadro ​

http
DELETE /api/v1/boards/{id}

Autenticação: api_key (boards:write) ou session

ParâmetroOndeTipoDescrição
idpathinteger

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âmetroOndeTipoDescrição
idpathinteger

Corpo: BoardPatch

Respostas: 200 Board · 400 · 404

Cartões: aceitam id ou chave (DEV-12) ​

Listar cartões ​

http
GET /api/v1/cards

Autenticação: api_key (cards:read) ou session

ParâmetroOndeTipoDescrição
board_idqueryintegerSó os cartões deste quadro.
column_idqueryintegerSó os cartões desta coluna.
assignee_idqueryintegerSó os cartões desta pessoa.
labelquerystringSó os cartões com esta etiqueta (sem diferença de maiúsculas).
limitqueryinteger1 a 100 (padrão 50).
cursorquerystring

Respostas: 200 CardPage · 400 — Parâmetros inválidos · 401

Criar cartão ​

http
POST /api/v1/cards

Cria 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âmetroOndeTipoDescrição
Idempotency-Keyheaderstring (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âmetroOndeTipoDescrição
cardpathstringId 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âmetroOndeTipoDescrição
cardpathstringId 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âmetroOndeTipoDescrição
cardpathstringId ou chave (ex.: DEV-12)

Corpo: CardPatch

Respostas: 200 Card · 400 · 404

Trocar etiquetas do cartão ​

http
PUT /api/v1/cards/{card}/labels

Substitui 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âmetroOndeTipoDescrição
cardpathstringId ou chave (ex.: DEV-12)

Corpo: CardLabels

Respostas: 200 Card · 400 · 404

Mover cartão ​

http
POST /api/v1/cards/{card}/move

Move 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âmetroOndeTipoDescrição
cardpathstringId 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}/comments

Autenticação: api_key (cards:read) ou session

ParâmetroOndeTipoDescrição
cardpathstringId ou chave (ex.: DEV-12)
limitqueryinteger1 a 100 (padrão 50).
cursorquerystring

Respostas: 200 CommentPage · 400 — Parâmetros inválidos · 404

Comentar no cartão ​

http
POST /api/v1/cards/{card}/comments

Aceita o header Idempotency-Key.

Autenticação: api_key (comments:write) ou session

ParâmetroOndeTipoDescrição
cardpathstringId ou chave (ex.: DEV-12)
Idempotency-Keyheaderstring (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âmetroOndeTipoDescrição
idpathinteger

Respostas: 204 · 403 · 404

Pessoas da empresa (responsáveis pelos cartões) ​

Listar pessoas ​

http
GET /api/v1/users

Pessoas da empresa que podem ser responsáveis por cartões (só id e nome).

Autenticação: api_key (cards:read) ou session

ParâmetroOndeTipoDescrição
limitqueryinteger1 a 100 (padrão 50).
cursorquerystring

Respostas: 200 PersonPage · 400 — Parâmetros inválidos · 401

Chaves para integrações ​

Listar API keys ativas ​

http
GET /api/v1/api-keys

Autenticação: session

Respostas: 200 ApiKey[]

Criar API key ​

http
POST /api/v1/api-keys

Autenticação: session

Corpo: NewApiKey

Respostas: 201 CreatedApiKey · 400

Revogar API key ​

http
DELETE /api/v1/api-keys/{id}

Autenticação: session

ParâmetroOndeTipoDescrição
idpathinteger

Respostas: 204 · 404

Notificações de eventos para sistemas externos ​

Reenviar uma entrega ​

http
POST /api/v1/webhook-deliveries/{id}/retry

Autenticação: api_key (webhooks:manage) ou session

ParâmetroOndeTipoDescrição
idpathinteger

Respostas: 202 · 404

Listar endpoints de webhook ​

http
GET /api/v1/webhooks

Autenticação: api_key (webhooks:manage) ou session

Respostas: 200 Endpoint[]

Cadastrar endpoint de webhook ​

http
POST /api/v1/webhooks

Autenticaçã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âmetroOndeTipoDescrição
idpathinteger

Respostas: 204 · 404

Últimas 100 entregas de um endpoint ​

http
GET /api/v1/webhooks/{id}/deliveries

Autenticação: api_key (webhooks:manage) ou session

ParâmetroOndeTipoDescrição
idpathinteger

Respostas: 200 Delivery[] · 404

Modelos ​

ApiKey ​

CampoTipoObrigatórioDescrição
idintegersim
namestringsim
prefixstringsimInício da chave, para identificá-la (ex.: pk_live_a1b2).
scopesstring[]sim
created_atintegersim
last_used_atinteger (opcional)não

Board ​

CampoTipoObrigatórioDescrição
idintegersim
space_idintegersim
namestringsim
columnsColumn[]sim
created_atintegersimMilissegundos desde 1970 (UTC).
updated_atintegersim

BoardPage ​

CampoTipoObrigatórioDescrição
dataBoard[]sim
next_cursorstring (opcional)nãoPasse em cursor para buscar a próxima página; null quando acabou.

BoardPatch ​

CampoTipoObrigatórioDescrição
namestring (opcional)não

Card ​

CampoTipoObrigatórioDescrição
idintegersim
keystringsimChave legível (ex.: DEV-12): aceita no lugar do id nas rotas e no MCP.
space_idintegersim
board_idintegersim
column_idintegersim
titlestringsim
descriptionstringsim
positionintegersimOrdem dentro da coluna (menor = mais acima).
created_atintegersimMilissegundos desde 1970 (UTC).
updated_atintegersim
completed_atinteger (opcional)nãoQuando entrou numa coluna done; null se não está concluído.
prioritystring (opcional)nãolow, medium, high ou urgent; null = sem prioridade.
due_onstring (opcional)nãoPrazo AAAA-MM-DD; null = sem prazo.
assignee_idinteger (opcional)nãoPessoa responsável (veja GET /api/v1/users); null = ninguém.
labelsstring[]simEtiquetas em ordem alfabética (ex.: cliente-acme, urgente).

CardLabels ​

CampoTipoObrigatórioDescrição
labelsstring[]simLista completa de etiquetas do cartão (substitui a atual; [] tira todas). Até 10, de 1 a 30 caracteres.

CardMove ​

CampoTipoObrigatórioDescrição
column_idintegersimColuna de destino (do mesmo quadro). O cartão vai para o fim dela.

CardPage ​

CampoTipoObrigatórioDescrição
dataCard[]sim
next_cursorstring (opcional)nãoPasse em cursor para buscar a próxima página; null quando acabou.

CardPatch ​

CampoTipoObrigatórioDescrição
titlestring (opcional)não
descriptionstring (opcional)não
prioritystring (opcional)nãolow, medium, high ou urgent; null tira a prioridade.
due_onstring (opcional)nãoPrazo AAAA-MM-DD; null tira o prazo.
assignee_idinteger (opcional)nãoPessoa responsável; null tira o responsável.

Column ​

CampoTipoObrigatórioDescrição
idintegersim
namestringsim
kindstringsimbacklog, todo, in_progress, review ou done (base das métricas de fluxo).
positionintegersimOrdem da esquerda para a direita (1, 2, 3…).
wip_limitinteger (opcional)nãoLimite de cartões em andamento; null = sem limite.

Comment ​

CampoTipoObrigatórioDescrição
idintegersim
card_idintegersim
authorstringsimNome de quem escreveu (pessoa ou "Integração pk_live_…").
author_user_idinteger (opcional)nãoId da pessoa que escreveu; null quando veio de uma integração.
bodystringsim
created_atintegersimMilissegundos desde 1970 (UTC).

CommentPage ​

CampoTipoObrigatórioDescrição
dataComment[]sim
next_cursorstring (opcional)nãoPasse em cursor para buscar a próxima página; null quando acabou.

CreatedApiKey ​

CreatedEndpoint ​

Delivery ​

CampoTipoObrigatórioDescrição
idintegersim
event_idstringsim
event_typestringsim
statusstringsimpending, delivered ou failed.
attemptsintegersim
last_statusinteger (opcional)não
last_errorstring (opcional)não
created_atintegersim
delivered_atinteger (opcional)não

Endpoint ​

CampoTipoObrigatórioDescrição
idintegersim
urlstringsim
eventsstring[]sim
activebooleansim
created_atintegersim

LoginInput ​

CampoTipoObrigatórioDescrição
emailstringsim
passwordstringsim

Me ​

CampoTipoObrigatórioDescrição
idintegersim
namestringsim
emailstringsim
rolestringsimowner ou member.
tenant_idintegersim
tenant_namestringsim
scopesstring[]sim

NewApiKey ​

CampoTipoObrigatórioDescrição
namestringsim
scopesstring[]sim

NewBoard ​

CampoTipoObrigatórioDescrição
space_idintegersim
namestringsim1 a 80 caracteres.

NewCard ​

CampoTipoObrigatórioDescrição
board_idintegersim
column_idinteger (opcional)nãoColuna inicial; sem ela, a primeira coluna do quadro.
titlestringsim1 a 200 caracteres.
descriptionstring (opcional)nãoAté 10000 caracteres.
prioritystring (opcional)nãolow, medium, high ou urgent.
due_onstring (opcional)nãoPrazo AAAA-MM-DD.
assignee_idinteger (opcional)nãoPessoa responsável (id de GET /api/v1/users).
labelsstring[]nãoAté 10 etiquetas de 1 a 30 caracteres (repetidas contam uma vez).

NewComment ​

CampoTipoObrigatórioDescrição
bodystringsim1 a 5000 caracteres (texto simples, quebras de linha permitidas).

NewEndpoint ​

CampoTipoObrigatórioDescrição
urlstringsimURL https:// pública que receberá os eventos.
eventsstring[]simEventos assinados; ["*"] para todos.

NewSpace ​

CampoTipoObrigatórioDescrição
keystringsim2 a 10 caracteres: letras maiúsculas sem acento e números, começando por letra. Não muda depois.
namestringsim1 a 80 caracteres.
descriptionstring (opcional)nãoAté 2000 caracteres.

Person ​

CampoTipoObrigatórioDescrição
idintegersim
namestringsim

PersonPage ​

CampoTipoObrigatórioDescrição
dataPerson[]sim
next_cursorstring (opcional)nãoPasse em cursor para buscar a próxima página; null quando acabou.

Space ​

CampoTipoObrigatórioDescrição
idintegersim
keystringsimPrefixo dos cartões (ex.: DEV → DEV-142).
namestringsim
descriptionstringsim
created_atintegersimMilissegundos desde 1970 (UTC).
updated_atintegersim

SpacePage ​

CampoTipoObrigatórioDescrição
dataSpace[]sim
next_cursorstring (opcional)nãoPasse em cursor para buscar a próxima página; null quando acabou.

SpacePatch ​

CampoTipoObrigatórioDescrição
namestring (opcional)não
descriptionstring (opcional)não

UiBatch ​

CampoTipoObrigatórioDescrição
eventsUiEvent[]sim

UiEvent ​

CampoTipoObrigatórioDescrição
kindstringsimview (tela aberta, com ms) ou action (com name).
screenstringsimPadrão da rota, ex.: /itens/:id.
msinteger (opcional)não
namestring (opcional)não