List cycles

GET https://app.improbable.work/api/v1/cycles

What this workspace has planned, so a caller can name a cycle. This is the endpoint an integration calls first: cycle ids are not the labels a person sees on screen, so guessing one is not a thing you can do.

Takes no parameters.

Request

curl -H "Authorization: Bearer imp_key_…" \
  https://app.improbable.work/api/v1/cycles

Response

{
"ok": true,
"data": [
  {
    "id": "2026-C03",
    "label": "Q3 2026",
    "short": "Q3",
    "ref": "2026/q3",
    "startsOn": "2026-07-01",
    "endsOn": "2026-09-30",
    "current": true,
    "path": "/api/v1/cycles/2026/q3/board"
  }
]
}

Fields on a cycle
Field	What it is
`id`	The canonical id — a year, a `C`, and a two-digit ordinal. This is what the board endpoint takes.
`label`	What the product calls this cycle on screen. For people, not for addresses.
`short`	The shorthand as the workspace wrote it — “Q3”, “Shipmas”. Also for people.
`ref`	The shorthand as an address: a year, a slash, and a slug. Two fields rather than one because slugging `short` yourself is a rule you should not have to reimplement.
`startsOn`	First day of the cycle, `YYYY-MM-DD`, or `null` for a cycle with no window.
`endsOn`	Last day, inclusive, or `null`.
`current`	True on the cycle running today. At most one row carries it — none, if the calendar has not been cut yet.
`path`	This cycle's board, already assembled against the mount this request arrived on.

Follow path rather than building the board URL yourself. The shorthand belongs to the workspace and they may rename it; a caller that assembled the address is a caller that breaks the day somebody renames a quarter.

What is listed, and what is not

This lists the cycles that have actually been cut — the rows the calendar holds — rather than every cycle the workspace's rhythm would eventually produce. That distinction matters to exactly one reader: a caller looking for an id it can pass back. An id that is not in this list may still answer on the board endpoint, but nothing here will name it for you.

The read never materialises a cycle. An unattended poll cannot cause this workspace's calendar to be cut, which is what keeps a read path from writing to the plan once a minute, forever.