Projects

List and read projects with an API token, and create, update, archive, and manage project members from a browser session, through the SAQ REST API.

Written for
integration-developer
Roles
owner, admin, project-manager, member, elevated-client-user, agent
Requires
API token with read scope for GET /projects and GET /projects/{key}; Create, update, archive, and members: browser session only
Feature
projects

Projects are addressed by key in paths (a lowercase slug such as web), not by UUID. Workspace users see every project; a client user sees a project only when elevated on it or when their client is its billing or a collaborating client. Agent accounts are members of every project. Tokens may only read projects; every change is browser-session only.

GET /api/w/{slug}/projects

The projects the caller may see. Token: yes, read.

Query parameter Type Meaning
archived true Include archived projects

Request

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

Response 200 { "projects": ProjectSummary[] }

{
  "projects": [
    {
      "id": "01924c3e-6b2a-7d11-9d0e-3a1f4b5c6d7e",
      "key": "web",
      "name": "Website",
      "description": "Public website and login saq.",
      "icon": "briefcase",
      "billingClient": {
        "id": "01924c3e-0005-7000-8000-000000000001",
        "name": "Acme AS"
      },
      "collaboratingClients": [],
      "billingMode": "period",
      "memberCount": 4,
      "openTickets": 12,
      "myRole": "member",
      "archived": false
    }
  ]
}
Field Type Meaning
id, key, name, description Identity and description
icon EntityIcon or null The project's icon, one of the fixed set below; null is the default
billingClient { id, name } or null Null means internal work
collaboratingClients[] { id, name } Clients whose users may be elevated and to whom tickets may be billed
billingMode period or on_close Default billing mode for tickets on the project
timelineEnabled boolean Whether the project shows its Timeline (Gantt) tab
memberCount integer Project members
openTickets integer Tickets in an open state
myRole member, manager, or null The caller's project role
archived boolean Archived

EntityIcon is one of briefcase, building, factory, truck, anchor, hard-hat, heart-pulse, graduation-cap, landmark, scale, server, shopping-cart, zap, shield, wrench, headset, rocket, flag, alert-triangle, lightbulb. The same set names a saved board's icon. Any other value is refused with details.reason unknown_icon.

GET /api/w/{slug}/projects/{key}

One project with its members and what the caller may do. Token: yes, read.

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

Response 200 (ProjectDetail): every ProjectSummary field plus:

Field Type Meaning
members[] ProjectMember id, identityId, name, email, kind (workspace or client), clientId, clientName, role (member or manager), categoryId (consultant category override), hasFullLogin
permissions object edit, members, collaborators, billing (booleans)
Error Status When
not_found 404 Unknown key or not visible

GET /api/w/{slug}/projects/{key}/timeline

The rows of the project's Timeline tab: every non-archived ticket in the project the caller may see, with its dates and state, so a client can draw the Gantt chart described in Plan with the project timeline. Token: no (browser session only). Returned whether or not the tab is turned on.

Response 200 (ProjectTimeline):

Field Type Meaning
items[] TimelineItem id, humanId, title, state (id, name, category), parentId (set only when the parent is itself in items: same project and visible to the caller), startDate, dueDate, assignee or null, closedAt or null, estimateMinutes (the ticket's own; null when unset), loggedMinutes (net minutes logged on the ticket itself, not its sub-tickets). Both figures are null for client users. Ordered by start date, then creation. At most 2 000.
truncated boolean True when the project has more than 2 000 such tickets
canEdit boolean Whether the caller may change dates on the project's tickets (Owner, Admin, or full project member)
Error Status When
not_found 404 Unknown key or not visible

POST /api/w/{slug}/projects

Create a project. Token: no (browser session only). Owner or Admin.

Body field (CreateProject) Type Required Validation
key string yes 1–32 lowercase letters, digits, or hyphens; unique; fixed after creation
name string yes 1–120 characters
description string no At most 2 000 characters
icon EntityIcon or null no One of the fixed set below; null or absent is the default glyph
billingClientId uuid or null no Null is internal work
billingMode period or on_close no Default period
timelineEnabled boolean no Default false; shows the Timeline tab
collaboratingClientIds uuid[] no At most 20

Response 201 (ProjectDetail).

Error Status details.reason
forbidden 403 admin_only
invalid 400 project_key_format, name_length, unknown_client, unknown_icon
conflict 409 project_key_exists

PATCH /api/w/{slug}/projects/{key}

Change a project. Token: no (browser session only). Owner, Admin, or a workspace-user Project manager; billingClientId and billingMode are Owner or Admin only; collaboratingClientIds replaces the set and needs Owner, Admin, or a workspace-user Project manager.

Body (UpdateProject): any of name, description, icon, billingClientId, billingMode, timelineEnabled, collaboratingClientIds, with the validation above. Response 200 (ProjectDetail).

Error Status details.reason
forbidden 403 Not allowed to edit; admin_only for billing fields; manager_only for collaborators
invalid 400 name_length, unknown_client, unknown_icon
not_found 404 Unknown key

DELETE /api/w/{slug}/projects/{key}

Archive a project (projects are never deleted). Token: no (browser session only). Owner or Admin. Response 200 { "ok": true }. Errors: forbidden 403, not_found 404.

PUT /api/w/{slug}/projects/{key}/members

Add a member or change their role. For a client user this is the elevation. Token: no (browser session only). Needs a re-authentication within the last ten minutes. Owner, Admin, or a workspace-user Project manager may add workspace users; a client Project manager may elevate only users of their own client, and that client must be on the project.

Body (ProjectMemberInput): { "identityId": "…", "role": "member" } where role is member or manager. Response 200 (ProjectDetail).

Error Status details.reason
reauth_required 403 No recent re-authentication
forbidden 403 manager_only, elevate_own_client
invalid 400 client_not_on_project
not_found 404 unknown_person, or unknown project

DELETE /api/w/{slug}/projects/{key}/members/{identityId}

Remove a member (for a client user: remove the elevation). Token: no (browser session only). Recent re-authentication required; same roles as adding. Response 200 { "ok": true }. Errors: reauth_required 403, forbidden 403, not_found 404.

PUT /api/w/{slug}/projects/{key}/pin

Pin or unpin the project on the caller's own sidebar. Token: no (browser session only). Any workspace user, for a project they can see; a pin is personal and never affects anyone else. Body { "pinned": true } or { "pinned": false }; response 200 { "pinned": true }. Pinning a pinned project, or unpinning one that is not pinned, succeeds and changes nothing. At most 20 projects can be pinned.

Pinned projects are returned, in pin order, in the pinned array of GET /api/w/{slug}, each with its openTickets count over the tickets the caller may see. Archived projects drop out of the list.

Error Status Reason
invalid 400 pin_limit: 20 projects are already pinned
forbidden 403 Client users and API tokens cannot pin
not_found 404 Unknown project, or one the caller cannot see