API Kanera

A API pública do Kanera permite que você crie integrações em torno do mesmo trabalho que sua equipe gerencia no aplicativo: espaços de trabalho, quadros, cartões, listas, separadores de quadros, comentários, listas de verificação, notas, anexos, rótulos, campos personalizados, tarefas, próximas filas classificadas, atividades e links externos.

Use a API quando o Kanera precisar se conectar a outro sistema, potencializar um fluxo de trabalho interno, migrar dados, criar relatórios ou permitir que outra ferramenta crie e atualize o trabalho do Kanera.

O que você pode construir

Os casos de uso comuns de API incluem:

• Sincronize os cartões Kanera com outro rastreador de trabalho.
• Crie cartões a partir de formulários, tickets de suporte, mensagens de chat ou registros de CRM.
• Crie painéis de relatórios personalizados a partir de quadros, atribuições, rótulos, campos personalizados e atividades.
• Importe o trabalho de outro sistema para o Kanera.
• Mantenha registros externos vinculados a cartões ou notas Kanera.
• Adicione comentários ou atualizações de status de outra ferramenta.
• Carregue e anexe arquivos a cartões ou notas.
• Leia o histórico de atividades para auditoria, relatórios ou automação.

As integrações do Kanera podem ter como alvo quadros ou espaços de trabalho independentes. Um quadro independente possui suas próprias listas, rótulos e campos personalizados. Um espaço de trabalho compartilha esses recursos entre seus quadros, o que torna mais fácil manter a consistência dos relatórios entre quadros e da sincronização de fluxos de trabalho.

Clientes oficiais

Você não precisa começar de curl. Dois clientes primários agrupam a mesma API:

Cliente	Instalar	Use-o para
Kanera CLI	npm install --global @kanera/cli	Uso de terminal, scripts de shell e agentes de IA que podem executar comandos.
SDK TypeScript	npm install @kanera/sdk	Integrações TypeScript e JavaScript. Sem dependências de tempo de execução; roda em Node, Bun, Deno, trabalhadores e navegadores.

O SDK é licenciado pelo MIT, portanto incorporá-lo em seu próprio aplicativo não levanta questões sobre política de licença. Use os endpoints REST diretamente para qualquer outro idioma.

Referência da API

A API REST Kanera está em:

https://api.kanera.app

Referência detalhada em nível de endpoint está disponível em:

https://api.kanera.app/docs

O serviço de API público inclui a referência em nível de endpoint:

Caminho	Usar
/docs	Referência de API escalar interativa.
/swagger	Referência da IU do Swagger.
/openapi.json	Documento OpenAPI para geração e ferramentas de SDK.

Para Kanera, abra:

https://api.kanera.app/docs
https://api.kanera.app/swagger
https://api.kanera.app/openapi.json

Use esta página como guia de primeiros passos e, em seguida, use a referência da API para caminhos exatos de endpoint, corpos de solicitação, esquemas de resposta e tipos de eventos de webhook disponíveis.

Use a referência de endpoint

Abrir Escalar para a referência do endpoint primário. Cada operação mostra seu método e caminho, escopo necessário, caminho e parâmetros de consulta, esquema de solicitação, esquema de resposta e respostas de erro. Usar Autorizar para fornecer um token ao portador quando você quiser tentar uma solicitação.

Usar IU arrogante quando suas ferramentas ou fluxo de trabalho são construídos em torno do Swagger. Baixar JSON OpenAPI para geração de SDK, validação de solicitação ou importação da API para outro cliente.

O documento OpenAPI é a fonte da verdade. Copie um exemplo da referência em vez de adivinhar o corpo da solicitação e teste as operações de gravação ou exclusão no espaço de trabalho pretendido antes de automatizá-las.

Grupos de endpoints

Grupo	Operações típicas
Espaços de trabalho e quadros	Descubra trabalhos acessíveis, abra o estado completo do quadro, gerencie membros e convidados e crie ou reordene quadros.
Listas, separadores e cartões	Crie, atualize, posicione, mova, conclua, arquive, duplique e edite trabalhos em massa.
Notas e anexos	Crie notas aninhadas, gerencie bloqueios e backlinks, carregue arquivos diretamente ou por meio de um link de upload único e leia os bytes de um anexo.
Bloco de rascunho	Leia as páginas privadas do Scratchpad do chamador e capture tarefas rápidas em uma página da Caixa de entrada. Apenas credenciais pessoais.
Campos e rótulos	Gerencie campos personalizados, opções e etiquetas de cartões reutilizáveis no nível do espaço de trabalho.
Comentários e atividades	Leia feeds de cartões, escreva comentários e reações e analise as atividades do quadro.
Próximas prioridades	Descubra filas legíveis, liste a ordem das equipes e adicione, mova ou remova cartas classificadas.
Seguindo	Assista ou pare de assistir cartões e quadros, defina, limpe ou liste seus lembretes de cartões privados e pesquise sua caixa de entrada de notificações. Apenas credenciais pessoais.
Execuções do agente	Anuncie que um agente está trabalhando em um cartão, pulsando enquanto ele é executado e registre como ele terminou.
Pesquisa e links externos	Pesquise conteúdo acessível e mantenha mapeamentos idempotentes para registros em outros sistemas.
Webhooks	Registre e gerencie endpoints, inspecione ou tente novamente entregas e receba eventos de alteração assinados sem pesquisa.

