Create a Record

Create a Record

The createTodo mutation allows you to create new records in Blue with comprehensive configuration options including custom fields, tags, assignments, and more. Records can be created in specific lists or automatically placed in the default list.

Basic Example

Create a simple record with just a title:

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

Advanced Example

Create a record with all available options:

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
    }
  }
}

Input Parameters

CreateTodoInput

CreateTodoInputPlacement Values

CreateTodoTagInput

*Note: You must provide either id (for existing tag) OR title (to create/find by title)

CreateTodoInputCustomField

CreateChecklistWithoutTodoInput

Custom Field Value Formats

When setting custom field values, use these formats based on field type:

Response Fields

The mutation returns a Todo object with comprehensive record details:

Required Permissions

Users must have appropriate workspace access to create records:

The mutation requires the user’s workspace access level to be OWNER, ADMIN, MEMBER, or CLIENT. Users with VIEW_ONLY or COMMENT_ONLY roles cannot create records.

Error Responses

WorkspaceNotFoundError

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

When: No workspace context is available for the user.

TodoListCreateTodoLimitError

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

When: The todo list already contains 100,000 records (maximum limit).

TodoListNotFoundError

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

When: The specified todoListId doesn’t exist or user lacks access.

CustomFieldValueParseError

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

When: Custom field value fails validation (e.g., invalid phone, rating out of range).

Important Notes

Performance

• Each todo list can contain up to 100,000 records
• Creating records triggers multiple background processes (webhooks, automations, search indexing)
• Batch operations are more efficient than creating records one at a time

Business Logic

• Position Handling: Default position is 65535.0 when neither position nor placement specified
• Date Logic:
  • If only duedAt is provided, startedAt is set to beginning of that day
  • If only startedAt is provided, duedAt is set to the same value
• Tag Creation: New tags are automatically created if they don’t exist with the specified title/color
• List Selection: If no todoListId provided, the first todo list in the workspace is used

Side Effects

Creating a record triggers:

• Activity log entry creation
• Webhook notifications
• Search index updates
• Automation rule execution (if configured)
• Email/push notifications (if notify: true)
• Formula and time duration custom field calculations
• Analytics and chart updates

Related Endpoints

• List Records: Query todos to retrieve existing records
• Update Record: Use updateTodo mutation to modify records
• List Custom Fields: Query to get available custom field IDs
• List Tags: Query to get existing tag IDs
• List Todo Lists: Query to get available todo list IDs