Recurring Rule
A recurrence rule anchored to a task: while the rule is live, Nifty keeps spawning fresh copies of that task.
type decides which configuration fields are legal, and the combinations are enforced — a mismatch is a 400, and even an explicit null counts as sending the field:
type | required | must be omitted |
|---|---|---|
date | cron or schedule | triggerStatusId |
status | triggerStatusId | cron, schedule |
completion | — | cron, schedule, triggerStatusId |
type and sourceTaskId are fixed once the rule exists; everything else is editable. Only task-anchored rules are on this surface — rules attached to lists or check-ins are managed elsewhere and never appear here, so a list you know recurs may show no rule at all.
List Recurring Rules
List recurringRules. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 4 fields. Ordered by createdAt unless you pass sort.
Required scope: recurring-rules:read
query Parameters
projectIdRestrict the list to one project. Omit to list recurringRules across every project you can access.
sortField to sort by. Prefix with - for descending (-createdAt); a createdAt:desc / createdAt:asc suffix works too, but never both markers at once. Default: createdAt. Listing without projectId orders by -updatedAt instead.
cursorOpaque cursor for the next page (the envelope nextCursor).
limitItems per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow nextCursor instead of assuming one page held everything.
includeTotalWhen true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination.
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
type[eq]Filter where type equals.
type[in]Filter where type is one of (comma-separated list).
sourceTaskId[eq]Filter where sourceTaskId equals.
sourceTaskId[in]Filter where sourceTaskId is one of (comma-separated list).
nextRecurrenceAt[gt]Filter where nextRecurrenceAt is greater than.
nextRecurrenceAt[gte]Filter where nextRecurrenceAt is greater than or equal to.
nextRecurrenceAt[lt]Filter where nextRecurrenceAt is less than.
nextRecurrenceAt[lte]Filter where nextRecurrenceAt is less than or equal to.
createdAt[gt]Filter where createdAt is greater than.
createdAt[gte]Filter where createdAt is greater than or equal to.
createdAt[lt]Filter where createdAt is less than.
createdAt[lte]Filter where createdAt is less than or equal to.
List Recurring Rules › Responses
OK
The page of results.
totalTotal rows matching the query (across pages).
limithasMorenextCursorOpaque cursor for the next page; null on the last page.
Create Recurring Rule
Create a Recurring Rule. Server-assigned fields are ignored if sent.
Required scope: recurring-rules:write
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Create Recurring Rule › Request Body
typeWhat makes this rule fire. date — a cron or schedule timetable. status — the anchored task moving into triggerStatusId. completion — the anchored task being completed. Set once when the rule is created; it cannot be changed afterwards.
sourceTaskIdThe task this rule is anchored to. Required when the rule is created, and server-managed afterwards: each time the rule spawns, the engine repoints it at the newly created task, and it becomes null once end has passed — so a read can return a different task than you sent, or none.
cronStandard 5-field cron for date rules — minute, hour, day-of-month, month, day-of-week (no seconds field). It must resolve to a SINGLE minute and a SINGLE hour: ranges, lists and steps in those two positions are rejected. Occurrences are computed in the timezone reported by tzIana.
Recurrence timetable for date rules, as an alternative to cron. Send one or the other — if both are present, cron wins and schedule is ignored.
cloneFieldsRestricts what each spawned task copies from the anchored task. Omit it (or send null) and everything is copied — this is an allowlist, not a set of extras. Allowed entries: description, embedUrl, startAt, dueAt, labels, fields (custom-field values), subtasks.
Shifts dates on each spawned task, relative to the date it is spawned on: [{ "type": "dueAt", "offset": 3 }] gives every new task a due date 3 days out. offset is a whole number of days and may be negative.
endWhen the recurrence stops (ISO 8601 timestamp). It must fall after the next occurrence. Once passed, the rule stops spawning: nextRecurrenceAt and sourceTaskId are both cleared.
weekParityThins a date recurrence out to every other ISO week. off (the default) fires every matching week; skipEvenWeeks fires only in odd ISO weeks; skipOddWeeks fires only in even ones.
recurOnDateOnlyFor date rules: when true the rule fires strictly on its timetable, instead of also spawning early if the anchored task is completed ahead of schedule.
triggerStatusIdFor status rules: the status whose arrival fires the rule — the next task is spawned when the anchored task moves into it. Required on a status rule and rejected on any other type. Set once when the rule is created.
Create Recurring Rule › Responses
Created
idUnique identifier for this resource.
createdAtCreation timestamp.
typeWhat makes this rule fire. date — a cron or schedule timetable. status — the anchored task moving into triggerStatusId. completion — the anchored task being completed. Set once when the rule is created; it cannot be changed afterwards.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
cronStandard 5-field cron for date rules — minute, hour, day-of-month, month, day-of-week (no seconds field). It must resolve to a SINGLE minute and a SINGLE hour: ranges, lists and steps in those two positions are rejected. Occurrences are computed in the timezone reported by tzIana.
Recurrence timetable for date rules, as an alternative to cron. Send one or the other — if both are present, cron wins and schedule is ignored.
Restricts what each spawned task copies from the anchored task. Omit it (or send null) and everything is copied — this is an allowlist, not a set of extras. Allowed entries: description, embedUrl, startAt, dueAt, labels, fields (custom-field values), subtasks.
Shifts dates on each spawned task, relative to the date it is spawned on: [{ "type": "dueAt", "offset": 3 }] gives every new task a due date 3 days out. offset is a whole number of days and may be negative.
endWhen the recurrence stops (ISO 8601 timestamp). It must fall after the next occurrence. Once passed, the rule stops spawning: nextRecurrenceAt and sourceTaskId are both cleared.
weekParityThins a date recurrence out to every other ISO week. off (the default) fires every matching week; skipEvenWeeks fires only in odd ISO weeks; skipOddWeeks fires only in even ones.
recurOnDateOnlyFor date rules: when true the rule fires strictly on its timetable, instead of also spawning early if the anchored task is completed ahead of schedule.
triggerStatusIdFor status rules: the status whose arrival fires the rule — the next task is spawned when the anchored task moves into it. Required on a status rule and rejected on any other type. Set once when the rule is created.
onCompleteRead-only: true on completion rules, false on every other type. Derived from type — it is not part of the create body.
sourceTaskIdThe task this rule is anchored to. Required when the rule is created, and server-managed afterwards: each time the rule spawns, the engine repoints it at the newly created task, and it becomes null once end has passed — so a read can return a different task than you sent, or none.
nextRecurrenceAtNext occurrence (server-computed from cron/schedule + the author timezone snapshot). THE engine cursor — the nifty-crons poll selects rules by it; NEVER client-writable (a stale/forged value kills or force-spawns the rule).
targetStatusIdThe status each spawned task is placed into — taken from the anchored task when the rule was created.
tzIanaThe author's IANA timezone (e.g. 'America/New_York'), snapshotted server-side at create/update — the timezone the engine spawns occurrences in. Read-only display field; never client-writable.
tzOffsetThe author's UTC offset in MINUTES EAST of UTC at the time the rule was saved, matching tzIana (New York in winter is -300). Recorded by the server; never writable.
The related Task, present only when you pass ?expand=sourceTask.
The related Status, present only when you pass ?expand=targetStatus.
The related Actor, present only when you pass ?expand=createdByActor.
The related Actor, present only when you pass ?expand=updatedByActor.
Get Recurring Rule
Retrieve a single Recurring Rule by id.
Required scope: recurring-rules:read
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Recurring Rule.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Get Recurring Rule › Responses
OK
idUnique identifier for this resource.
createdAtCreation timestamp.
typeWhat makes this rule fire. date — a cron or schedule timetable. status — the anchored task moving into triggerStatusId. completion — the anchored task being completed. Set once when the rule is created; it cannot be changed afterwards.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
cronStandard 5-field cron for date rules — minute, hour, day-of-month, month, day-of-week (no seconds field). It must resolve to a SINGLE minute and a SINGLE hour: ranges, lists and steps in those two positions are rejected. Occurrences are computed in the timezone reported by tzIana.
Recurrence timetable for date rules, as an alternative to cron. Send one or the other — if both are present, cron wins and schedule is ignored.
Restricts what each spawned task copies from the anchored task. Omit it (or send null) and everything is copied — this is an allowlist, not a set of extras. Allowed entries: description, embedUrl, startAt, dueAt, labels, fields (custom-field values), subtasks.
Shifts dates on each spawned task, relative to the date it is spawned on: [{ "type": "dueAt", "offset": 3 }] gives every new task a due date 3 days out. offset is a whole number of days and may be negative.
endWhen the recurrence stops (ISO 8601 timestamp). It must fall after the next occurrence. Once passed, the rule stops spawning: nextRecurrenceAt and sourceTaskId are both cleared.
weekParityThins a date recurrence out to every other ISO week. off (the default) fires every matching week; skipEvenWeeks fires only in odd ISO weeks; skipOddWeeks fires only in even ones.
recurOnDateOnlyFor date rules: when true the rule fires strictly on its timetable, instead of also spawning early if the anchored task is completed ahead of schedule.
triggerStatusIdFor status rules: the status whose arrival fires the rule — the next task is spawned when the anchored task moves into it. Required on a status rule and rejected on any other type. Set once when the rule is created.
onCompleteRead-only: true on completion rules, false on every other type. Derived from type — it is not part of the create body.
sourceTaskIdThe task this rule is anchored to. Required when the rule is created, and server-managed afterwards: each time the rule spawns, the engine repoints it at the newly created task, and it becomes null once end has passed — so a read can return a different task than you sent, or none.
nextRecurrenceAtNext occurrence (server-computed from cron/schedule + the author timezone snapshot). THE engine cursor — the nifty-crons poll selects rules by it; NEVER client-writable (a stale/forged value kills or force-spawns the rule).
targetStatusIdThe status each spawned task is placed into — taken from the anchored task when the rule was created.
tzIanaThe author's IANA timezone (e.g. 'America/New_York'), snapshotted server-side at create/update — the timezone the engine spawns occurrences in. Read-only display field; never client-writable.
tzOffsetThe author's UTC offset in MINUTES EAST of UTC at the time the rule was saved, matching tzIana (New York in winter is -300). Recorded by the server; never writable.
The related Task, present only when you pass ?expand=sourceTask.
The related Status, present only when you pass ?expand=targetStatus.
The related Actor, present only when you pass ?expand=createdByActor.
The related Actor, present only when you pass ?expand=updatedByActor.
Delete Recurring Rule
Permanently delete this Recurring Rule. This cannot be undone.
Required scope: recurring-rules:delete
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Recurring Rule.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Delete Recurring Rule › Responses
No Content
Update Recurring Rule
Partially update a Recurring Rule. Only the fields you send are changed.
Required scope: recurring-rules:write
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Recurring Rule.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Update Recurring Rule › Request Body
cronStandard 5-field cron for date rules — minute, hour, day-of-month, month, day-of-week (no seconds field). It must resolve to a SINGLE minute and a SINGLE hour: ranges, lists and steps in those two positions are rejected. Occurrences are computed in the timezone reported by tzIana.
Recurrence timetable for date rules, as an alternative to cron. Send one or the other — if both are present, cron wins and schedule is ignored.
cloneFieldsRestricts what each spawned task copies from the anchored task. Omit it (or send null) and everything is copied — this is an allowlist, not a set of extras. Allowed entries: description, embedUrl, startAt, dueAt, labels, fields (custom-field values), subtasks.
Shifts dates on each spawned task, relative to the date it is spawned on: [{ "type": "dueAt", "offset": 3 }] gives every new task a due date 3 days out. offset is a whole number of days and may be negative.
endWhen the recurrence stops (ISO 8601 timestamp). It must fall after the next occurrence. Once passed, the rule stops spawning: nextRecurrenceAt and sourceTaskId are both cleared.
weekParityThins a date recurrence out to every other ISO week. off (the default) fires every matching week; skipEvenWeeks fires only in odd ISO weeks; skipOddWeeks fires only in even ones.
recurOnDateOnlyFor date rules: when true the rule fires strictly on its timetable, instead of also spawning early if the anchored task is completed ahead of schedule.
expectedUpdatedAtOptional concurrency guard: the updatedAt you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh updatedAt.
Update Recurring Rule › Responses
OK
idUnique identifier for this resource.
createdAtCreation timestamp.
typeWhat makes this rule fire. date — a cron or schedule timetable. status — the anchored task moving into triggerStatusId. completion — the anchored task being completed. Set once when the rule is created; it cannot be changed afterwards.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
cronStandard 5-field cron for date rules — minute, hour, day-of-month, month, day-of-week (no seconds field). It must resolve to a SINGLE minute and a SINGLE hour: ranges, lists and steps in those two positions are rejected. Occurrences are computed in the timezone reported by tzIana.
Recurrence timetable for date rules, as an alternative to cron. Send one or the other — if both are present, cron wins and schedule is ignored.
Restricts what each spawned task copies from the anchored task. Omit it (or send null) and everything is copied — this is an allowlist, not a set of extras. Allowed entries: description, embedUrl, startAt, dueAt, labels, fields (custom-field values), subtasks.
Shifts dates on each spawned task, relative to the date it is spawned on: [{ "type": "dueAt", "offset": 3 }] gives every new task a due date 3 days out. offset is a whole number of days and may be negative.
endWhen the recurrence stops (ISO 8601 timestamp). It must fall after the next occurrence. Once passed, the rule stops spawning: nextRecurrenceAt and sourceTaskId are both cleared.
weekParityThins a date recurrence out to every other ISO week. off (the default) fires every matching week; skipEvenWeeks fires only in odd ISO weeks; skipOddWeeks fires only in even ones.
recurOnDateOnlyFor date rules: when true the rule fires strictly on its timetable, instead of also spawning early if the anchored task is completed ahead of schedule.
triggerStatusIdFor status rules: the status whose arrival fires the rule — the next task is spawned when the anchored task moves into it. Required on a status rule and rejected on any other type. Set once when the rule is created.
onCompleteRead-only: true on completion rules, false on every other type. Derived from type — it is not part of the create body.
sourceTaskIdThe task this rule is anchored to. Required when the rule is created, and server-managed afterwards: each time the rule spawns, the engine repoints it at the newly created task, and it becomes null once end has passed — so a read can return a different task than you sent, or none.
nextRecurrenceAtNext occurrence (server-computed from cron/schedule + the author timezone snapshot). THE engine cursor — the nifty-crons poll selects rules by it; NEVER client-writable (a stale/forged value kills or force-spawns the rule).
targetStatusIdThe status each spawned task is placed into — taken from the anchored task when the rule was created.
tzIanaThe author's IANA timezone (e.g. 'America/New_York'), snapshotted server-side at create/update — the timezone the engine spawns occurrences in. Read-only display field; never client-writable.
tzOffsetThe author's UTC offset in MINUTES EAST of UTC at the time the rule was saved, matching tzIana (New York in winter is -300). Recorded by the server; never writable.
The related Task, present only when you pass ?expand=sourceTask.
The related Status, present only when you pass ?expand=targetStatus.
The related Actor, present only when you pass ?expand=createdByActor.
The related Actor, present only when you pass ?expand=updatedByActor.