Escolha um tipo de chave de API

Kanera possui dois tipos de chave de API. Eles autenticam da mesma forma, mas seu modelo de acesso é diferente.

Tipo de chave	Crie-o a partir	Use-o quando	Modelo de acesso
Chave de API pessoal	Configurações de perfil -> Chaves de API	Você está conectando seu próprio script, CLI ou cliente MCP e deseja que ele funcione em todas as áreas que você pode acessar pessoalmente.	Age como você, em todos os espaços de trabalho e quadros que você pode acessar, respeitando sua função em cada quadro. É Leia ou Escreva o escopo limita o que ele pode fazer dentro desse acesso. Ele não pode executar ações de administrador do espaço de trabalho.
Chave de API do espaço de trabalho ou quadro	Configurações do espaço de trabalho -> API ou Configurações do quadro -> API	Você está configurando uma integração de equipe, uma conta de serviço, um produtor de webhook, um trabalho de sincronização ou uma automação para um espaço de trabalho ou quadro independente.	Com escopo para esse espaço de trabalho ou quadro autônoma. É Leia, Escreva, ou Administrador o escopo controla o que a integração pode fazer.

Use uma chave pessoal para fluxos de trabalho de propriedade do usuário. Use um espaço de trabalho com escopo ou chave de quadro para integrações compartilhadas ou de produção que devem ser de propriedade, rotacionadas e auditadas com o destino.

Requisitos do plano

Chaves de API pessoais e conexões interativas de agentes de IA funcionam cada plano, incluindo hospedado gratuitamente. Eles atuam como um usuário presente, portanto alcançam exatamente os fóruns que o usuário pode abrir, tanto nas organizações Gratuitas quanto nas Pro.

As chaves de API do espaço de trabalho e da quadro, os agentes de serviço OAuth autônomos, os webhooks e os destinos de bate-papo precisam Pro ou os 30 dias Avaliação profissional. Eles são executados em nome da organização sem ninguém conectado, portanto não estão disponíveis no Free hospedado, onde a página de configurações do espaço de trabalho explica isso em vez de mostrar o formulário de criação. Solicitações bloqueadas por retorno de limite de plano 403 com o código de erro PLAN_LIMIT, portanto, uma integração pode diferenciar um problema de plano de um problema de permissão.

Necessidades de criação de chaves de API de espaço de trabalho ou quadro, clientes OAuth e destinos de bate-papo administrador do espaço de trabalho permissão. Os administradores também gerenciam todos os endpoints de webhook em um espaço de trabalho; uma credencial de API com capacidade de gravação ou um agente OAuth interativo pode registrar endpoints com escopo para sua própria conexão quando seu usuário for um membro do espaço de trabalho. As chaves de API pessoais não precisam de nenhuma função de espaço de trabalho para serem criadas.

O portão não está apenas na criação. Quando uma organização hospedada muda para Gratuito, Kanera revoga seu espaço de trabalho ativo e chaves de API de quadro, o que também desativa os agentes de serviço OAuth criados neles, e /api/v1 as rejeita no momento da solicitação, portanto, uma chave que sobrevive em outro lugar ainda não pode ser usada. As chaves de API pessoais e as conexões de agentes interativos continuam funcionando. Os endpoints do webhook e os destinos de chat são pausados ​​pelo mesmo downgrade. A atualização de volta para o Pro restaura as chaves e os endpoints afetados pelo downgrade.

Limites de taxa

As solicitações de chaves de API e agentes de IA, tanto em REST quanto em MCP, são limitadas por usuário, nos limites do plano da organização proprietária do quadro que está sendo acessado:

Organização do quadro	Por segundo	Por minuto
Hospedado gratuitamente	5	60
Teste hospedado Pro ou Pro	20	400
Auto-hospedado	20	400 (configurável)

Um usuário que pertence a uma organização Gratuita e Pro obtém os limites de cada organização em seus próprios fóruns. Solicitações acima do limite não são recusadas de imediato: até 10 aguardam na fila, por no máximo 10 segundos, e são atendidas como liberação de capacidade. Somente solicitações além dessa fila recebem 429 com um Retry-After cabeçalho. O servidor CLI, SDK e MCP recua e tenta novamente automaticamente.

