Documentação da API

Guia didático para sair do zero até sua primeira automação em produção.

1) Começo rápido

Gere sua API key no perfil, valide com GET /api/v1/me e use sempre a mesma chave durante a integração.

Use sempre o header Authorization: Bearer <sua_api_key>.

curl -X GET "https://kanbe.tech/api/v1/me" \
  -H "Authorization: Bearer knb_sua_api_key"

2) Como obter sua API key

Acesse o seu perfil em /profile.
Na seção Acesso por API, clique em Gerar API key.
Copie e guarde a chave: ela aparece apenas uma vez.

3) Fluxo completo de uso

Siga as etapas em sequência. Cada bloco mostra o objetivo, o endpoint e exemplos equivalentes em Python e cURL.

Etapa 1) Validar autenticação com /me

Confirma que a API key está ativa e vinculada ao usuário correto antes de qualquer ação de leitura/escrita.

Endpoint: GET /api/v1/me
Saída esperada: Objeto data com id e email do usuário autenticado.
Guarde para próxima etapa: A mesma API key será usada em todas as etapas seguintes.

Python

import requests

BASE_URL = "https://kanbe.tech"
api_key = "knb_sua_api_key"

resp = requests.get(
    f"{BASE_URL}/api/v1/me",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=20,
)
resp.raise_for_status()
me = resp.json()["data"]
print(me["id"], me["email"])

cURL

curl -X GET "https://kanbe.tech/api/v1/me" \
  -H "Authorization: Bearer knb_sua_api_key"

Etapa 2) Listar boards e capturar board_id

Recupera os boards onde essa API key tem acesso. Escolha um board para usar no restante do fluxo.

Endpoint: GET /api/v1/boards
Saída esperada: Lista de boards com id e título.
Guarde para próxima etapa: Salvar board_id do board que será automatizado.

Python

import requests

BASE_URL = "https://kanbe.tech"
api_key = "knb_sua_api_key"

resp = requests.get(
    f"{BASE_URL}/api/v1/boards",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=20,
)
resp.raise_for_status()
boards = resp.json()["data"]["items"]
board_id = boards[0]["id"]
print("board_id:", board_id)

cURL

curl -X GET "https://kanbe.tech/api/v1/boards" \
  -H "Authorization: Bearer knb_sua_api_key"

Etapa 3) Listar nomes de todas as colunas do board

Usa o retorno do board para extrair apenas os títulos das colunas e validar a estrutura antes de criar ou mover tasks.

Endpoint: GET /api/v1/boards/{board_id}/tasks
Entrada: board_id obtido na etapa 2.
Saída esperada: Lista de nomes das colunas do board.
Guarde para próxima etapa: Com as colunas validadas, siga para a etapa 4 para listar tasks.

Python

import requests

BASE_URL = "https://kanbe.tech"
api_key = "knb_sua_api_key"
board_id = 10  # use o ID retornado na etapa 2

resp = requests.get(
    f"{BASE_URL}/api/v1/boards/{board_id}/tasks",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=20,
)
resp.raise_for_status()
data = resp.json()["data"]
column_names = [column["title"] for column in data.get("columns", [])]
print("colunas no board:", ", ".join(column_names))

cURL

curl -X GET "https://kanbe.tech/api/v1/boards/10/tasks" \
  -H "Authorization: Bearer knb_sua_api_key"

Etapa 4) Listar tasks do board

Mostra o estado atual do board para evitar duplicações e entender tasks já existentes.

Endpoint: GET /api/v1/boards/{board_id}/tasks
Entrada: board_id obtido na etapa 2.
Guarde para próxima etapa: Se necessário, criar coluna na etapa 5 para receber novas tasks.

Python

import requests

BASE_URL = "https://kanbe.tech"
api_key = "knb_sua_api_key"
board_id = 10  # use o ID retornado na etapa 2

resp = requests.get(
    f"{BASE_URL}/api/v1/boards/{board_id}/tasks",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=20,
)
resp.raise_for_status()
tasks = resp.json()["data"]["tasks"]
print("tasks no board:", len(tasks))

cURL

curl -X GET "https://kanbe.tech/api/v1/boards/10/tasks" \
  -H "Authorization: Bearer knb_sua_api_key"

