---

Criar um Registro

A mutação createTodo permite que você crie novos registros no Blue com opções de configuração abrangentes, incluindo campos personalizados, tags, atribuições e muito mais. Os registros podem ser criados em listas específicas ou automaticamente colocados na lista padrão.

Exemplo Básico

Crie um registro simples com apenas um título:

mutation CreateRecord {
  createTodo(
    input: {
      title: "New Task"
    }
  ) {
    id
    title
    position
  }
}

Exemplo Avançado

Crie um registro com todas as opções disponíveis:

mutation CreateRecordAdvanced {
  createTodo(
    input: {
      todoListId: "clm4n8qwx000008l0g4oxdqn7"
      title: "Product Launch Planning"
      placement: TOP
      description: "<p>Complete product launch preparation including marketing materials and documentation.</p>"
      startedAt: "2025-01-15T09:00:00Z"
      duedAt: "2025-02-01T17:00:00Z"
      notify: true
      assigneeIds: ["user_123", "user_456"]
      tags: [
        { id: "tag_existing_123" }
        { title: "Priority", color: "#ff4b4b" }
        { title: "Marketing" }
      ]
      customFields: [
        {
          customFieldId: "cf_budget_123"
          value: "50000 USD"
        }
        {
          customFieldId: "cf_status_456"
          value: "In Progress"
        }
      ]
      checklists: [
        {
          title: "Pre-launch Checklist"
          position: 1
        }
      ]
    }
  ) {
    id
    uid
    title
    position
    startedAt
    duedAt
    todoList {
      id
      title
    }
    users {
      id
      fullName
    }
    tags {
      id
      title
      color
    }
  }
}

Parâmetros de Entrada

CreateTodoInput

Parâmetro	Tipo	Obrigatório	Descrição
todoListId	String	Não	ID da lista de tarefas para adicionar o registro. Se não fornecido, usa a primeira lista de tarefas no projeto
title	String!	✅ Sim	Título do registro (obrigatório)
position	Float	Não	Posição personalizada na lista. Se não fornecido, usa o parâmetro de colocação
placement	CreateTodoInputPlacement	Não	Onde colocar o registro se a posição não for especificada (CIMA ou BAIXO)
startedAt	DateTime	Não	Data/hora de início para o registro
duedAt	DateTime	Não	Data/hora de vencimento para o registro
notify	Boolean	Não	Se deve enviar notificações para a criação deste registro
description	String	Não	Conteúdo da descrição em HTML (será sanitizado)
assigneeIds	[String!]	Não	Array de IDs de usuários para atribuir a este registro
checklists	[CreateChecklistWithoutTodoInput!]	Não	Array de checklists a serem criados com o registro
customFields	[CreateTodoInputCustomField]	Não	Array de valores de campos personalizados
tags	[CreateTodoTagInput!]	Não	Array de tags para anexar ao registro

Valores de CreateTodoInputPlacement

Valor	Descrição
TOP	Colocar no topo da lista (posição mais alta)
BOTTOM	Colocar na parte inferior da lista (posição mais baixa)

CreateTodoTagInput