Operadoras auto-hospedadas podem alterar os limites com PUBLIC_API_KEY_RATE_LIMIT_PER_SECOND, PUBLIC_API_KEY_RATE_LIMIT_PER_MINUTE, PUBLIC_API_RATE_LIMIT_QUEUE_SIZEe PUBLIC_API_RATE_LIMIT_QUEUE_MAX_WAIT_MS. Veja Webhooks para o comportamento de downgrade completo.

Crie uma chave de API pessoal

1. Abrir Configurações de perfil.
2. Vá para Chaves de API guia.
3. Crie uma chave de API pessoal.
4. Escolha Somente leitura ou Ler e escrever.
5. Adicione uma etiqueta privada opcional para que você possa reconhecer onde a chave é usada.
6. Copie o segredo quando ele for mostrado.

As chaves pessoais estão sempre vinculadas ao usuário que as criou. Eles seguem o acesso e a função reais do proprietário no quadro, e a atividade aparece como o proprietário. Não há escopo administrativo: uma chave pessoal nunca pode realizar a administração do espaço de trabalho, qualquer que seja a função de seu proprietário.

Chaves pessoais somente leitura

Uma chave pessoal é ler e escrever a menos que você escolha o contrário, que é o que uma chave existente ou um fluxo de criação inalterado oferece.

Escolha Somente leitura quando a credencial estiver indo para algum lugar que você não estará observando: um agente de IA, um trabalho de relatório, uma verificação de CI, um painel. Uma chave somente leitura pode listar, ler, pesquisar e relatar, e Kanera recusa todas as mutações com 403 e o código de erro FORBIDDEN. Como a recusa ocorre na API e não no cliente, um agente mal comportado ou injetado imediatamente ainda não poderá alterar seu trabalho.

O escopo é corrigido quando a chave é criada. Para alterá-lo, crie uma nova chave e revogue a antiga.

O segredo é mostrado uma vez. Armazene-o em seu gerenciador de segredos local, na configuração do cliente MCP ou em variáveis ​​de ambiente.

Crie uma chave de API de espaço de trabalho ou quadro

1. Abra o espaço de trabalho ou quadro independente.
2. Vá para Configurações do espaço de trabalho -> API ou Configurações do quadro -> API.
3. Crie uma chave de API do espaço de trabalho.
4. Escolha o menor escopo adequado à integração.
5. Copie o segredo quando ele for mostrado.

As chaves de API do espaço de trabalho têm escopo no espaço de trabalho. Uma chave só pode acessar recursos no workspace onde foi criada e onde seu criador ainda tem acesso.

O segredo é mostrado uma vez. Armazene-o no gerenciador secreto ou nas variáveis ​​de ambiente da sua integração.

Escopos de chave da API do Workspace

Escopo	Use-o quando
Leia	A integração só precisa ler, pesquisar, relatar ou exportar dados do Kanera.
Escreva	A integração precisa criar ou atualizar trabalhos, como cartões, comentários, rótulos, responsáveis, valores de campos personalizados, notas ou anexos.
Administrador	A integração precisa de operações de API públicas em nível de administrador, quando houver suporte. Use isso com moderação.

Leia, Escrevae Administrador aplicam-se às teclas do espaço de trabalho e do quadro. Chaves pessoais escolhem entre Leia e Escreva apenas, e sempre herdar as permissões de nível de quadro do proprietário além disso.

Use chaves de API separadas para integrações separadas. Isso torna o acesso mais fácil de revogar, alternar e auditar. Para sistemas compartilhados, prefira chaves de espaço de trabalho para que o acesso não fique vinculado às ferramentas pessoais de uma pessoa.

Autenticação

Envie a chave API como um token ao portador:

curl "$KANERA_PUBLIC_API_URL/api/v1/workspaces" \
  -H "Authorization: Bearer kanera_live_..."

As chaves da API Kanera usam prefixos para o ambiente:

Prefixo	Meio Ambiente
kanera_live_...	Produção
kanera_stg_...	Encenação
kanera_dev_...	Desenvolvimento
kanera_test_...	Teste

As chaves pessoais carregam um u marcador após o prefixo do fornecedor, então kanera_u_live_... é uma chave pessoal e kanera_live_... é uma chave de espaço de trabalho ou quadro. Ambos autenticam da mesma maneira.

Retorno de chaves ausentes ou inválidas 401. Chaves válidas sem permissão para retorno de recurso ou operação 403 — incluindo uma tentativa de gravação com uma chave com escopo de leitura.

OAuth para agentes de IA

Kanera suporta OAuth 2.0 para que um agente de IA compatível possa se conectar ao Kanera MCP por meio do consentimento do navegador ou de uma conexão de serviço em vez de armazenar uma chave de API.

Uma conexão OAuth é para MCP; não é uma credencial de API pública geral. Use uma chave de API pessoal, de espaço de trabalho ou de quadro quando sua própria integração precisar ser chamada /api/v1 diretamente.

Existem três caminhos OAuth:

