Documentação

API dn.task

Referência completa dos endpoints REST. Use o YAML para alimentar IAs e geradores de cliente (OpenAPI 3.1).

Basehttps://dbeknvfrzagveqeqdnwo.supabase.co/functions/v1/api-gateway
Baixar .md

API dn.task — Documentação Completa

A API REST da dn.task permite que agentes do dnOS e integrações externas leiam e modifiquem boards, listas, cards, comentários, checklists, automações e analytics dos workspaces.

URL Base

https://dbeknvfrzagveqeqdnwo.supabase.co/functions/v1/api-gateway

Todos os endpoints são prefixados por essa URL. O escopo de uma chave de API é sempre um único workspace.

Autenticação

Toda requisição (exceto as internas de automação) DEVE incluir o header:

X-API-Key: dntask_sua_chave_aqui
  • Chaves são geradas em Configurações → API Keys
  • A chave plain só é exibida uma única vez no momento da criação
  • O servidor valida o SHA-256 da chave contra api_keys.key_hash
  • Chaves desativadas ou inexistentes retornam 401 UNAUTHORIZED
  • O campo last_used_at é atualizado automaticamente a cada chamada autenticada

Exemplo

curl -X GET "https://dbeknvfrzagveqeqdnwo.supabase.co/functions/v1/api-gateway/boards?workspace_id=SEU_WORKSPACE_ID" \
  -H "X-API-Key: dntask_sua_chave_aqui"

Formato Padrão de Erro

Todas as respostas de erro seguem este formato JSON:

{
  "error": "Mensagem legível descrevendo o problema",
  "code": "CODE_CONSTANT"
}

Códigos de erro possíveis

HTTPcodeQuando ocorre
400VALIDATION_ERRORParâmetros obrigatórios faltando ou inválidos
401UNAUTHORIZEDHeader X-API-Key ausente, inválido ou chave desativada
403UNAUTHORIZEDA chave existe, mas o recurso pertence a outro workspace
404NOT_FOUNDRecurso (board, card, lista, membro, automação) não encontrado
405VALIDATION_ERRORMétodo HTTP não suportado para a rota
500INTERNAL_ERRORFalha interna ou erro do banco de dados

Endpoints

Boards

GET /boards

Lista os boards (não arquivados) do workspace.

  • Query params

    • workspace_id (obrigatório, uuid) — workspace dono dos boards

  • Request

    curl "https://dbeknvfrzagveqeqdnwo.supabase.co/functions/v1/api-gateway/boards?workspace_id=WS" \
  -H "X-API-Key: dntask_..."

  • Response 200

    {
  "boards": [
    {
      "id": "uuid",
      "name": "Sprint 12",
      "description": null,
      "created_at": "2026-05-01T10:00:00Z",
      "lists_count": 4,
      "open_cards_count": 27
    }
  ]
}

  • Erros: 400 VALIDATION_ERROR, 401/403 UNAUTHORIZED, 500 INTERNAL_ERROR

GET /boards/:board_id/cards

Lista cards de um board, com filtros opcionais.

  • Path params: board_id (uuid)

  • Query params

    • archived — "true" ou "false" (default: "false")
    • list_id — filtra por lista
    • due_status — on_track | approaching | overdue | done
    • member_id — apenas cards atribuídos a este membro
    • label_id — apenas cards com este label

  • Response 200

    {
  "cards": [
    {
      "id": "uuid",
      "title": "Implementar login",
      "description": "Texto markdown...",
      "list_id": "uuid",
      "list_name": "Em andamento",
      "board_id": "uuid",
      "due_date": "2026-05-20T18:00:00Z",
      "due_status": "on_track",
      "archived": false,
      "position": 3,
      "created_at": "2026-05-01T10:00:00Z",
      "updated_at": "2026-05-10T14:00:00Z",
      "members": [{ "id": "uuid", "display_name": "Diego", "avatar_url": null, "is_agent": false }],
      "labels":  [{ "id": "uuid", "name": "Bug", "color": "#ef4444" }],
      "checklist_progress": "2/5",
      "comments_count": 4,
      "share_url": "https://dntask.lovable.app/board/BOARD_ID?card=CARD_ID"
    }
  ]
}

  • Erros: 401/403 UNAUTHORIZED, 404 NOT_FOUND, 500 INTERNAL_ERROR

Cards

GET /cards/:card_id