Etapa 5) Criar coluna (opcional)

Use quando precisar separar o fluxo de entrada via API em uma coluna dedicada.

Endpoint: POST /api/v1/boards/{board_id}/columns
Entrada: board_id e título da coluna.
Guarde para próxima etapa: Salvar column_id retornado para usar no create de task da etapa 6.

Python

import requests

BASE_URL = "https://kanbe.tech"
api_key = "knb_sua_api_key"
board_id = 10

payload = {"title": "API - Backlog"}

resp = requests.post(
    f"{BASE_URL}/api/v1/boards/{board_id}/columns",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=20,
)
resp.raise_for_status()
column_id = resp.json()["data"]["id"]
print("column_id:", column_id)

cURL

curl -X POST "https://kanbe.tech/api/v1/boards/10/columns" \
  -H "Authorization: Bearer knb_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{"title":"API - Backlog"}'

Etapa 6) Criar task com payload completo

Cria a task com metadados de prioridade, cliente, produto, tamanho e datas no formato aceito pela API.

Endpoint: POST /api/v1/boards/{board_id}/tasks
Entrada: board_id, column_id (opcional) e campos da task.
Guarde para próxima etapa: Salvar task_id para atualização posterior via PATCH na etapa 7.

Python

import requests

BASE_URL = "https://kanbe.tech"
api_key = "knb_sua_api_key"
board_id = 10
column_id = 123

payload = {
    "title": "Task via API",
    "description": "Criacao automatizada",
    "assignee_name": "Equipe Operacoes",
    "priority": "Alta",
    "priority_color": "#f97316",
    "client_label": "ChemIA",
    "client_color": "#2563eb",
    "product_label": "Kanbe",
    "product_color": "#7c3aed",
    "task_size": "M",
    "start_date": "2026-04-21",
    "due_date": "2026-04-30",
    "column_id": column_id,
}

resp = requests.post(
    f"{BASE_URL}/api/v1/boards/{board_id}/tasks",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=20,
)
resp.raise_for_status()
task_id = resp.json()["data"]["id"]
print("task_id:", task_id)

cURL

curl -X POST "https://kanbe.tech/api/v1/boards/10/tasks" \
  -H "Authorization: Bearer knb_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Task via API",
    "description": "Criacao automatizada",
    "assignee_name": "Equipe Operacoes",
    "priority": "Alta",
    "priority_color": "#f97316",
    "client_label": "ChemIA",
    "client_color": "#2563eb",
    "product_label": "Kanbe",
    "product_color": "#7c3aed",
    "task_size": "M",
    "start_date": "2026-04-21",
    "due_date": "2026-04-30",
    "column_id": 123
  }'

Etapa 7) Atualizar task via PATCH

Atualiza apenas os campos necessários, sem reenviar o payload completo. Este é o caminho recomendado para concluir/reabrir e mover task.

Endpoint: PATCH /api/v1/tasks/{task_id}
Entrada: task_id e campos a serem alterados (parcial).
Saída esperada: Task atualizada com os novos valores persistidos.

Python

import requests

BASE_URL = "https://kanbe.tech"
api_key = "knb_sua_api_key"
task_id = 999

payload = {
    "title": "Task via API (atualizada)",
    "completed": True,
    "is_blocked": False,
}

resp = requests.patch(
    f"{BASE_URL}/api/v1/tasks/{task_id}",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=20,
)
resp.raise_for_status()
print(resp.json()["data"]["title"])

cURL

curl -X PATCH "https://kanbe.tech/api/v1/tasks/999" \
  -H "Authorization: Bearer knb_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Task via API (atualizada)",
    "completed": true,
    "is_blocked": false
  }'

Etapa 8) Confirmar persistência

Faça uma leitura final para confirmar que os campos enviados nas etapas 6 e 7 foram gravados corretamente.

Endpoint: GET /api/v1/boards/{board_id}/tasks
Entrada: board_id e task_id usados nas etapas anteriores.
Saída esperada: Task encontrada no GET final com os campos atualizados.

Python

import requests

BASE_URL = "https://kanbe.tech"
api_key = "knb_sua_api_key"
board_id = 10
task_id = 999