• Agentes interativos use o fluxo do código de autorização com PKCE. Uma pessoa aprova a conexão uma vez no navegador e o agente atua como esse usuário. É assim que clientes MCP compatíveis, como Claude, ChatGPT, Copilot e Codex, se conectam sem uma chave de API.
• Clientes de dispositivos use a concessão de autorização do dispositivo (urn:ietf:params:oauth:grant-type:device_code). O cliente mostra um código curto, uma pessoa o aprova em um navegador em qualquer dispositivo e o cliente pesquisa tokens. Use isto para uma CLI ou cliente headless que não pode receber um redirecionamento do navegador. Veja o referência de autorização do dispositivo.
• Agentes autônomos use o client_credentials concessão. Você cria um ID de cliente e um segredo em Configurações do espaço de trabalho -> API e troque-os por tokens de curta duração, sem nenhuma etapa do navegador. Use-os para CI, cron ou agentes do lado do servidor.

Veja Conecte um agente de IA para configuração, escopos e gerenciamento de conexão. Os autores do cliente OAuth personalizado podem encontrar os detalhes do protocolo no Referência técnica do MCP.

URL base e controle de versão

Os endpoints REST residem em /api/v1 no serviço API público.

Por exemplo:

https://api.kanera.app/api/v1/workspaces

Caminhos auxiliares operacionais, como /docs, /swagger, /openapi.json, URLs de mídia assinada e descoberta de eventos de webhook podem residir fora do /api/v1 prefixo. Trate os URLs de mídia assinados retornados pela API como URLs opacos e use-os conforme fornecidos.

Primeiros pedidos

Verifique quem é a credencial. GET /api/v1/session retorna o usuário, a organização, o tipo de credencial e scope (read significa que toda alteração é recusada), além do usuário timeZone e today, a data atual nessa zona, para que um cliente possa resolver "hoje" ou "amanhã" da maneira como Kanera carimba as datas de vencimento:

curl "$KANERA_PUBLIC_API_URL/api/v1/session" \
  -H "Authorization: Bearer $KANERA_API_KEY"

Liste os workspaces que a chave de API pode acessar:

curl "$KANERA_PUBLIC_API_URL/api/v1/workspaces" \
  -H "Authorization: Bearer $KANERA_API_KEY"

Em seguida, liste os quadros em um espaço de trabalho:

curl "$KANERA_PUBLIC_API_URL/api/v1/workspaces/$WORKSPACE_ID/boards" \
  -H "Authorization: Bearer $KANERA_API_KEY"

Abra um quadro para obter o quadro, listas de espaços de trabalho, separadores de quadro, cartões visíveis, membros, rótulos e campos personalizados necessários para renderizar ou sincronizar o trabalho:

curl "$KANERA_PUBLIC_API_URL/api/v1/boards/$BOARD_ID/open" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY"

Crie um cartão:

curl "$KANERA_PUBLIC_API_URL/api/v1/boards/$BOARD_ID/lists/$LIST_ID/cards" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Follow up with Acme"}'

Uma criação também pode definir labelIds, assigneeIds, dueDateLocalDate (YYYY-MM-DD) e dueDateSlot na mesma gravação, para que o cartão chegue totalmente descrito e suas automações de etiqueta sejam executadas uma vez.

Crie vários cartões de uma vez, até 50 por solicitação em um quadro. Cada cartão nomeia sua própria lista e chega ao final dela na ordem de solicitação:

curl "$KANERA_PUBLIC_API_URL/api/v1/boards/$BOARD_ID/cards/bulk/create" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{\"cards\":[{\"listId\":\"$LIST_ID\",\"title\":\"Draft the brief\",\"labelIds\":[\"$LABEL_ID\"]},{\"listId\":\"$LIST_ID\",\"title\":\"Review with legal\",\"assigneeIds\":[\"$USER_ID\"],\"dueDateLocalDate\":\"2026-11-02\"}]}"

Cada cartão é verificado antes de qualquer um ser criado, portanto, uma lista, rótulo ou destinatário desconhecido rejeita toda a solicitação com um 400 que nomeia a entrada, como cards[1]: one or more label ids are invalid. Cada cartão aciona as mesmas automações, notificações e webhooks de uma única criação.

As respostas das cartas incluem o imutável workspaceId, opaco organisationKey, positivo number, atual legível por humanos key como PROJ-123e limpe o navegador url. O prefixo do espaço de trabalho pode mudar, mas o número do cartão não.

Resolva uma chave de cartão atual ou histórica antes de chamar um endpoint de mutação baseado em ID:

curl "$KANERA_PUBLIC_API_URL/api/v1/organisations/$ORGANISATION_KEY/cards/by-key/$CARD_KEY" \
  -H "Authorization: Bearer $KANERA_API_KEY"

A resolução não diferencia maiúsculas de minúsculas e retorna o ID atual do cartão, espaço de trabalho, quadro, lista, número, chave e URL do navegador. A chave da organização é o valor opaco retornado pelo Kanera, não um nome de organização ou slug. Cartões ausentes e inacessíveis são retornados 404.

Atualizar um cartão:

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID" \
  -X PATCH \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Imported from CRM"}'

