API Pública
Crie e gerencie flows, mapas mentais, tarefas, notas e lembretes programaticamente via API REST.
Autenticação
Todas as requisições exigem dois headers de autenticação. Gere seu token em Configurações > Avançado.
| Header | Valor | Descrição |
|---|---|---|
| X-User-Id | seu-uuid | UUID do usuário (visível em Configurações) |
| X-Api-Token | dflow_abc123... | Token gerado em Configurações > Avançado |
curl -X GET https://seudominio.com/api/v1/folders \
-H "X-User-Id: seu-uuid-aqui" \
-H "X-Api-Token: dflow_seu-token-aqui"GET /api/v1/folders
Lista todas as pastas do usuário em estrutura de árvore. Use o id retornado como folder_id ao criar flows ou mindmaps.
{
"folders": [
{
"id": "uuid-da-pasta",
"name": "Projetos",
"parent_id": null,
"root_id": null,
"icon": "folder",
"color": "#3b82f6",
"order_index": 0,
"children": [
{
"id": "uuid-subpasta",
"name": "Frontend",
"parent_id": "uuid-da-pasta",
"root_id": "uuid-da-pasta",
"children": []
}
]
}
]
}POST /api/v1/flows
Cria um novo flow dentro de uma pasta. O folder_id é obrigatório. Os campos id em steps, connections e checklist items são opcionais — se omitidos, UUIDs são gerados automaticamente.
{
"title": "Meu Fluxo de Deploy",
"folder_id": "uuid-da-pasta",
"content": {
"type": "flow",
"steps": [
{
"type": "start",
"title": "Início",
"status": "completed",
"order": 0,
"position": { "x": 250, "y": 50 },
"createdAt": "2026-02-24T00:00:00Z"
},
{
"type": "action",
"title": "Build",
"status": "pending",
"order": 1,
"position": { "x": 250, "y": 200 },
"createdAt": "2026-02-24T00:00:00Z"
},
{
"type": "end",
"title": "Fim",
"status": "pending",
"order": 2,
"position": { "x": 250, "y": 350 },
"createdAt": "2026-02-24T00:00:00Z"
}
],
"connections": [
{ "fromStepId": "step-1", "toStepId": "step-2" },
{ "fromStepId": "step-2", "toStepId": "step-3" }
]
}
}{
"id": "uuid-do-flow",
"title": "Meu Fluxo de Deploy",
"folder_id": "uuid-da-pasta",
"created_at": "2026-02-24T12:00:00Z"
}GET /api/v1/flows/:id
Exporta um flow como JSON, incluindo metadados _meta.
{
"_meta": {
"app": "doFlow",
"version": "12.1",
"schema_version": 1,
"exported_at": "2026-02-24T12:00:00Z",
"type": "flow"
},
"id": "uuid-do-flow",
"title": "Meu Fluxo",
"folder_id": "uuid-da-pasta",
"content": { ... FlowContent ... },
"created_at": "...",
"updated_at": "..."
}PUT /api/v1/flows/:id
Atualiza título e/ou conteúdo de um flow existente. Campos são opcionais. IDs em steps/connections/checklist são preenchidos automaticamente se omitidos.
{
"title": "Novo Título",
"content": { ... FlowContent ... }
}POST /api/v1/mindmaps
Cria um novo mapa mental dentro de uma pasta.
{
"title": "Brainstorm Projeto X",
"folder_id": "uuid-da-pasta",
"content": {
"type": "mindmap",
"nodes": [
{
"id": "root",
"label": "Projeto X",
"parentId": null,
"position": { "x": 0, "y": 0 },
"order": 0
},
{
"id": "node-1",
"label": "Frontend",
"parentId": "root",
"position": { "x": 220, "y": -50 },
"order": 0
},
{
"id": "node-2",
"label": "Backend",
"parentId": "root",
"position": { "x": 220, "y": 50 },
"order": 1
}
]
}
}{
"id": "uuid-do-mindmap",
"title": "Brainstorm Projeto X",
"folder_id": "uuid-da-pasta",
"created_at": "2026-02-24T12:00:00Z"
}GET /api/v1/mindmaps/:id
Exporta um mapa mental como JSON com metadados _meta.
PUT /api/v1/mindmaps/:id
Atualiza título e/ou conteúdo de um mapa mental existente.
POST /api/v1/todos
Cria uma nova lista de tarefas. O content é opcional — se omitido, cria uma lista vazia.
{
"title": "Sprint 12",
"folder_id": "uuid-da-pasta",
"content": {
"type": "todoList",
"items": [
{
"id": "uuid-item-1",
"text": "Implementar login",
"completed": false,
"order": 0,
"createdAt": "2026-02-24T00:00:00Z"
},
{
"id": "uuid-item-2",
"text": "Escrever testes",
"completed": false,
"order": 1,
"createdAt": "2026-02-24T00:00:00Z"
}
]
}
}{
"id": "uuid-da-lista",
"title": "Sprint 12",
"folder_id": "uuid-da-pasta",
"created_at": "2026-02-24T12:00:00Z"
}GET /api/v1/todos/:id
Retorna a lista de tarefas com _meta e conteúdo completo.
PUT /api/v1/todos/:id
Atualiza título e/ou conteúdo. Campos opcionais.
{
"title": "Sprint 12 (atualizado)",
"content": {
"type": "todoList",
"items": [ ... ]
}
}DELETE /api/v1/todos/:id
Deleta permanentemente a lista de tarefas e seus dados relacionados.
{ "deleted": true }POST /api/v1/notes
Cria uma nova nota com conteúdo no formato Tiptap (editor de texto rico). O content é opcional.
{
"title": "Anotações da reunião",
"folder_id": "uuid-da-pasta",
"content": {
"type": "doc",
"content": [
{
"type": "heading",
"attrs": { "level": 2 },
"content": [{ "type": "text", "text": "Pauta" }]
},
{
"type": "paragraph",
"content": [{ "type": "text", "text": "Discutir roadmap Q2." }]
}
]
}
}{
"id": "uuid-da-nota",
"title": "Anotações da reunião",
"folder_id": "uuid-da-pasta",
"created_at": "2026-02-24T12:00:00Z"
}GET /api/v1/notes/:id
Retorna a nota com _meta e conteúdo Tiptap.
PUT /api/v1/notes/:id
Atualiza título e/ou conteúdo. Campos opcionais.
POST /api/v1/reminders
Cria um novo lembrete com data/hora de disparo. O campo reminder_at é obrigatório (ISO 8601).
{
"title": "Reunião com cliente",
"folder_id": "uuid-da-pasta",
"description": "Preparar apresentação de progresso do projeto.",
"reminder_at": "2026-03-01T14:00:00Z"
}{
"id": "uuid-do-lembrete",
"title": "Reunião com cliente",
"folder_id": "uuid-da-pasta",
"reminder_at": "2026-03-01T14:00:00Z",
"created_at": "2026-02-24T12:00:00Z"
}GET /api/v1/reminders/:id
Retorna o lembrete com _meta, description, reminder_at e notification_sent.
PUT /api/v1/reminders/:id
Atualiza título, descrição e/ou data. Se reminder_at for atualizado, notification_sent é resetado para false.
{
"title": "Reunião remarcada",
"description": "Nova data confirmada.",
"reminder_at": "2026-03-05T10:00:00Z"
}Schemas JSON
FlowStep
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| id | string (UUID) | Não | Auto-gerado se omitido |
| type | 'start'|'end'|'action'|'decision'|'approval'|'wait'|'notify' | Sim | Tipo da etapa |
| title | string | Sim | Título (max 200 chars) |
| description | string | Não | Descrição detalhada (max 2000 chars) |
| status | 'pending'|'active'|'completed'|'skipped' | Sim | Estado da etapa |
| order | number | Sim | Posição na ordem |
| position | { x, y } | Não | Posição no canvas |
| assignee | string | Não | Responsável (max 200 chars) |
| dueDate | string (ISO) | null | Não | Data limite |
| estimatedDuration | string | Não | Duração estimada (ex: "2h", "3 dias") |
| checklist | FlowChecklistItem[] | Não | Itens de verificação (max 30) |
| links | { label, url }[] | Não | Links relacionados (max 10) |
| notes | string | Não | Anotações livres (max 5000 chars) |
| branches | { label, targetStepId, color? }[] | Não | Ramos para decisões (max 5) |
| color | string | Não | Cor da etapa (hex, max 20 chars) |
| actor | string | Não | Persona/papel no processo (max 100 chars) |
| style | { color?, icon? } | Não | Estilo visual customizado |
| metadata | Record<string, unknown> | Não | Dados livres (max 10KB serializado) |
| tags | string[] | Não | Tags de categorização (max 20, 50 chars cada) |
| createdAt | string (ISO) | Sim | Data de criação |
Exemplo com novos campos
{
"type": "action",
"title": "Code Review",
"description": "Revisão do PR antes do merge",
"status": "active",
"order": 2,
"position": { "x": 250, "y": 200 },
"assignee": "João",
"actor": "Tech Lead",
"style": { "color": "#8b5cf6", "icon": "GitPullRequest" },
"tags": ["review", "qualidade", "sprint-12"],
"metadata": {
"pr_number": 142,
"repo": "doflow/frontend",
"min_approvals": 2
},
"checklist": [
{ "text": "Verificar testes", "completed": true },
{ "text": "Validar types", "completed": false }
],
"createdAt": "2026-02-24T00:00:00Z"
}FlowChecklistItem
Cada etapa do flow pode conter uma checklist interna para acompanhamento granular. Máximo de 30 itens por etapa.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| id | string (UUID) | Não | Auto-gerado se omitido |
| text | string | Sim | Texto do item (max 500 chars) |
| completed | boolean | Sim | Se o item foi concluído |
FlowConnection
Conexões definem as setas entre etapas. Use label para nomear o caminho e condition para documentar a condição lógica (especialmente útil em etapas de decisão).
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| id | string (UUID) | Não | Auto-gerado se omitido |
| fromStepId | string (UUID) | Sim | ID da etapa de origem |
| toStepId | string (UUID) | Sim | ID da etapa de destino |
| label | string | Não | Rótulo exibido na seta (max 100). Ex: "Sim", "Não" |
| condition | string | Não | Condição lógica (max 500). Ex: "aprovações >= 2" |
| animated | boolean | Não | Se a conexão tem animação visual |
| sourceHandle | string | Não | Posição de saída. Veja Handles |
| targetHandle | string | Não | Posição de entrada. Veja Handles |
{
"connections": [
{
"fromStepId": "step-decisao",
"toStepId": "step-aprovado",
"label": "Sim",
"condition": "aprovações >= 2",
"sourceHandle": "right",
"targetHandle": "left"
},
{
"fromStepId": "step-decisao",
"toStepId": "step-revisao",
"label": "Não",
"condition": "aprovações < 2",
"sourceHandle": "bottom",
"targetHandle": "top"
}
]
}TodoItem
Cada item dentro de uma TodoListContent. O content de uma lista de tarefas é { type: "todoList", items: TodoItem[] }. Máximo de 500 itens por lista.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| id | string (UUID) | Sim | Identificador único |
| text | string | Sim | Texto da tarefa (max 1000 chars) |
| completed | boolean | Sim | Se a tarefa está concluída |
| dueDate | string ('AAAA-MM-DD' ou ISO legado) | null | Não | Data de vencimento (dia, sem hora) |
| order | number | Sim | Posição na lista |
| createdAt | string (ISO) | Sim | Data de criação |
| status | string | Não | ID da coluna Kanban (ex: "todo", "in-progress", "done") |
| subtasks | TodoItem[] | Não | Subtarefas (max 20, 1 nível) |
Lembrete (Reminder)
Lembretes usam campos específicos na tabela. O body do POST/PUT aceita description e reminder_at diretamente (não como content JSONB).
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| title | string | Sim (POST) | Título do lembrete (max 200 chars) |
| description | string | Não | Descrição (max 5000 chars) |
| reminder_at | string (ISO) | Sim (POST) | Data/hora de disparo |
| notification_sent | boolean | — | Somente leitura (GET). Resetado ao alterar reminder_at |
TiptapContent (Nota)
Notas usam o formato Tiptap JSON. O content é { type: "doc", content: [...] } com nós como paragraph, heading, bulletList, etc. URLs são sanitizadas (apenas http/https/mailto/tel permitidos).
MindMapNode
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| id | string | Sim | Identificador único |
| label | string | Sim | Texto do nó (max 200 chars) |
| parentId | string | null | Sim | null = nó raiz |
| position | { x, y } | Sim | Posição no canvas |
| order | number | Sim | Ordem entre irmãos |
| style | { color?, emoji? } | Não | Estilo visual |
| collapsed | boolean | Não | Recolher filhos |
| notes | string | Não | Anotações (max 2000 chars) |
Handles (Posição das Conexões)
Use sourceHandle e targetHandle nas connections para controlar de qual lado do nó a seta sai e entra. Se omitidos, o padrão é saída por baixo e entrada por cima.
| Valor | sourceHandle | targetHandle |
|---|---|---|
| "top" | Seta sai por cima do nó | Seta entra por cima (padrão) |
| "bottom" | Seta sai por baixo (padrão) | Seta entra por baixo |
| "left" | Seta sai pela esquerda | Seta entra pela esquerda |
| "right" | Seta sai pela direita | Seta entra pela direita |
{
"fromStepId": "step-a",
"toStepId": "step-b",
"sourceHandle": "right",
"targetHandle": "left"
}Os valores são normalizados internamente para os IDs corretos do React Flow. Nomes amigáveis como "left" são convertidos automaticamente — você não precisa se preocupar com IDs internos.
Campo _meta
Todo JSON exportado (via UI ou API GET) inclui um campo _meta para interoperabilidade. Na importação (POST), o campo é opcional.
{
"_meta": {
"app": "doFlow",
"version": "12.1",
"schema_version": 1,
"exported_at": "2026-02-24T12:00:00.000Z",
"type": "flow" | "mindmap" | "todo" | "note" | "reminder"
}
}- schema_version: permite futuras migrações de formato
- exported_at: data/hora da exportação (ISO 8601)
- type: identifica o tipo do recurso
Códigos de erro
| HTTP | Código | Mensagem |
|---|---|---|
401 | API_TOKEN_REQUIRED | Token de API obrigatório |
401 | API_TOKEN_INVALID | Token de API inválido |
400 | API_INVALID_PAYLOAD | Payload da API inválido (detalhes no campo error) |
404 | LIST_NOT_FOUND | Lista não encontrada |
404 | FOLDER_NOT_FOUND | Pasta não encontrada ou sem permissão |
500 | DATABASE_ERROR | Erro interno do banco de dados |
{
"error": "Mensagem descritiva do erro",
"code": "API_TOKEN_INVALID"
}