Pular para o conteúdo principal
doFlow
API v1
v12.1

API Pública

Crie e gerencie flows, mapas mentais, tarefas, notas e lembretes programaticamente via API REST.

REST
JSON
Autenticação por token

Autenticação

Todas as requisições exigem dois headers de autenticação. Gere seu token em Configurações > Avançado.

HeaderValorDescrição
X-User-Idseu-uuidUUID do usuário (visível em Configurações)
X-Api-Tokendflow_abc123...Token gerado em Configurações > Avançado
Exemplo cURL
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.

Resposta 200
{
  "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.

Request Body
{
  "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" }
    ]
  }
}
Resposta 201
{
  "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.

Resposta 200
{
  "_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.

Request Body
{
  "title": "Novo Título",
  "content": { ... FlowContent ... }
}

POST /api/v1/mindmaps

Cria um novo mapa mental dentro de uma pasta.

Request Body
{
  "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
      }
    ]
  }
}
Resposta 201
{
  "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.

Request Body
{
  "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"
      }
    ]
  }
}
Resposta 201
{
  "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.

Request Body
{
  "title": "Sprint 12 (atualizado)",
  "content": {
    "type": "todoList",
    "items": [ ... ]
  }
}

DELETE /api/v1/todos/:id

Deleta permanentemente a lista de tarefas e seus dados relacionados.

Resposta 200
{ "deleted": true }

POST /api/v1/notes

Cria uma nova nota com conteúdo no formato Tiptap (editor de texto rico). O content é opcional.

Request Body
{
  "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." }]
      }
    ]
  }
}
Resposta 201
{
  "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).

Request Body
{
  "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"
}
Resposta 201
{
  "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.

Request Body
{
  "title": "Reunião remarcada",
  "description": "Nova data confirmada.",
  "reminder_at": "2026-03-05T10:00:00Z"
}

Schemas JSON

FlowStep

CampoTipoObrigatórioDescrição
idstring (UUID)NãoAuto-gerado se omitido
type'start'|'end'|'action'|'decision'|'approval'|'wait'|'notify'SimTipo da etapa
titlestringSimTítulo (max 200 chars)
descriptionstringNãoDescrição detalhada (max 2000 chars)
status'pending'|'active'|'completed'|'skipped'SimEstado da etapa
ordernumberSimPosição na ordem
position{ x, y }NãoPosição no canvas
assigneestringNãoResponsável (max 200 chars)
dueDatestring (ISO) | nullNãoData limite
estimatedDurationstringNãoDuração estimada (ex: "2h", "3 dias")
checklistFlowChecklistItem[]NãoItens de verificação (max 30)
links{ label, url }[]NãoLinks relacionados (max 10)
notesstringNãoAnotações livres (max 5000 chars)
branches{ label, targetStepId, color? }[]NãoRamos para decisões (max 5)
colorstringNãoCor da etapa (hex, max 20 chars)
actorstringNãoPersona/papel no processo (max 100 chars)
style{ color?, icon? }NãoEstilo visual customizado
metadataRecord<string, unknown>NãoDados livres (max 10KB serializado)
tagsstring[]NãoTags de categorização (max 20, 50 chars cada)
createdAtstring (ISO)SimData de criação

Exemplo com novos campos

FlowStep completo
{
  "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.

CampoTipoObrigatórioDescrição
idstring (UUID)NãoAuto-gerado se omitido
textstringSimTexto do item (max 500 chars)
completedbooleanSimSe 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).

CampoTipoObrigatórioDescrição
idstring (UUID)NãoAuto-gerado se omitido
fromStepIdstring (UUID)SimID da etapa de origem
toStepIdstring (UUID)SimID da etapa de destino
labelstringNãoRótulo exibido na seta (max 100). Ex: "Sim", "Não"
conditionstringNãoCondição lógica (max 500). Ex: "aprovações >= 2"
animatedbooleanNãoSe a conexão tem animação visual
sourceHandlestringNãoPosição de saída. Veja Handles
targetHandlestringNãoPosição de entrada. Veja Handles
Exemplo com condition e label
{
  "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.

CampoTipoObrigatórioDescrição
idstring (UUID)SimIdentificador único
textstringSimTexto da tarefa (max 1000 chars)
completedbooleanSimSe a tarefa está concluída
dueDatestring ('AAAA-MM-DD' ou ISO legado) | nullNãoData de vencimento (dia, sem hora)
ordernumberSimPosição na lista
createdAtstring (ISO)SimData de criação
statusstringNãoID da coluna Kanban (ex: "todo", "in-progress", "done")
subtasksTodoItem[]NãoSubtarefas (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).

CampoTipoObrigatórioDescrição
titlestringSim (POST)Título do lembrete (max 200 chars)
descriptionstringNãoDescrição (max 5000 chars)
reminder_atstring (ISO)Sim (POST)Data/hora de disparo
notification_sentboolean—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

CampoTipoObrigatórioDescrição
idstringSimIdentificador único
labelstringSimTexto do nó (max 200 chars)
parentIdstring | nullSimnull = nó raiz
position{ x, y }SimPosição no canvas
ordernumberSimOrdem entre irmãos
style{ color?, emoji? }NãoEstilo visual
collapsedbooleanNãoRecolher filhos
notesstringNãoAnotaçõ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.

ValorsourceHandletargetHandle
"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 esquerdaSeta entra pela esquerda
"right"Seta sai pela direitaSeta entra pela direita
Exemplo — seta horizontal
{
  "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
{
  "_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

HTTPCódigoMensagem
401
API_TOKEN_REQUIREDToken de API obrigatório
401
API_TOKEN_INVALIDToken de API inválido
400
API_INVALID_PAYLOADPayload da API inválido (detalhes no campo error)
404
LIST_NOT_FOUNDLista não encontrada
404
FOLDER_NOT_FOUNDPasta não encontrada ou sem permissão
500
DATABASE_ERRORErro interno do banco de dados
Formato de erro
{
  "error": "Mensagem descritiva do erro",
  "code": "API_TOKEN_INVALID"
}