Retorna o card completo (mesmos campos de GET /boards/:id/cards), incluindo o link compartilhável (share_url) que abre o card direto no app web.

  • Path params: card_id (uuid)
  • Response 200: objeto card completo, com share_url no formato https://dntask.lovable.app/board/{board_id}?card={card_id}.
  • Erros: 401/403 UNAUTHORIZED, 404 NOT_FOUND

💡 O campo share_url é retornado em todas as respostas que incluem um card (list, create, patch, move, archive, get). Basta abrir essa URL no navegador (estando logado no workspace) que o board carrega e o cartão é aberto automaticamente.

POST /cards

Cria um novo card.

  • Body

    {
  "list_id": "uuid (obrigatório)",
  "title": "string (obrigatório)",
  "description": "string | null",
  "due_date": "ISO 8601 | null",
  "member_ids": ["uuid", "..."],
  "label_ids":  ["uuid", "..."]
}

  • Request

    curl -X POST "https://dbeknvfrzagveqeqdnwo.supabase.co/functions/v1/api-gateway/cards" \
  -H "X-API-Key: dntask_..." \
  -H "Content-Type: application/json" \
  -d '{"list_id":"LISTA","title":"Novo card","description":"detalhes"}'

  • Response 201: objeto card completo (mesmo formato de GET /boards/:id/cards)

  • Erros: 400 VALIDATION_ERROR, 401/403 UNAUTHORIZED, 404 NOT_FOUND, 500 INTERNAL_ERROR

PATCH /cards/:card_id

Atualiza campos do card. Mover de lista também atualiza board_id automaticamente.

  • Body (todos opcionais)

    {
  "title": "string",
  "description": "string | null",
  "due_date": "ISO 8601 | null",
  "due_status": "on_track | approaching | overdue | done",
  "list_id": "uuid"
}

  • Response 200: objeto card completo atualizado

  • Erros: 401/403 UNAUTHORIZED, 404 NOT_FOUND, 500 INTERNAL_ERROR

POST /cards/:card_id/archive

Arquiva um card (não remove do banco). Use unarchive para reverter.

  • Response 200: objeto card completo com archived: true
  • Erros: 401/403 UNAUTHORIZED, 404 NOT_FOUND

POST /cards/:card_id/unarchive

Desarquiva um card previamente arquivado.

  • Response 200: objeto card completo com archived: false
  • Erros: 401/403 UNAUTHORIZED, 404 NOT_FOUND

DELETE /cards/:card_id

Remove permanentemente um card e todos os dados relacionados (comentários, checklists, anexos, labels). Operação irreversível — prefira archive quando quiser apenas ocultar.

  • Response 200: { "success": true, "id": "uuid" }
  • Erros: 401/403 UNAUTHORIZED, 404 NOT_FOUND, 500 INTERNAL_ERROR

POST /cards/:card_id/move

Move um card para outra lista (e opcionalmente em uma posição específica).

  • Body 
    { "list_id": "uuid (obrigatório)", "position": 2 }
  • Se position não for fornecido, o card vai para o fim da lista alvo.
  • Response 200: objeto card completo atualizado
  • Erros: 400 VALIDATION_ERROR, 401/403 UNAUTHORIZED, 404 NOT_FOUND, 500 INTERNAL_ERROR

POST /cards/:card_id/comments

Adiciona um comentário. A chave deve estar associada a um membro (member_id).

  • Body: { "content": "Texto do comentário" }
  • Response 201 
    { "id": "uuid", "card_id": "uuid", "author_id": "uuid", "content": "...", "created_at": "..." }
  • Erros: 400 VALIDATION_ERROR, 401 UNAUTHORIZED (chave sem membro), 403 UNAUTHORIZED, 404 NOT_FOUND

PATCH /cards/:card_id/checklist-items/:item_id

Marca/desmarca um item de checklist.

  • Body: { "completed": true }
  • Response 200: objeto checklist_item atualizado
  • Erros: 400 VALIDATION_ERROR, 401/403 UNAUTHORIZED, 404 NOT_FOUND

Members

GET /members

Lista membros do workspace.

  • Query: workspace_id (obrigatório)
  • Response 200 
    {
  "members": [
    { "id": "uuid", "display_name": "Diego", "role": "super_admin",
      "is_agent": false, "agent_id": null, "avatar_url": null }
  ]
}

GET /members/:member_id/cards

Lista cards (não arquivados) atribuídos a um membro.

  • Query: due_status, board_id (opcionais)
  • Response 200: { "cards": [...] } (mesmo formato dos cards completos)

