Update Record

Use the editRecord mutation to change a record’s built-in fields — title, description, due dates, color, cover, and tags — and use the setRecordCustomField mutation to write a value to one custom field on a record. Records are Record objects in the API and custom fields are CustomField objects.

editRecord returns the updated Record. setRecordCustomField returns Boolean! — it does not return the field value, so read it back with List Records when you need to confirm the result.

Request

Update a record’s title and description. todoId is the only required field; include only the fields you want to change.

mutation UpdateRecord {
  editRecord(
    input: {
      todoId: "todo_123"
      title: "Finalize Q3 proposal"
      html: "<p>Send to legal by Friday.</p>"
      text: "Send to legal by Friday."
    }
  ) {
    id
    title
    text
    html
  }
}

Parameters

EditRecordInput

All-day vs. timed dates

A due date is either a floating all-day date — the same calendar day for every viewer, RFC 5545 style — or a timed instant rendered per viewer using timezone. granularity picks which one you get:

mutation SetAllDayDueDate {
  editRecord(input: { todoId: "todo_123", duedAt: "2026-07-10T00:00:00Z", granularity: ALL_DAY }) {
    id
    duedAt
    dueDateGranularity
  }
}

CreateRecordTagInput

Each entry either references an existing tag by id, or creates/matches one by title (and optional color).

Color options

color accepts any of the record colors used in the app:

// Light theme
["#ffc2d4", "#ed8285", "#ffb55e", "#ffe885", "#ccf07d",
 "#91e38c", "#a1f7fa", "#91cfff", "#c29ee0", "#e8bd91"]

// Dark theme
["#ff8ebe", "#ff4b4b", "#ff9e4b", "#ffdc6b", "#b4e051",
 "#66d37e", "#4fd2ff", "#4a9fff", "#a17ee8", "#e89e64"]

Response

{
  "data": {
    "editRecord": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "title": "Finalize Q3 proposal",
      "text": "Send to legal by Friday.",
      "html": "<p>Send to legal by Friday.</p>"
    }
  }
}

Returns

editRecord returns the updated Record. Commonly selected fields:

Full example

Replace the tag set, move the record to a new list, set a position, and set a due-date range in one call.

mutation UpdateRecordFull {
  editRecord(
    input: {
      todoId: "todo_123"
      todoListId: "list_123"
      position: 65535
      color: "#91cfff"
      startedAt: "2026-06-01T09:00:00Z"
      duedAt: "2026-06-05T17:00:00Z"
      tags: [{ id: "tag_123" }, { title: "urgent", color: "#ff4b4b" }]
    }
  ) {
    id
    position
    color
    startedAt
    duedAt
    tags {
      id
      title
      color
    }
  }
}

Update custom fields

Use the setRecordCustomField mutation to write one custom field value on a record. Send the field-specific parameter for the field’s CustomFieldType — passing the wrong parameter is silently ignored, so match the table below. The mutation returns Boolean!.

mutation SetCustomFieldValue {
  setRecordCustomField(input: { todoId: "todo_123", customFieldId: "field_123", text: "Acme Corp" })
}

{ "data": { "setRecordCustomField": true } }

SetRecordCustomFieldInput

Examples by field type

Text, URL, email (TEXT_SINGLE, TEXT_MULTI, URL, EMAIL)

mutation {
  setRecordCustomField(
    input: { todoId: "todo_123", customFieldId: "field_123", text: "hello@acme.com" }
  )
}

Number, percent, rating (NUMBER, PERCENT, RATING) — number is a Float, unquoted.

mutation {
  setRecordCustomField(input: { todoId: "todo_123", customFieldId: "field_123", number: 42 })
}

Currency (CURRENCY) — amount plus a currency code. See Currency Field.

mutation {
  setRecordCustomField(
    input: { todoId: "todo_123", customFieldId: "field_123", number: 1500.50, currency: "USD" }
  )
}

Checkbox (CHECKBOX)

mutation {
  setRecordCustomField(input: { todoId: "todo_123", customFieldId: "field_123", checked: true })
}

Single-select (SELECT_SINGLE) — one option ID.

mutation {
  setRecordCustomField(
    input: { todoId: "todo_123", customFieldId: "field_123", customFieldOptionId: "option_123" }
  )
}

Multi-select (SELECT_MULTI) — the full set of selected option IDs.

mutation {
  setRecordCustomField(
    input: {
      todoId: "todo_123"
      customFieldId: "field_123"
      customFieldOptionIds: ["option_123", "option_456"]
    }
  )
}

Date (DATE) — endDate is the date; add startDate for a range, timezone for timezone-aware storage, and granularity: ALL_DAY for a floating all-day date. See Date Field.

mutation {
  setRecordCustomField(
    input: {
      todoId: "todo_123"
      customFieldId: "field_123"
      startDate: "2026-06-01T00:00:00Z"
      endDate: "2026-06-05T00:00:00Z"
      timezone: "America/New_York"
    }
  )
}

Phone (PHONE) — E.164 number in text with the matching regionCode.

mutation {
  setRecordCustomField(
    input: {
      todoId: "todo_123"
      customFieldId: "field_123"
      text: "+33642526644"
      regionCode: "FR"
    }
  )
}

Country (COUNTRY) — ISO 3166-1 alpha-2 codes.

mutation {
  setRecordCustomField(
    input: { todoId: "todo_123", customFieldId: "field_123", countryCodes: ["AF", "AL", "DZ"] }
  )
}

Location (LOCATION) — coordinates plus a display text.

mutation {
  setRecordCustomField(
    input: {
      todoId: "todo_123"
      customFieldId: "field_123"
      latitude: 42.2923323
      longitude: 12.1266212
      text: "Capranica, Italy"
    }
  )
}

Reference (REFERENCE) — the records to link. Replaces the existing link set. See Reference Field.

mutation {
  setRecordCustomField(
    input: {
      todoId: "todo_123"
      customFieldId: "field_123"
      customFieldReferenceTodoIds: ["todo_456", "todo_789"]
    }
  )
}

Assignee (ASSIGNEE) — the users assigned through the field. Replaces the existing assignees. See Assignee Field.

mutation {
  setRecordCustomField(
    input: {
      todoId: "todo_123"
      customFieldId: "field_123"
      assigneeUserIds: ["user_123", "user_456"]
    }
  )
}

Errors

editRecord:

setRecordCustomField:

Permissions

setRecordCustomField additionally honors per-field role permissions: if a custom field is marked non-editable for the caller’s role, the call is rejected with FORBIDDEN.

Related

• List Records — read records and custom field values back.
• Toggle Record Status — mark a record complete (done is not an editRecord field).
• Move Record to List — move a record between lists and workspaces.
• Tags — add or remove individual tags instead of replacing the whole set.
• Set Custom Field Values — the full per-type guide for setRecordCustomField.