Parâmetro	Tipo	Obrigatório	Descrição
id	String	Não*	ID da tag existente para conectar
title	String	Não*	Título da tag (cria nova se não existir)
color	String	Não	Cor hexadecimal para nova tag (padrão é #4a9fff)

*Nota: Você deve fornecer id (para tag existente) OU title (para criar/encontrar pelo título)

CreateTodoInputCustomField

Parâmetro	Tipo	Obrigatório	Descrição
customFieldId	String	Não	ID do campo personalizado
value	String	Não	Valor para o campo personalizado (veja o guia de formato abaixo)

CreateChecklistWithoutTodoInput

Parâmetro	Tipo	Obrigatório	Descrição
title	String!	✅ Sim	Título da checklist
position	Float	Não	Posição da checklist dentro do registro

Formatos de Valores de Campo Personalizado

Ao definir valores de campos personalizados, use estes formatos com base no tipo de campo:

Tipo de Campo	Formato	Exemplo
CHECKBOX	"true", "1", or "checked" for checked	"true"
COUNTRY	Country name or ISO code	"United States" or "US"
CURRENCY	Amount with optional currency	"50000 USD"
DATE	YYYY-MM-DD or date range	"2025-01-15" or "2025-01-15,2025-01-20"
NUMBER	Numeric value	"42"
PERCENT	Numeric value (% optional)	"75" or "75%"
RATING	Numeric value within range	"4" (if max is 5)
PHONE	International phone format	"+1234567890"
SELECT_SINGLE	Custom field option ID	"option_123"
SELECT_MULTI	Comma-separated option IDs	"option_1,option_2"
LOCATION	Latitude,longitude	"40.7128,-74.0060"
EMAIL	Valid email address	"user@example.com"
URL	Valid URL	"https://example.com"
TEXT	Plain text value	"Any text content"

Campos de Resposta

A mutação retorna um objeto Todo com detalhes abrangentes do registro:

Campo	Tipo	Descrição
id	String!	Identificador único para o registro
uid	String!	Identificador único alternativo
title	String!	Título do registro
position	Float!	Posição na lista
done	Boolean!	Status de conclusão
startedAt	DateTime	Data/hora de início
duedAt	DateTime	Data/hora de vencimento
todoList	TodoList	Detalhes da lista de tarefas associada
users	[User!]	Usuários atribuídos
tags	[Tag!]	Tags associadas
checklists	[Checklist!]	Checklists associadas
customFields	[CustomFieldValue!]	Valores de campos personalizados

Permissões Necessárias

Os usuários devem ter acesso apropriado ao projeto para criar registros:

Nível de Acesso	Pode Criar Registros
OWNER	✅ Sim
ADMIN	✅ Sim
MEMBER	✅ Sim
CLIENT	✅ Sim
COMMENT_ONLY	❌ Não
VIEW_ONLY	❌ Não

A mutação requer que o nível de acesso do projeto do usuário seja OWNER, ADMIN, MEMBER, ou CLIENT. Usuários com funções VIEW_ONLY ou COMMENT_ONLY não podem criar registros.

Respostas de Erro

ProjectNotFoundError

{
  "errors": [{
    "message": "Project was not found.",
    "extensions": {
      "code": "PROJECT_NOT_FOUND"
    }
  }]
}

Quando: Nenhum contexto de projeto está disponível para o usuário.

TodoListCreateTodoLimitError

{
  "errors": [{
    "message": "Todo list has reached the maximum number of todos.",
    "extensions": {
      "code": "TODO_LIST_CREATE_TODO_LIMIT_ERROR"
    }
  }]
}

Quando: A lista de tarefas já contém 100.000 registros (limite máximo).

TodoListNotFoundError

{
  "errors": [{
    "message": "Todo list was not found.",
    "extensions": {
      "code": "TODO_LIST_NOT_FOUND"
    }
  }]
}

Quando: A todoListId especificada não existe ou o usuário não tem acesso.

CustomFieldValueParseError

{
  "errors": [{
    "message": "Invalid phone number format",
    "extensions": {
      "code": "CUSTOM_FIELD_VALUE_PARSE_ERROR"
    }
  }]
}

Quando: O valor do campo personalizado falha na validação (por exemplo, telefone inválido, classificação fora do intervalo).

Notas Importantes

Desempenho

• Cada lista de tarefas pode conter até 100.000 registros
• Criar registros aciona múltiplos processos em segundo plano (webhooks, automações, indexação de pesquisa)
• Operações em lote são mais eficientes do que criar registros um por um

Lógica de Negócio

• Tratamento de Posição: A posição padrão é 65535.0 quando nem position nem placement são especificados
• Lógica de Data:
  • Se apenas duedAt for fornecido, startedAt é definido para o início daquele dia
  • Se apenas startedAt for fornecido, duedAt é definido para o mesmo valor
• Criação de Tag: Novas tags são criadas automaticamente se não existirem com o título/cor especificados
• Seleção de Lista: Se nenhuma todoListId for fornecida, a primeira lista de tarefas no projeto é usada

Efeitos Colaterais

Criar um registro aciona:

• Criação de entrada no log de atividades
• Notificações de webhook
• Atualizações de índice de pesquisa
• Execução de regras de automação (se configuradas)
• Notificações por e-mail/push (se notify: true)
• Cálculos de campos personalizados de fórmula e duração de tempo
• Atualizações de análises e gráficos

Endpoints Relacionados

• Listar Registros: Consultar tarefas para recuperar registros existentes
• Atualizar Registro: Usar a mutação updateTodo para modificar registros
• Listar Campos Personalizados: Consultar para obter IDs de campos personalizados disponíveis
• Listar Tags: Consultar para obter IDs de tags existentes
• Listar Listas de Tarefas: Consultar para obter IDs de listas de tarefas disponíveis