Adicione um comentário:

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID/comments" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"Customer confirmed the rollout window."}'

Substitua as etiquetas ou destinatários do cartão por um conjunto exato:

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID/labels" \
  -X PUT \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"labelIds\":[\"$LABEL_ID\"]}"

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID/assignees" \
  -X PUT \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"userIds\":[\"$USER_ID\"]}"

Esses dois PUT operações substituem todo o conjunto. Envie um array vazio para limpá-lo; use as operações documentadas de adição/remoção em massa quando precisar de semântica de patch em cartões selecionados.

Preencha um cartão:

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID/completion" \
  -X PATCH \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"completed":true}'

Gerenciar separadores de quadro

Um separador é um item de propriedade do quadro, intitulado e opcionalmente colorido, na linha de pedidos mista de cartão e separador de uma lista de fluxo de trabalho. Crie um em uma âncora digitada exatamente:

curl "$KANERA_PUBLIC_API_URL/api/v1/boards/$BOARD_ID/lists/$LIST_ID/separators" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"title\":\"This week\",\"color\":\"blue\",\"beforeItem\":{\"type\":\"card\",\"id\":\"$CARD_ID\"}}"

Atualize seu título ou cor com PATCH /api/v1/separators/{id}, mova-o com POST /api/v1/separators/{id}/movee exclua-o com DELETE /api/v1/separators/{id}. Mover corpos nomear o destino listId e forneça exatamente um beforeItem ou afterItem; o item pode ser um { "type": "card", "id": "..." } ou { "type": "separator", "id": "..." } referência. Um null afterItem significa o topo e um null beforeItem significa o fundo. A exclusão de um separador deixa os cartões inalterados.

Gerenciar o próximo pedido

A API expõe as mesmas filas classificadas usadas por Home, My Cards e Team Cards:

Ponto final	Usar
GET /api/v1/work/priority-targets	Liste os usuários cujas filas a credencial pode ler.
GET /api/v1/work/priorities	Leia todas as filas permitidas em uma resposta.
GET /api/v1/work/priorities/{userId}	Leia uma fila em ordem de classificação.
POST /api/v1/work/priorities/{userId}/cards	Adicione um cartão ativo atribuído em uma posição ancorada.
POST /api/v1/card-priorities/{id}/move	Mova uma entrada da fila antes ou depois de outra entrada visível.
DELETE /api/v1/card-priorities/{id}	Remova a entrada sem alterar o cartão.

As credenciais pessoais sempre podem ler sua própria fila. A leitura da fila de outra pessoa requer autoridade administrativa efetiva em um espaço de trabalho compartilhado, e as gravações também exigem uma credencial com capacidade de gravação, além de autoridade para o cartão de destino. Use os IDs de entrada retornados pela fila como âncoras de movimentação; as classificações são valores de apresentação, não IDs de mutação.

Anexe e leia arquivos

POST /api/v1/cards/{id}/attachments faz um upload multiparte. Quando o arquivo estiver em algum lugar de onde o chamador não possa transmitir diretamente, como a sandbox de um agente de IA, crie um link de upload único e PUT os bytes brutos para ele:

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/MKT-42/attachments/upload-links" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"test-run.log"}'

# The response includes uploadUrl; no Authorization header is needed for the upload itself.
curl -fsS -T ./test-run.log "$UPLOAD_URL"

• O link funciona uma vez, expira após 15 minutos e para de funcionar se a chave que o criou for revogada.
• Kanera armazena o arquivo com o nome e tipo registrado quando o link foi criado, inferindo o tipo da extensão quando você omite mimeType. Arquivos de registro (.log, .out, .jsonl, e similares) são armazenados como texto simples.
• A criação de um link requer uma credencial com capacidade de gravação e acesso de editor ao cartão. Os limites de armazenamento são verificados quando o link é criado e quando o arquivo chega.
• A resposta de upload é o novo anexo, e qualquer pessoa que observe o cartão o verá aparecer imediatamente.

Leia os bytes de um anexo com GET /api/v1/cards/{id}/attachments/{attachmentId}/content. Ele suporta Range solicitações, e ?variant=cover (até 1200px) ou ?variant=thumbnail (400px) retorna as cópias JPEG que Kanera faz de imagens PNG, JPEG, GIF e WebP.

Capturar para o Scratchpad

POST /api/v1/scratchpad/capture anexa uma tarefa aberta ao privado do chamador Bloco de rascunho, na primeira página intitulada pageTitle (padrão Inbox) e cria a página quando ela está faltando:

curl "$KANERA_PUBLIC_API_URL/api/v1/scratchpad/capture" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Renew the venue insurance"}'

