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 with one or more database homes within workspaces (Workspace). A database record does not need a list (RecordList).

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.

For explicit database creation, singleton reads, field writes, files, color, delete, and restore, see Database Records. The createRecord examples below use the workspace/list contract.

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

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",
      "rank": "a0V"
    }
  }
}

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

• Placement. Send previousId/nextId to insert a record directly between two existing records (the recommended input). Otherwise placement decides: the default (no placement) and TOP insert above the current first record; BOTTOM inserts after the last.
• 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.

Create a record in a table

createRecordInDatabase is the generic path for creating a record in an explicit table — the route an AI agent, MCP tool, or REST/SDK caller uses. It targets a table (RecordDatabase) directly, so it also works on tables that have no list, and the workspace is part of the input: it must match the workspace in the blue-workspace-id header.

Request

mutation CreateRecordInTable {
  createRecordInDatabase(
    input: {
      workspaceId: "project_123"
      databaseId: "table_123"
      title: "Draft launch plan"
      fieldValues: [{ fieldId: "field_123", kind: "text", value: { text: "In progress" } }]
    }
  ) {
    recordId
    databaseId
    created
    joined
    rank
  }
}

CreateRecordInDatabaseInput

Response

Authorization and the creation form

• You need record-creation access in the target workspace: OWNER, ADMIN, or MEMBER; a custom role additionally needs edit access, the create-records permission, and records enabled. An organization-level OWNER/ADMIN bypasses a restricted role.
• The table must be live and have a text field configured to name records.
• If the table’s creation form marks fields as required, the call must supply them in fieldValues; defaults for other form fields are applied automatically. Otherwise the call is rejected with BAD_USER_INPUT.
• Sending groupOptionId requires the table to have a grouping field, and the option must be live.

Errors

Related

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