A recurring series creates one ordinary ticket per occurrence (see Recurring tickets). These operations manage the series; the tickets it creates travel through the ticket operations, where GET /api/w/{slug}/tickets?recurrenceId=… lists them and every TicketSummary carries recurrence: { id, occurrenceOn } or null. Every operation here is for workspace users; a client user, elevated or not, gets 403 forbidden with details.reason: "workspace_users_only". A series in a project the token may not reach answers 404 not_found.
Shapes
RecurrenceRule is one of:
frequency |
Fields | Meaning |
|---|---|---|
weekly |
interval: 1, 2, 3, or 4 |
Every interval weeks on the weekday of startDate |
monthly |
interval: 1, 2, 3, or 6; ordinal: 1, 2, 3, 4, "last", or omitted |
Every interval months on startDate's day of the month (clamped to shorter months), or, with ordinal, on that position of startDate's weekday |
yearly |
interval: 1 |
Every year on startDate's month and day (29 February → 28 February) |
RecurrenceDuration is { "amount": integer ≥ 1, "unit": "day" | "week" | "month" | "year" }. The due date of an occurrence is start + length − 1 day. The length may not exceed the interval: weekly allows up to interval weeks or 7 × interval days; monthly up to interval months, 4 × interval weeks, or 28 × interval days; yearly up to 1 year, 12 months, 52 weeks, or 365 days.
Recurrence (a series): id, project (id, key, name), owner and assignee (id, name, clientName, or null), title, description, kind and priority (id, key, name), parent (id, humanId, title, or null; only when the caller may see it), labels[], estimateMinutes (null when none or for callers who may not see estimates), rule, duration, startDate (the anchor), leadDays, nextOccurrenceOn (the first occurrence without a ticket), endsOn or null, status (active, paused, ended, archived), lastError (why the last run paused or degraded an occurrence, or null), pausedAt, archivedAt, createdAt, updatedAt, permissions.edit.
lastError values: owner_missing, project_create_forbidden, or another refusal reason from ticket creation (the series is paused); assignee_dropped or parent_dropped (the latest ticket was created without that field; the series continues).
GET /api/w/{slug}/recurrences
The series the caller may see, soonest next occurrence first. Token: yes, read. Archived series are left out unless status=archived.
| Query parameter | Type | Meaning |
|---|---|---|
projectId |
uuid | Only this project |
status |
active, paused, ended, or archived |
Only series in that state |
Response 200 (RecurrenceList): { "recurrences": Recurrence[] }.
POST /api/w/{slug}/recurrences
Create a series and its first occurrence. Token: yes, write. The caller must be a workspace user who may start tickets on the project; the caller becomes the owner.
Body field (CreateRecurrence) |
Type | Required | Validation |
|---|---|---|---|
projectId |
uuid | yes | A project that is not archived |
title |
string | yes | 1–200 characters, trimmed |
description |
string | no | Markdown, at most 50 000 characters |
kindId, priorityId |
uuid | no | Defaults: the first kind, the workspace default priority |
assigneeId |
uuid or null | no | A workspace user or an elevated client user on the project |
labelIds |
uuid[] | no | At most 20 |
estimateMinutes |
integer ≥ 0 or null | no | Only while time tracking is on |
parentId |
uuid or null | no | A visible, non-archived ticket that is not itself a recurring occurrence |
rule |
RecurrenceRule |
yes | See Shapes |
duration |
RecurrenceDuration |
yes | At most the interval |
startDate |
YYYY-MM-DD |
yes | The first occurrence; today or later in the workspace time zone; must hold ordinal if set |
leadDays |
integer 0–90 | no | Default 14 |
endsOn |
YYYY-MM-DD or null |
no | Not before startDate |
Request
curl -X POST https://saq.no/api/w/acme/recurrences \
-H 'Authorization: Bearer saq_YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"projectId": "01924c3e-6b2a-7d11-9d0e-3a1f4b5c6d7e",
"title": "Monthly invoice run",
"rule": { "frequency": "monthly", "interval": 1, "ordinal": "last" },
"duration": { "amount": 3, "unit": "day" },
"startDate": "2026-10-30",
"leadDays": 7,
"assigneeId": "01924c3e-0004-7000-8000-000000000001",
"estimateMinutes": 240
}'
Response 201 (CreateRecurrenceResult): { "recurrence": Recurrence, "ticket": TicketSummary }. The ticket is the first occurrence, with startDate equal to the anchor and recurrence.occurrenceOn set. Any further occurrence already inside the lead window is created as well.
| Error | Status | details.reason |
|---|---|---|
invalid |
400 | rule_interval, rule_ordinal, rule_frequency, anchor_ordinal, anchor_past, duration_amount, duration_exceeds_interval, lead_days, ends_before_start, date_format, title_required, unknown_kind, unknown_priority, unknown_label, unknown_person, assignee_ineligible, recurring_parent, estimate_format, and the reasons of ticket creation |
forbidden |
403 | workspace_users_only, project_create_forbidden, missing scope |
conflict |
409 | project_archived, parent_archived, recurrence_limit (200 non-archived series) |
not_found |
404 | unknown_project, or a parent the caller may not see |
GET /api/w/{slug}/recurrences/{id}
One series with its upcoming occurrences and tickets. Token: yes, read.
Response 200 (RecurrenceDetail): a Recurrence plus upcoming[] (startDate, dueDate for the next six occurrences from nextOccurrenceOn; empty for ended and archived series) and tickets[] (TicketSummary, the tickets created from the series that the caller may see, newest activity first, at most 50; use GET /tickets?recurrenceId= for more).
PATCH /api/w/{slug}/recurrences/{id}
Change the series. Token: yes, write. Only the owner, a Project manager on the project, or an Owner or Admin. Every field is optional; send only what changes. Changes apply to occurrences not created yet.
Body field (UpdateRecurrence) |
Notes |
|---|---|
title, description, kindId, priorityId, assigneeId, labelIds, estimateMinutes, parentId |
As on create |
rule, startDate |
A new grid: nextOccurrenceOn becomes the first date on or after today (and on or after startDate) the rule produces; dates that already have a ticket are skipped. startDate must be today or later. |
duration, leadDays, endsOn |
Validated against the (new) rule |
ownerId |
Hand the series to another workspace user; later tickets are created as them |
Response 200 (Recurrence). lastError is cleared.
| Error | Status | details.reason |
|---|---|---|
invalid |
400 | As on create, plus owner_not_member |
forbidden |
403 | Not the owner, a Project manager on the project, or an Owner/Admin |
conflict |
409 | series_archived |
not_found |
404 | Unknown or not reachable |
POST /api/w/{slug}/recurrences/{id}/pause
Stop creating tickets until resumed. Token: no (browser session only). Same permission as PATCH. Response 200 (Recurrence) with status: "paused". 409 series_archived on an archived series.
POST /api/w/{slug}/recurrences/{id}/resume
Continue a paused series. Token: no (browser session only). nextOccurrenceOn moves to the first occurrence on or after today; the occurrences missed while paused are not created. lastError is cleared. Response 200 (Recurrence). 409 series_archived on an archived series.
POST /api/w/{slug}/recurrences/{id}/archive
Close the series for good. Token: no (browser session only). Its tickets stay; it leaves the default list and can no longer be edited, paused, or resumed. Response 200 (Recurrence) with status: "archived".