GET /api/v1/scratchpad/notes lista cada página com seu conteúdo e PATCH /api/v1/scratchpad/notes/{id} substitui uma página. Passe o updatedAt você lê como baseUpdatedAt receber 409 SCRATCHPAD_STALE em vez de substituir as edições feitas desde então. O Scratchpad pertence a uma pessoa, portanto as chaves API do espaço de trabalho recebem 403; use uma chave pessoal ou uma conexão OAuth.

Veja cartões e defina lembretes

O Seguindo endpoints gerenciam as próprias assinaturas do chamador, para que as chaves de API do espaço de trabalho recebam 403; use uma chave pessoal ou uma conexão OAuth. Alterá-los requer uma credencial com capacidade de gravação, mas apenas acesso de leitura ao cartão.

Ponto final	Usar
GET /api/v1/cards/{id}/follow	Se você assiste o cartão e seu lembrete nele.
PUT / DELETE /api/v1/cards/{id}/watch	Assista ou pare de assistir a um card. Retorna o mesmo estado que follow.
PUT / DELETE /api/v1/boards/{id}/watch	Assista ou pare de assistir a um tabuleiro.
PUT /api/v1/cards/{id}/reminder	Defina seu lembrete: {"remindAt": "2026-10-16T15:00:00+01:00"}.
DELETE /api/v1/cards/{id}/reminder	Limpe seu lembrete.
GET /api/v1/reminders	Seus lembretes pendentes, o mais rápido primeiro. ?status=all inclui aqueles que já dispararam.
GET /api/v1/notifications	Pesquise sua caixa de entrada de notificação a partir de um cursor. Veja abaixo.

remindAt é um instante ISO com deslocamento, no futuro e no máximo 56 dias (oito semanas) à frente. Você mantém um lembrete por cartão, portanto, configurá-lo novamente o substitui e rearma. Suas outras sessões abertas são atualizadas imediatamente. Nem a observação nem os lembretes aparecem na atividade do cartão. Veja Lembretes.

GET /api/v1/notifications é para um script ou agente que não pode receber webhooks, como um executado em um laptop. Ele retorna as mesmas linhas da sua gaveta de notificações (respostas, menções, atribuições e alterações nos cartões que você assiste ou foi atribuído), os mais antigos primeiro. Ligue uma vez sem since para as últimas linhas e, em seguida, passe cada resposta cursor de volta como since, repetindo enquanto hasMore é true, para obter apenas o que há de novo. Cada linha carrega uma linha summary, o card chave e URL, o actor, e um commentExcerpt para comentários. As linhas aparecem alguns segundos após o evento. Uma conexão de agente de IA não vê notificações causadas por suas próprias gravações, a menos que você adicione includeSelf=true, e a votação nunca marca nada como lido.

Acompanhe o trabalho de um agente durante o voo

Quando o chamador é um agente de IA em vez de um trabalho de sincronização, ele pode anunciar o trabalho que está realizando em um cartão. Kanera então mostra um chip ao vivo no bloco do cartão, lista a execução nos detalhes do cartão e registra as linhas de atividade do cartão para o início e o fim – para que uma pessoa possa ver que algo está acontecendo e quem está fazendo isso, sem esperar pelo resultado.

Ponto final	Usar
POST /api/v1/cards/{cardId}/agent-runs	Comece uma corrida. Corpo leva title (obrigatório), summarye externalUrl.
GET /api/v1/cards/{cardId}/agent-runs	Liste as execuções de um cartão. Ao vivo apenas por padrão; passar includeEnded=true para a história, o mais novo primeiro.
GET /api/v1/agent-runs/{id}	Leia uma corrida.
PATCH /api/v1/agent-runs/{id}	Atualizar, pulsar ou terminar uma execução. Cada campo é opcional, então {} é um batimento cardíaco nu.

Comece a corrida e mantenha o id da resposta:

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID/agent-runs" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Implementing OAuth refresh","externalUrl":"https://github.com/acme/api/pull/482"}'

Em seguida, relate o progresso e feche-o:

curl "$KANERA_PUBLIC_API_URL/api/v1/agent-runs/$RUN_ID" \
  -X PATCH \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"succeeded","summary":"Merged in PR 482; realtime suite green."}'

Os status são running, blocked, succeeded, failed, cancellede stalled:

• running e blocked são os dois estados vivos. Usar blocked enquanto o agente está aguardando uma pessoa, como uma pergunta ou uma aprovação; o chip do cartão fica âmbar.
• succeeded, failede cancelled são terminais. Um status de terminal encerra a execução e a torna imutável, portanto, mais tarde PATCH retorna 409 com message: agent run has already ended.
• stalled é definido por Kanera, não por você, quando uma execução ao vivo para de pulsar por quinze minutos, então um agente travado não pode deixar um cartão mostrando "funcionando" indefinidamente. Uma execução paralisada não é finalizada: o agente ainda pode fechá-la com um status de terminal ou definir running para retomar.

