Records

Records are the core unit of work in Blue: the cards you create in a list, assign to people, tag, date, and fill with custom field values. In the API a record is a Record object, and it lives inside a list (RecordList) within a workspace (Workspace).

This section covers creating records and every operation you reach for next - reading, updating, moving, completing, and organizing them. The most common starting point, createRecord, is documented in full below.

POST https://api.blue.app/graphql
blue-token-id: YOUR_TOKEN_ID
blue-token-secret: YOUR_TOKEN_SECRET
blue-org-id: YOUR_ORG_ID
blue-workspace-id: project_123

The blue-workspace-id header scopes record operations to one workspace. Company and project headers accept either an ID or a slug. Header names are case-insensitive.

Operations

Two lifecycle mutations don’t yet have dedicated pages but round out the record surface:

Create a record

Use the createRecord mutation to add a record to a list. The only required input is a title; everything else - the target list, dates, assignees, tags, checklists, and custom field values - is optional and can be set in the same call.

Request

The smallest call creates a record from a title alone. If you omit todoListId, the record lands in the workspace’s first list (one is created if the workspace has none).

mutation CreateRecord {
  createRecord(input: { title: "Draft launch plan" }) {
    id
    title
    position
  }
}

Parameters

CreateRecordInput

CreateRecordInputPlacement

CreateRecordTagInput

Provide either id (to attach an existing tag) or title (to find or create a tag by title).

CreateRecordInputCustomField

CreateChecklistWithoutTodoInput

Custom field value formats

The value string is parsed based on the target field’s CustomFieldType. Common types:

Computed types - FORMULA, LOOKUP, ROLLUP, REFERENCED_BY, TIME_DURATION - derive their own values and ignore any value you pass at creation. See the custom field types reference for full per-type details.

Response

createRecord returns the created Record.

{
  "data": {
    "createRecord": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "title": "Draft launch plan",
      "position": 131070.42
    }
  }
}

Returns

The mutation returns the Record object. Common fields to select:

Full example

Create a record with a target list, dates, assignees, tags, a checklist, and custom field values, then read back the resolved relations.

mutation CreateRecordAdvanced {
  createRecord(
    input: {
      todoListId: "list_123"
      title: "Product launch planning"
      placement: BOTTOM
      description: "<p>Coordinate marketing, docs, and release.</p>"
      startedAt: "2025-01-15T09:00:00Z"
      duedAt: "2025-02-01T17:00:00Z"
      notify: true
      assigneeIds: ["user_123", "user_456"]
      tags: [{ id: "tag_123" }, { title: "Priority", color: "#ff4b4b" }, { title: "Marketing" }]
      customFields: [
        { customFieldId: "field_123", value: "50000 USD" }
        { customFieldId: "field_456", value: "option_123" }
      ]
      checklists: [{ title: "Pre-launch checklist", position: 1 }]
    }
  ) {
    id
    uid
    title
    position
    startedAt
    duedAt
    todoList {
      id
      title
    }
    users {
      id
      fullName
    }
    tags {
      id
      title
      color
    }
  }
}

Errors

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

Behavior

• Position. When position is set it wins. Otherwise placement decides: the default (no placement) and TOP insert above the current first record; BOTTOM inserts after the last. The gap constant 65535 is only used directly when the list is empty.
• Dates. Passing only duedAt sets startedAt to the start of that day; passing only startedAt sets duedAt to the same point in time. Pass both to control each independently.
• Tags. A CreateRecordTagInput with a title reuses an existing tag of the same title and color, or creates a new one (default color #4a9fff). A title with no match creates the tag.
• Custom fields. Each value is parsed by the field’s type; computed fields ignore supplied values. If the record’s workspace uses a name-formula field, the returned title reflects the computed name rather than the literal input.

Related

• List records
• Update a record
• Toggle completion
• Custom field values
• Tags