Docs · Using Iskue

Plans, goals, documentation spaces and wiki

Four related features sit above individual projects. Plans draw a cross-project timeline with dependencies, rolled-up epics and team capacity, and let you stage date changes in a scenario before committing them. Goals are organisation-level outcomes with linked tickets and a computed progress, aligned to strategic themes. Documentation spaces are organisation-wide page trees with revisions, comments, restriction and search. The project wiki is the same page engine scoped to one project.

Plans

A plan (/plans) is a named selection of projects, optionally narrowed by a TQL scope (tqlScope, applied on top of the projects), with a sharing scope of PRIVATE or ALL_USERS. Only the owner can edit it; others with access see it read-only (canEdit in the DTO).

curl -s -X POST $ISKUE_URL/api/v1/plans -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"Q4 delivery","shared":"ALL_USERS","tqlScope":"type IN (Epic, Story)","projectIds":["<uuid>","<uuid>"]}'

curl -s "$ISKUE_URL/api/v1/plans/<plan-uuid>/timeline" -H "Authorization: Bearer $TOKEN"

The timeline

GET …/timeline returns rangeStart/rangeEnd and four collections. Items are tickets with a bar (start, end, scheduled), their hierarchy (level, parentTicketId), progress (estimate, totalPoints, donePoints, unassigned) and grouping fields (statusCategory, priority, assigneeName, teamName); epics and other parents get rolled-up dates from their children, and items on the longest dependency chain are flagged critical. Edges are BLOCKS links between items, with conflict set when a blocker ends after the item it blocks. Markers are version release dates from the plan's projects. Capacity bands show, per team and sprint, the configured capacity against the points scheduled into it (see the sprint capacity endpoint on the scaled-agile page).

Scenarios: what-if before commit

A scenario stages date changes without touching live tickets. Create one under a plan, set a startDate and/or dueDate per ticket (a null side keeps the live value), view the timeline with ?scenario= to compare, and commit when the plan is agreed: each staged change is applied through the normal ticket update — screen rules, permissions and changelog included — one ticket at a time, failures are collected rather than aborting the run, and if every change applied the scenario is deleted. Only the plan's owner can commit, and every commit is written to the configuration audit log (scenario X committed (N applied)).

P=$ISKUE_URL/api/v1/plans/<plan-uuid>
curl -s -X POST $P/scenarios -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"name":"Slip payments by two weeks"}'
curl -s -X PUT  $P/scenarios/<scenario-uuid>/changes/<ticket-uuid> -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"startDate":"2026-11-02","dueDate":"2026-11-20"}'
curl -s "$P/timeline?scenario=<scenario-uuid>" -H "Authorization: Bearer $TOKEN"      # preview
curl -s -X POST $P/scenarios/<scenario-uuid>/commit -H "Authorization: Bearer $TOKEN"
# → {"applied":7,"failed":[{"ticketKey":"CORE-12","error":"Field 'Due date' is read-only on this screen"}]}

Goals

Goals (/goals) are organisation-wide outcomes: a name (≤ 200), description (≤ 2 000), optional targetDate, a state of ON_TRACK (default), AT_RISK or DONE, and an optional strategic theme. Progress is never typed in — it is computed from the linked tickets: a ticket counts as done when its status category is DONE, and the DTO returns totalTickets/doneTickets and totalPoints/donePoints plus the linked keys. Reads need only a login; creating, editing, deleting and linking are admin operations. There are no goal owners, periods or parent goals, and only tickets (not projects) can be linked.

Documentation spaces

Documentation spaces (/docs, /docs/:spaceKey) are organisation-wide page trees, independent of any project. Administrators create a space with a key (≤ 20), name (≤ 120) and description; an open space can be read and edited by any signed-in user, while a restricted space is visible only to its members — READER or EDITOR — and to admins. Pages hold Markdown (body ≤ 200 000 characters, title ≤ 200) and nest through parentId (re-parent with parentId / clearParent on save).

Project wiki

Every project has a wiki at /projects/:key/wiki on the same page engine — tree of Markdown pages, revisions with restore, comments — under /api/v1/projects/{projectKey}/wiki with the same page, revision and comment paths as above. Access follows project membership: members read, write members author, project admins delete. The wiki has no search endpoint of its own; its pages are found through /api/v1/docs/search (which needs the Professional edition) or by browsing.

W=$ISKUE_URL/api/v1/projects/CORE/wiki
curl -s $W/<page-uuid>/revisions -H "Authorization: Bearer $TOKEN"
# → [{"rev":3,"title":"Release checklist","updatedBy":"Alice","createdAt":"…"}, {"rev":2,…}, {"rev":1,…}]
curl -s -X POST $W/<page-uuid>/revisions/2/restore -H "Authorization: Bearer $TOKEN"   # rev 2 becomes the current text (as a new revision)

Feature overview: Plan across projects, aim at goals, write it down