Cada PATCH atualiza os batimentos cardíacos, incluindo um que não altera nada; portanto, envie um sinal de alerta bem dentro da janela de quinze minutos em um trabalho longo. Iniciar ou atualizar um quadro de necessidades de corrida Editor acesso e uma credencial com capacidade de gravação, exatamente como qualquer outra gravação de cartão. As corridas também emitem o agentRun:started e agentRun:updated eventos de webhook.

Um agente conectado através OAuth é registrado como o agente agindo em nome de seu usuário: suas linhas de execuções, comentários e atividades levam o nome do agente, e a pessoa para quem ele atua é notificada sobre o que fez. Uma chave de API pessoal usada pelo seu próprio script ainda atua como proprietária.

Registrar um webhook de uma integração

Os administradores do espaço de trabalho podem gerenciar todos os endpoints genéricos do webhook. Uma credencial de API com capacidade de gravação não administrativa ou um agente OAuth interativo também pode criar uma quando seu usuário pertencer ao espaço de trabalho; Kanera marca esse ponto final scope: "connection", e apenas os mesmos administradores de conexão e espaço de trabalho podem listá-lo ou gerenciá-lo. Isso permite que um agente se inscreva em eventos de quadro sem receber autoridade de administrador do espaço de trabalho.

Usar POST /api/v1/workspaces/{workspaceId}/webhooks para criar o endpoint e salvar o único secret da resposta. O mesmo recurso expõe operações de lista, atualização, exclusão, rotação secreta, histórico de entrega e novas tentativas de entrega com falha. Veja Webhooks para o mapa de endpoint e regras de assinatura.

Um fluxo de integração confiável

1. Ligar GET /api/v1/workspaces ou GET /api/v1/boards para descobrir apenas os recursos que a credencial pode acessar.
2. Usar POST /api/v1/boards/{id}/open quando você precisar do quadro e de suas listas, cartões, membros, rótulos e campos personalizados em uma única resposta.
3. Armazene IDs retornados para mutações de API. Os nomes são editáveis; uma chave de cartão legível por humanos pode ser resolvida para a identificação do cartão atual quando uma pessoa ou registro externo fornece uma.
4. Valide corpos de gravação em relação ao esquema de operação em Scalar ou OpenAPI.
5. Tratar 401 como autenticação inválida, 403 como acesso insuficiente ou portão plano, 404 como dados ausentes ou inacessíveis, 409 como um conflito de estado, e 429 como um sinal para recuar.
6. Registre a resposta x-request-id em logs de integração sem registrar credenciais ou conteúdo confidencial.

Relacionamentos de cartão

Os relacionamentos conectam cartões no mesmo espaço de trabalho, inclusive entre seus quadros. direction lê do cartão no caminho: blocks significa que esta carta bloqueia o alvo, blocked_by significa que o alvo bloqueia esta carta, e relates_to não tem pedido obrigatório.

Método e caminho	Objetivo
GET /api/v1/cards/{cardId}/relations	Leia relacionamentos visíveis e hiddenBlockerCount.
POST /api/v1/cards/{cardId}/relations	Adicionar { "targetCardId": "<UUID>", "direction": "blocked_by" }.
DELETE /api/v1/cards/{cardId}/relations/{relationId}	Remova um relacionamento pelo seu ID.

Os detalhes do cartão incluem relations e hiddenBlockerCount; resumos de cartão expõem blockedByCount. Um cartão ativo é bloqueado enquanto pelo menos um pré-requisito está incompleto e não arquivado. Usar filters: { blockedOnly: true } com POST /api/v1/work/cards/query devolver apenas cartões abertos bloqueados, ou atRiskOnly: true para cartões abertos cujo bloqueador visível está vencido ou vencido depois deles. POST /api/v1/work/portfolio/query retorna blocked e atRisk conta por tabuleiro e em seus totais.

Adicionar um relacionamento existente é idempotente. Autolinks, links entre espaços de trabalho, ciclos de dependência e um cartão preenchido como um novo bloqueador são rejeitados. As gravações exigem acesso de edição ao cartão de caminho e ao cartão bloqueado, além de acesso de leitura ao outro cartão. Relacionamentos inacessíveis são omitidos nas leituras; seus bloqueadores ativos contribuem apenas para hiddenBlockerCount.

Limpar o último bloqueador ativo pode executar automações e enviar notificações de transferência. Reabrir ou restaurar um bloqueador pode bloquear o cartão novamente. A conclusão por meio da API permanece disponível sem o aviso interativo do aplicativo Web. Veja Relacionamentos e bloqueios de cartões para o comportamento do ciclo de vida.

Gráficos de dependência

POST /api/v1/cards/dependency-graph lê o gráfico atrás da visualização Dependências. Passe exatamente um escopo:

{ "boardId": "<board UUID>" }

