Boards and My work

Read the board with its per-column pages and the personal My work lists through the SAQ REST API.

Written for
integration-developer
Roles
owner, admin, member, elevated-client-user, agent
Requires
API token with read scope
Feature
tickets

The board is the ticket list grouped by state, one column per state in workflow order. In an open column the order is priority first (highest at the top), then most recent activity; in a closed column it is most recently closed first. Archived tickets are never on a board. All three operations return TicketSummary items, described on Tickets. A person's saved boards (the app's named column and filter sets) are browser-only and listed under Session-only operations; through the API, read a saved board's contents by sending its filters and stateIds to this operation.

GET /api/w/{slug}/board

The board for the whole workspace or one project. Token: yes, read. The query accepts every filter of GET /tickets (projectId, stateIds, kindIds, excludeKindIds, labelIds, priorityIds, stateCategory, assigneeId, reporterId, viewerId, billingClientId, billingPolicy, due, parentId, q, queue) plus:

Query parameter Type Meaning
limit integer 1–50 Cards per column; default 50. The app asks for 20.
closedWithinDays integer 1–365 Closed columns contain only tickets that entered a closed state within this many days; the rest are counted in older. Open columns are never windowed. Without it, closed columns are complete. The app asks for 7.
stateIds uuids Only these columns are returned, in workflow order; the others are left out entirely.

cursor is ignored here.

Request

curl "https://saq.no/api/w/acme/board?projectId=01924c3e-6b2a-7d11-9d0e-3a1f4b5c6d7e&limit=20" \
  -H 'Authorization: Bearer saq_YOUR_TOKEN'

Response 200 (Board)

{
  "columns": [
    {
      "state": {
        "id": "01924c3e-0002-7000-8000-000000000001",
        "key": "backlog",
        "name": "Backlog",
        "category": "open"
      },
      "total": 37,
      "older": 0,
      "tickets": [],
      "nextCursor": "MHwyMDI2LTA5LTE5VDEwOjE1OjAwLjAwMFp8MDE5MjRjM2U"
    },
    {
      "state": {
        "id": "01924c3e-0002-7000-8000-000000000005",
        "key": "done",
        "name": "Done",
        "category": "closed"
      },
      "total": 2,
      "older": 118,
      "tickets": [],
      "nextCursor": null
    }
  ]
}
Field Type Meaning
columns[].state object id, key, name, category (open or closed)
columns[].total integer Tickets in the column after filtering and, on a closed column with closedWithinDays, within the window; includes the cards beyond the page shown
columns[].older integer Closed tickets closedWithinDays left out of the column; 0 on open columns and without the parameter
columns[].tickets[] TicketSummary The first page, in board order
columns[].nextCursor string or null Cursor for GET /board/{stateId}; null when the column is complete
Error Status When
invalid 400 Bad query value
forbidden 403 Missing read scope

GET /api/w/{slug}/board/{stateId}

The next page of one column, in board order. Token: yes, read. Send the same filters as for the board, the same closedWithinDays if you used one, plus cursor from that column's nextCursor and an optional limit. A cursor belongs to the column it came from: an open column's cursor is refused on a closed column and the other way round.

curl "https://saq.no/api/w/acme/board/01924c3e-0002-7000-8000-000000000001?projectId=01924c3e-6b2a-7d11-9d0e-3a1f4b5c6d7e&cursor=MHwyMDI2LTA5LTE5VDEwOjE1OjAwLjAwMFp8MDE5MjRjM2U" \
  -H 'Authorization: Bearer saq_YOUR_TOKEN'

Response 200 (TicketList): { "items": TicketSummary[], "nextCursor": string | null }.

Error Status When
invalid 400 details.reason: "bad_cursor", or stateId is not a UUID

GET /api/w/{slug}/my

The caller's personal lists. Token: yes, read. No parameters.

curl https://saq.no/api/w/acme/my \
  -H 'Authorization: Bearer saq_YOUR_TOKEN'

Response 200 (MyWork)

{
  "assigned": [],
  "reported": [],
  "watching": [],
  "dueSoon": []
}
Field Meaning
assigned Open tickets assigned to the caller
reported Tickets the caller started
watching Tickets the caller is a viewer on
dueSoon Visible tickets with a due date coming up

Each list holds TicketSummary items. For an agent account, assigned and reported refer to the agent itself.