Recurring Records

Recurring Records

Blue supports recurring records through the repeating todo system. You can attach a repeating schedule to any existing record, which will automatically create copies of that record at the specified interval. The createRepeatingTodo, updateRepeatingTodo, and deleteRepeatingTodo mutations manage recurring schedules on records.

Basic Example

Set up a simple daily recurring schedule on an existing record:

mutation CreateRecurringRecord {
  createRepeatingTodo(
    input: {
      todoId: "clm4n8qwx000008l0g4oxdqn7"
      todoListId: "clx9k2pvm000108l0abc12345"
      type: DAILY
      fields: [ASSIGNEES, TAGS]
      from: "2025-03-01T09:00:00Z"
    }
  )
}

Advanced Example

Create a custom recurring schedule that repeats every 2 weeks on Monday and Wednesday, ending after 10 occurrences, and copies all supported fields:

mutation CreateRecurringRecordAdvanced {
  createRepeatingTodo(
    input: {
      todoId: "clm4n8qwx000008l0g4oxdqn7"
      todoListId: "clx9k2pvm000108l0abc12345"
      type: CUSTOM
      fields: [ASSIGNEES, TAGS, CUSTOM_FIELDS, DESCRIPTION, CHECKLISTS, COMMENTS]
      from: "2025-03-01T09:00:00Z"
      interval: {
        count: 2
        type: WEEKS
        days: [Mon, Wed]
      }
      end: {
        type: AFTER
        after: 10
      }
    }
  )
}

Update an existing recurring schedule to repeat monthly by date, ending on a specific date:

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

Delete a recurring schedule from a record:

mutation DeleteRecurringRecord {
  deleteRepeatingTodo(id: "clm4n8qwx000008l0g4oxdqn7")
}

Input Parameters

CreateRepeatingTodoInput

UpdateRepeatingTodoInput

deleteRepeatingTodo

RepeatingTodoRepeatType Values

RepeatingTodoAllowedField Values

RepeatingTodoIntervalInput

RepeatingTodoIntervalType Values

RepeatingTodoMonthType Values

RepeatingTodoEndInput

RepeatingTodoEndType Values

Response Fields

All three mutations return a Boolean indicating success or failure:

The source record’s repeatingTodoList field will reflect the target todo list once a recurring schedule is active:

Required Permissions

The record must belong to an active (non-archived) workspace. The user must have edit-level permissions on the record.

Error Responses

TodoNotFoundError

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

When: The specified todoId or id does not exist or the user lacks access to the record.

UnauthorizedError

{
  "errors": [{
    "message": "You are not authorized.",
    "extensions": {
      "code": "UNAUTHORIZED"
    }
  }]
}

When: The user does not have sufficient permissions to manage recurring schedules on the record (requires OWNER, ADMIN, or MEMBER access).

Important Notes

How Recurring Records Work

• A recurring schedule is attached to an existing record – the record serves as the template for future copies
• When a recurrence triggers, a copy of the template record is created in the specified todo list
• The fields parameter controls which data is carried over to each new copy (assignees, tags, custom fields, description, checklists, comments)
• The template record itself is not modified when copies are created

Schedule Configuration

• Preset types (DAILY, WEEKDAYS, WEEKLY, MONTHLY, YEARLY) provide quick setup without needing the interval parameter
• CUSTOM type requires the interval parameter for fine-grained control
• Use interval.days to specify which days of the week (e.g., Mon, Wed, Fri) when the interval type is WEEKS
• Use interval.month to control whether monthly repetition tracks the date (BY_DD) or the weekday position (BY_DDDD)
• The end parameter is optional – omitting it means the schedule repeats indefinitely (NEVER)

Side Effects

When a recurring copy is created via updateRepeatingTodo, it triggers:

• Activity log entry with category REPEAT_TODO
• Notification delivery to assigned users
• Real-time publishing of the new record to connected clients
• Todo action history entry

Error Handling

• If updateRepeatingTodo encounters an error while creating the copy, it automatically cleans up the recurring schedule to prevent stuck states and returns false
• Always check the return value to confirm the operation succeeded

Related Endpoints

• Create a Record: Use createTodo to create the initial record before setting up recurrence
• List Records: Use todoQueries.todos to query records including recurring copies
• Copy Record: The recurring system uses the same copy mechanism as copyTodo