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 |