resp = requests.get(
    f"{BASE_URL}/api/v1/boards/{board_id}/tasks",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=20,
)
resp.raise_for_status()
tasks = resp.json()["data"]["tasks"]
task = next((item for item in tasks if item["id"] == task_id), None)
print(task)

cURL

curl -X GET "https://kanbe.tech/api/v1/boards/10/tasks" \
  -H "Authorization: Bearer knb_sua_api_key"

4) Subtasks e exclusão de task

Use estes endpoints para criar/listar/atualizar/remover subtasks e também excluir task com cascata.

Etapa 1) Listar subtasks da task

Recupera as subtasks vinculadas à task e permite filtrar por status quando necessário.

Endpoint: GET /api/v1/tasks/{task_id}/subtasks

Python

import requests

BASE_URL = "https://kanbe.tech"
api_key = "knb_sua_api_key"
task_id = 999

resp = requests.get(
    f"{BASE_URL}/api/v1/tasks/{task_id}/subtasks",
    headers={"Authorization": f"Bearer {api_key}"},
    params={"page": 1, "per_page": 20, "sort": "position", "direction": "asc"},
    timeout=20,
)
resp.raise_for_status()
subtasks = resp.json()["data"]["items"]
print("subtasks:", len(subtasks))

cURL

curl -X GET "https://kanbe.tech/api/v1/tasks/999/subtasks?page=1&per_page=20&sort=position&direction=asc" \
  -H "Authorization: Bearer knb_sua_api_key"

Etapa 2) Criar subtask com tipo, esforço e data

Cria uma subtask com campos de negócio para operação diária e rastreabilidade.

Endpoint: POST /api/v1/tasks/{task_id}/subtasks

Python

import requests

BASE_URL = "https://kanbe.tech"
api_key = "knb_sua_api_key"
task_id = 999

payload = {
    "title": "Subtask API - revisão",
    "description": "Revisar payload e contrato",
    "size": "M",
    "due_date": "2026-05-15",
    "kind": "doc",
}

resp = requests.post(
    f"{BASE_URL}/api/v1/tasks/{task_id}/subtasks",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=20,
)
resp.raise_for_status()
subtask_id = resp.json()["data"]["id"]
print("subtask_id:", subtask_id)

cURL

curl -X POST "https://kanbe.tech/api/v1/tasks/999/subtasks" \
  -H "Authorization: Bearer knb_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Subtask API - revisao",
    "description": "Revisar payload e contrato",
    "size": "M",
    "due_date": "2026-05-15",
    "kind": "doc"
  }'

Etapa 3) Atualizar subtask (finalizada/bloqueada)

Atualiza parcialmente a subtask via PATCH, incluindo estado de conclusão e bloqueio.

Endpoint: PATCH /api/v1/subtasks/{subtask_id}

Python

import requests

BASE_URL = "https://kanbe.tech"
api_key = "knb_sua_api_key"
subtask_id = 321

payload = {
    "title": "Subtask API - revisão final",
    "is_completed": True,
    "is_blocked": False,
    "kind": "bug",
}

resp = requests.patch(
    f"{BASE_URL}/api/v1/subtasks/{subtask_id}",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=20,
)
resp.raise_for_status()
print(resp.json()["data"]["is_completed"])

cURL

curl -X PATCH "https://kanbe.tech/api/v1/subtasks/321" \
  -H "Authorization: Bearer knb_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Subtask API - revisao final",
    "is_completed": true,
    "is_blocked": false,
    "kind": "bug"
  }'

Etapa 4) Excluir subtask

Remove uma subtask específica da task sem afetar as demais.

Endpoint: DELETE /api/v1/subtasks/{subtask_id}

Python

import requests

BASE_URL = "https://kanbe.tech"
api_key = "knb_sua_api_key"
subtask_id = 321

resp = requests.delete(
    f"{BASE_URL}/api/v1/subtasks/{subtask_id}",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=20,
)
resp.raise_for_status()
print(resp.json()["ok"])

cURL

curl -X DELETE "https://kanbe.tech/api/v1/subtasks/321" \
  -H "Authorization: Bearer knb_sua_api_key"

Etapa 5) Excluir task (hard delete + cascata)

Remove a task e todas as subtasks vinculadas. Use com cautela em produção.

Endpoint: DELETE /api/v1/tasks/{task_id}

