Recurring tickets

List, create, read, update, pause, resume, and archive recurring-ticket series through the SAQ REST API, with the rule and length shapes, every field, and every error.

Written for
integration-developer
Roles
owner, admin, member, project-manager, agent
Requires
API token with read scope for GET, write scope to create and update; workspace users only; Pause, resume, and archive: browser session only
Feature
tickets

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".