Alternativamente passe { "workspaceId": "<workspace UUID>" } ou { "cardIds": ["<card UUID>"] }. Um escopo de ID de cartão aceita de 1 a 2.000 UUIDs. Este POST é uma leitura sem efeitos colaterais.

A resposta contém resumos compactos de cartão, bordas, pesquisas de quadro/lista/etiqueta/pessoas, campos personalizados de face de cartão e truncated. Cada carta adiciona inScope e seu canônico url. Cada quadro inclui canEdit para a autoridade de edição de dependência do chamador. Um blocks borda corre de sourceCardId (o pré-requisito) para targetCardId (o dependente); relates_to é simétrico.

A caminhada começa a partir de cartões de escopo abertos e desarquivados com relacionamentos, segue bordas de bloqueio em ambos os sentidos através de quadros legíveis e para em cartões concluídos. Vizinhos relacionados estão incluídos a um salto das sementes. Cartões inacessíveis são omitidos; blockedByCount ainda conta seus bloqueadores ativos. O gráfico para em 400 cartas e conjuntos truncated: true; restringir o escopo quando uma cadeia completa for necessária. As credenciais do espaço de trabalho permanecem dentro do espaço de trabalho.

Veja Visualização de Dependências para saber como o aplicativo apresenta e edita esses dados. O MCP retorna uma projeção expandida orientada ao agente, em vez desses resumos compactos.

Modelo de quadro e espaço de trabalho

A API do Kanera representa os dois modelos voltados para o usuário:

• Um espaço de trabalho padrão contém vários quadros.
• um quadro autônoma é retornada com kind: "board" por endpoints que expõem seu contêiner de apoio, mas os usuários o experimentam como um quadro independente.
• Os tabuleiros contêm cartas.
• Listas, rótulos e campos personalizados pertencem apenas a um quadro independente ou são compartilhados em todos os quadros em um espaço de trabalho padrão.
• Os pontos de extremidade de atribuição podem retornar cartões atribuídos entre quadros no espaço de trabalho.
• Os quadros privados só são visíveis onde a chave API tem acesso.
• Uma chave pessoal pode ver quadros em áreas de trabalho onde seu proprietário tem acesso.
• Uma chave de espaço de trabalho pode ver quadros somente dentro de seu espaço de trabalho.

Isso é importante ao construir integrações. Use um quadro autônoma quando seu esquema precisar permanecer independente. Em um espaço de trabalho, reutilize listas e campos existentes para que relatórios, consultas de atribuições e agregação de campos personalizados permaneçam consistentes. A UI de trabalho global pode abranger todos os quadros que a pessoa conectada pode acessar, enquanto uma chave de API do espaço de trabalho permanece com escopo definido para seu único espaço de trabalho.

Paginação e erros

Liste os endpoints que suportam o uso de paginação:

Parâmetro	Significado
limit	Número de registros a serem retornados.
before	Filtro estilo cursor para registros antes de um carimbo de data/hora.

Erros retornam JSON com:

Campo	Significado
code	Código de erro estável.
message	Mensagem de erro legível por humanos.
issues	Detalhes de validação opcionais.

Use o código de status HTTP e o código de erro juntos ao decidir se deseja tentar novamente, corrigir a entrada ou pedir a um administrador para atualizar o acesso.

Webhooks

Os webhooks permitem que sistemas externos reajam quando o trabalho muda no Kanera. Veja Webhooks para configuração, verificação de entrega e a lista completa de tipos de eventos de webhook suportados.

Se o objetivo é postar atividades de cartões em um canal de bate-papo da equipe, você não precisa criar nada: use Destinos de bate-papo para Slack, Discord, Telegram ou Zulip.

Links externos

Links externos permitem que as integrações armazenem mapeamentos duráveis entre registros Kanera e registros em outro sistema.

Use links externos quando precisar que os trabalhos de sincronização sejam idempotentes. Por exemplo, uma sincronização do Trello pode lembrar qual cartão Kanera mapeia para qual cartão Trello sem colocar metadados de integração ocultos na descrição do cartão.

Recomendações de segurança

• Use uma chave de API por integração.
• Use o escopo mais baixo que funciona.
• Armazene chaves e segredos de webhook em um gerenciador de segredos.
• Alterne chaves e segredos de webhook quando as pessoas saem ou os sistemas mudam.
• Não coloque chaves de API no Scratchpad, Notas, cartões, comentários, controle de origem, registros ou capturas de tela.
• Verifique as assinaturas do webhook antes de processar cargas.
• Torne os manipuladores de webhook idempotentes porque as entregas podem ser repetidas.
• Registre solicitações e IDs de eventos suficientes para depurar o comportamento de sincronização sem registrar segredos.

Páginas relacionadas

• Kanera CLI
• SDK TypeScript
• Conecte Kanera ao seu agente de IA
• Conecte um agente de IA
• Automações
• Trabalho Global
• Campos personalizados