Recurring Records

Use the createRepeatingRecord, updateRepeatingRecord, and deleteRepeatingRecord mutations to manage a repeating schedule on a record. The schedule is attached to an existing record, which acts as the template: each time the schedule fires, Blue copies the template into a target list. Records are Record objects in the API; lists are RecordList objects.

You control the cadence with a preset (DAILY, WEEKLY, MONTHLY, …) or a fully custom interval, choose when the schedule ends, and pick which elements (assignees, tags, custom fields, and more) carry over to each copy. All three mutations return Boolean.

Send these headers with every request. Company and project accept either an ID or a slug, and header names are case-insensitive.

blue-token-id: YOUR_TOKEN_ID
blue-token-secret: YOUR_TOKEN_SECRET
blue-org-id: YOUR_ORG_ID
blue-workspace-id: project_123

Request

Attach a daily repeating schedule to an existing record, copying assignees and tags to each new occurrence:

mutation CreateRecurringRecord {
  createRepeatingRecord(
    input: {
      todoId: "todo_123"
      todoListId: "list_123"
      type: DAILY
      fields: [ASSIGNEES, TAGS]
      from: "2026-06-01T09:00:00Z"
    }
  )
}

Parameters

CreateRepeatingRecordInput

UpdateRepeatingRecordInput

Same shape as CreateRepeatingRecordInput, plus repeatCounts.

RepeatingTodoTimeInput

RepeatingTodoIntervalInput

RepeatingTodoEndInput

RepeatingTodoRepeatType

RepeatingTodoAllowedField

RepeatingTodoAllowedField has no DUE_DATE member on purpose. These values copy the template’s own stored values, and a template never moves, so a copied due date would give every occurrence in the series the same fixed day. Use dueDateMode instead — it derives a date from each occurrence.

RepeatingTodoDueDateMode

OCCURRENCE_DATE reads the day the occurrence is created in the schedule’s own timezone (time.timezone), not in UTC. An evening schedule in a timezone behind UTC would otherwise be dated a day late.

dueOffsetDays must be a positive whole number. Any other value — zero, a negative, a fraction, or omitted — is read as no offset, so the occurrence is due on the day it is created. The date is always stored as an all-day date; the schedule’s time of day is when the work appears, not when it is due.

Existing schedules created before these fields were added carry no dueDateMode, which reads as NONE. Their behavior does not change.

updateRepeatingRecord creates a copy as soon as it succeeds, and that copy is dated by the same rule as every later occurrence. Send dueDateMode on an update as well as on a create, or the first record of the reconfigured series is the only undated one.

RepeatingTodoIntervalType

RepeatingTodoMonthType

RepeatingTodoEndType

Response

Each mutation returns a Boolean under the operation name.

{
  "data": {
    "createRepeatingRecord": true
  }
}

Returns

To read the active schedule’s target list back, select repeatingTodoList on the record. It is null when no schedule is set.

query RecurringTarget {
  recordQueries {
    todos(filter: { companyIds: ["company_123"], todoIds: ["todo_123"] }) {
      items {
        id
        title
        repeatingTodoList {
          id
          title
        }
      }
    }
  }
}

Full example

Repeat every 2 weeks on Monday and Wednesday, end after 10 occurrences, and copy every supported element:

mutation CreateRecurringRecordCustom {
  createRepeatingRecord(
    input: {
      todoId: "todo_123"
      todoListId: "list_123"
      type: CUSTOM
      fields: [ASSIGNEES, TAGS, CUSTOM_FIELDS, DESCRIPTION, CHECKLISTS, COMMENTS]
      from: "2026-06-01T09:00:00Z"
      interval: { count: 2, type: WEEKS, days: [Mon, Wed] }
      end: { type: AFTER, after: 10 }
    }
  )
}

Update a record’s schedule to repeat monthly by date, ending on a fixed date:

mutation UpdateRecurringRecord {
  updateRepeatingRecord(
    input: {
      todoId: "todo_123"
      todoListId: "list_123"
      type: CUSTOM
      fields: [ASSIGNEES, TAGS, DESCRIPTION]
      from: "2026-07-01T09:00:00Z"
      interval: { count: 1, type: MONTHS, month: BY_DD }
      end: { type: ON, on: "2026-12-31T23:59:59Z" }
      repeatCounts: 5
    }
  )
}

Remove a schedule from a record (the id is the record’s todoId):

mutation DeleteRecurringRecord {
  deleteRepeatingRecord(id: "todo_123")
}

How it works

• The schedule lives on the template record; the template itself is never altered when a copy is generated.
• Each occurrence is a fresh copy created in todoListId via the same mechanism as copying a record. The target list can be in the same workspace or a different one.
• fields controls exactly what carries over. Anything not listed is left off the copy.
• Preset cadences (DAILY, WEEKDAYS, WEEKLY, MONTHLY, YEARLY) need no interval. CUSTOM requires one — use interval.days to pin specific weekdays on WEEKS intervals, and interval.month to anchor MONTHS intervals to a date (BY_DD) or a weekday position (BY_DDDD).
• time applies uniformly across every cadence and interval type. Omit it to keep the legacy default of creating each occurrence at midnight UTC.
• time only controls when the copy is created (its createdAt) — it does not set a due date on the copy. fields has no due-date option today, so recurring copies are created without one.
• When updateRepeatingRecord generates a copy, it logs a REPEAT_TODO activity, records a todo action, notifies the copy’s assignees, and publishes the new record in real time. If creating the copy fails, the mutation clears the schedule to avoid a stuck state and returns false instead of throwing — always check the return value.

Errors

Permissions

Managing a recurring schedule requires edit-level access to the record. Only OWNER, ADMIN, and MEMBER access levels qualify; CLIENT, COMMENT_ONLY, and VIEW_ONLY cannot. A custom role with records disabled (isRecordsEnabled: false) is also denied, and the record’s workspace must be active (not archived).

Related

• Copy a record
• Update a record
• List records
• Assignees
• Tags