Labels

GET /labels

Lista labels de um board.

  • Query: board_id (obrigatório)
  • Response 200 
    { "labels": [{ "id": "uuid", "name": "Bug", "color": "#ef4444", "board_id": "uuid" }] }

GET /boards/{board_id}/labels

Mesma lista, no formato RESTful.

  • Response 200: { "labels": [{ "id", "name", "color", "board_id" }] }

POST /boards/{board_id}/labels

Cria uma nova etiqueta no board.

  • Body 
    { "name": "Bug", "color": "#ef4444" }
  • Response 201: { "id", "name", "color", "board_id" }
  • color deve estar no formato #RRGGBB (padrão: #3D61FF).

PATCH /labels/{label_id}

Atualiza nome e/ou cor de uma etiqueta.

  • Body (campos opcionais) 
    { "name": "Critical", "color": "#dc2626" }
  • Response 200: { "id", "name", "color", "board_id" }

DELETE /labels/{label_id}

Remove a etiqueta e a desvincula de todos os cards.

  • Response 200: { "success": true }

Automations

GET /automations

Lista automações do workspace.

  • Query: workspace_id (obrigatório), board_id (opcional)
  • Response 200: { "automations": [ ... ] }

POST /automations

Cria uma automação.

  • Body 
    {
  "name": "Mover para Done quando concluído",
  "active": true,
  "board_id": "uuid | null",
  "trigger_type": "card_created | card_moved | label_added | checklist_completed | due_date_overdue | due_date_approaching",
  "trigger_config": { "list_id": "uuid", "label_id": "uuid", "hours_before": 24 },
  "action_type": "move_card | assign_member | add_label | set_due_status | add_comment | notify_member",
  "action_config": { "list_id": "uuid", "member_id": "uuid", "label_id": "uuid", "due_status": "done", "content": "...", "message": "..." }
}
  • Response 201: objeto automation
  • Erros: 400 VALIDATION_ERROR, 401/403 UNAUTHORIZED, 500 INTERNAL_ERROR

PATCH /automations/:id

Atualiza qualquer subconjunto dos campos acima. Response 200: automation atualizada.

DELETE /automations/:id

Remove a automação. Response 200: { "deleted": true }

GET /automations/:id/logs

Histórico de execuções.

  • Query: limit (default 50, máx 200)
  • Response 200: { "logs": [ { "id", "automation_id", "card_id", "status", "detail", "triggered_at" } ] }

Analytics

GET /analytics/overview

Visão geral do workspace.

  • Query: workspace_id (obrigatório), period = 7d | 30d (default) | 90d
  • Response 200 
    {
  "period": "30d",
  "total_cards_open": 84,
  "total_cards_done": 156,
  "total_cards_overdue": 7,
  "cards_created_in_period": 42,
  "cards_completed_in_period": 38,
  "completion_rate": 90.5,
  "most_active_board": { "id": "uuid", "name": "Sprint 12", "cards_count": 22 },
  "most_active_member": { "id": "uuid", "name": "Diego", "actions_count": 134 }
}

GET /analytics/boards/:board_id

Métricas detalhadas de um board: cycle time por lista, throughput semanal e top members.

  • Query: period
  • Response 200: { "board_id", "board_name", "period", "lists": [...], "throughput": [...], "top_members": [...] }

GET /analytics/members

Atividade dos membros no período.

  • Query: workspace_id (obrigatório), period
  • Response 200: { "period", "members": [ { "member_id", "display_name", "total_actions", "last_active_at", ... } ] }

GET /analytics/cards/overdue

Cards atrasados, ordenados por due_date ascendente.

  • Query: workspace_id (obrigatório), board_id (opcional)
  • Response 200 
    {
  "cards": [
    { "card_id": "uuid", "title": "...", "board_name": "...", "list_name": "...",
      "due_date": "2026-05-10T...", "days_overdue": 5, "members": [...] }
  ]
}

Boas Práticas

  • Idempotência: POST /cards cria um novo card a cada chamada — guarde o id retornado para evitar duplicatas.
  • Paginação: a API atual retorna todos os registros do escopo solicitado. Use filtros (list_id, due_status, label_id, member_id) para limitar volumes.
  • Rate limiting: não há limite explícito, mas mantenha um padrão razoável (≤ 10 req/s por chave).
  • Segurança: nunca exponha a chave em código client-side. Use no servidor da sua integração.

Última atualização: 2026-05-15