Python

import requests

BASE_URL = "https://kanbe.tech"
api_key = "knb_sua_api_key"
task_id = 999

resp = requests.delete(
    f"{BASE_URL}/api/v1/tasks/{task_id}",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=20,
)
resp.raise_for_status()
print(resp.json()["data"]["deleted_subtasks_count"])

cURL

curl -X DELETE "https://kanbe.tech/api/v1/tasks/999" \
  -H "Authorization: Bearer knb_sua_api_key"

5) Campos principais para criação/edição de task

Use estes campos no POST /boards/{board_id}/tasks e no PATCH /tasks/{task_id}.

Campo	Tipo	Exemplo	Regra
title	string	"Task API"	Obrigatorio no create
description	string	"Detalhes"	Opcional
assignee_name	string	"Jeff"	Opcional
priority	string	"Alta"	Matching case-insensitive
priority_color	string	"#f97316"	Hex ou nome de cor do sistema
client_label	string	"ChemIA"	Matching case-insensitive
client_color	string	"azul"	Hex ou nome de cor do sistema
product_label	string	"Kanbe"	Aceita alias system_label
product_color	string	"#7c3aed"	Aceita alias system_color
task_size	string	"M"	PP, P, M, G, GG, XG
start_date	date	"2026-04-21"	Formato YYYY-MM-DD
due_date	date	"2026-04-30"	start_date <= due_date
column_id	int	123	Mesma board da task
completed	bool	true	PATCH canônico para concluir/reabrir
is_blocked	bool	false	Se true, task nao pode ficar completed

6) Erros comuns e como resolver

401 API key ausente/inválida: revise header Authorization.
403 acesso negado: confira compartilhamento e permissões do board.
400 payload inválido: valide datas (YYYY-MM-DD), task_size e column_id.

7) Checklist de validação

Consegui autenticar com /me.
Consegui listar boards e tasks com a mesma API key.
Consegui criar coluna e task com sucesso.
Consegui atualizar task via PATCH com completed e column_id.
Confirmei no GET final que os campos foram persistidos.

Integracao com Agentes

Guia de uso da pasta .kanbe para integracao entre projetos e agentes de IA na automacao de tarefas do Kanbe.

Com essa integracao configurada, basta informar ao agente o que precisa ser feito.

Download da pasta .kanbe

Baixe os arquivos no repositorio oficial:

https://github.com/jeffrichardchemistry/kanbeapi

Finalidade desta documentacao

Este fluxo descreve como:

configurar a integracao com a API do Kanbe;
orientar geracao de tarefas por agentes;
publicar tarefas de forma segura e repetivel.

Estrutura esperada

meu_projeto/
  .kanbe/
    kanbe_api_config.yml
    kanbe_api_probe.py
    kanbe_api_upsert_tasks.py
    tasks_to_push_example.json
  src/
  README.md

Fluxo minimo recomendado

1) Copiar a pasta .kanbe para o projeto

A pasta .kanbe deve ficar na raiz do projeto.

2) Ignorar .kanbe no versionamento (quando aplicavel)

.kanbe/

3) Configurar kanbe_api_config.yml

Campos minimos:

kanbe.base_url
kanbe.api_base_path
kanbe.api_key
kanbe.default_board_id
kanbe.default_column_id (opcional)
task_defaults

Boas praticas de seguranca:

rotacionar API keys com frequencia;
revogar chaves antigas periodicamente;
nao versionar chaves reais no repositorio.

4) Pedir ao agente para preparar tarefas

Exemplo:

Gerar resumo das entregas e criar tarefas de backlog com subtarefas tecnicas.

5) Validar conectividade com o Kanbe

python .kanbe/kanbe_api_probe.py

6) Publicar tarefas

python .kanbe/kanbe_api_upsert_tasks.py --tasks-file .kanbe/tasks_to_push_projeto.json

Dry-run:

python .kanbe/kanbe_api_upsert_tasks.py --tasks-file .kanbe/tasks_to_push_projeto.json --dry-run

Troubleshooting rapido

Erro de coluna invalida: column_id nao pertence ao board.
Erro 401/403: verificar API key, permissoes e board.
Divergencia de ambiente: validar base_url e api_base_path.