API reference Projects and people
Projects and people
Access grants, with project, asset, person and team names
GET /access-grants
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
project_id | query | string | |
asset_id | query | string | |
user_id | query | string | |
team_id | query | string |
Responses
Grant a role on a project or asset to a person, team or email
POST /access-grants
{"project_id" or "asset_id", "user_id" or "team_id" or "email", "role"}. With email, someone who is not a member joins with no organisation-wide role (an account is created with password when there is none; account_created says so). A grant that exists for the same person or team and project or asset has its role changed (200); a new one is 201
Request body
application/json, required: object
Responses
Change a grant's role
PATCH /access-grants/{id}
Change a grant's role, or remove it. Takes effect on the next request
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Remove a grant
DELETE /access-grants/{id}
Change a grant's role, or remove it. Takes effect on the next request
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Invitations, open and recent
GET /invitations
Invitations: open ones, and the others of the last 30 days, with status (pending, accepted, revoked, expired), scope (organisation, specific, or project for one made before grants) and grants (kind, project_id or asset_id, role, name, available, unavailable: archived, merged or deleted). project_id lists the ones that name that project. Never the link
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
project_id | query | string |
Responses
Invite someone to the organisation or a project
POST /invitations
Invite someone and say what they will see, as for POST /users: an organisation-wide role (every project and asset), or grants ([{"project_id", "role"} | {"asset_id", "role"}], with role none or no role). The older form {"role", "project_id"} is still accepted and becomes one project grant. teams: teams they join on accepting (each invitation lists them with what they can see, in teams). There is no default: neither is 400, and so is a grant on a project or asset that is not this organisation's (or an archived project or merged asset); nothing is created then. 201 with invitation (with scope and grants), emailed and replaced (the person's earlier open invitations, now withdrawn: one open invitation per person); when the email was not sent, link (shown once) and email_problem. Someone already a member gets the grants at once, all or none (granted, grants, and grant: the first); an organisation-wide invitation for a member is 409
Request body
application/json, required: object
| Field | Type | Description |
|---|---|---|
email required | string (email) | |
name | string | At most 200 characters. |
role | string | Organisation-wide role, or none with grants (or the role on project_id, in the older form). One of viewer, engineer, security, admin, none. |
grants | array of object | At most 500 items. |
grants[].project_id | integer | |
grants[].asset_id | integer | |
grants[].role required | string | One of viewer, engineer, security, admin. |
project_id | integer | Older form: role on this one project. Not with grants. |
teams | array of integer | Teams to add them to; membership gives the team's access. With role none, may stand in for grants when one of the teams can see something. At most 50 items. |
Responses
Accept an invitation
POST /invitations/accept
{"token", "name", "password"}. Joins the invitation's organisation with what it gives, in one transaction; answers workspace_id, project_id (its only project, or 0), role, scope, grants (how many were given), dropped (grants skipped because the project was archived or deleted, or the asset merged or deleted, since the invitation was sent), account_created and joined, and the browser session then works in that organisation. 410 invitation_stale when nothing is left to give (nothing is written; the invitation stays open); 410 invitation_invalid when the link does not work; 409 sign_in_required or wrong_account
Request body
application/json, required: object
Responses
What an invitation link is for
POST /invitations/preview
{"token"}: what the link is for (workspace, project and role when it names one project or all of them, scope, grants with whether each can still be given, usable, email, invited_by, expires_at, account_exists) and signed_in_as. 410 for any link that does not work, without saying why
Request body
application/json, required: object
Responses
Withdraw a pending invitation
DELETE /invitations/{id}
Withdraw a pending invitation: its link stops working
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
The first-run flow
GET /onboarding
The first-run flow: state (new, skipped, done), show_flow (state new and no assets yet), has_assets, project_id and project (chosen in the flow), and steps (project, asset, notifications, invite), each read from what exists. The state becomes done only when an admin hides the Dashboard's setup checklist
Responses
Set the first-run flow's state and project
PUT /onboarding
{"state": "new" | "skipped" | "done", "project_id": N}; audited as onboarding.update
Request body
application/json, required: object
Responses
The waiting screen's poll
GET /onboarding/results
The waiting screen's poll: assets created since since (RFC 3339; default the last 24 hours), newest first, at most 20, in the chosen project (project_id or the header). Each has packages, issues (active), checked (its first complete report has been evaluated, so the counts are final) and fixes_now (fixes in Home's focus)
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
since | query | string |
Responses
Owner rules, most specific first
GET /owner-rules
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
asset_id | query | integer | Rules that can apply to this asset |
project_id | query | integer | Rules that can apply to this project |
Responses
Create an owner rule
POST /owner-rules
Request body
application/json, required: object
Responses
Preview or apply the owner rules to open issues
POST /owner-rules/apply
Request body
application/json, required: object
Responses
Replace an owner rule
PUT /owner-rules/{id}
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Delete an owner rule
DELETE /owner-rules/{id}
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Groupings proposed from runs_on, built_from and deployed_as relations
GET /project-suggestions
Groupings proposed from runs_on, built_from and deployed_as relations: assets in no project related to a project's assets (project_id), or related assets all in no project (suggested_name). Nothing changes until someone adds the assets; {"key"} hides one until its assets change
Responses
Hide a grouping suggestion
POST /project-suggestions/dismiss
Groupings proposed from runs_on, built_from and deployed_as relations: assets in no project related to a project's assets (project_id), or related assets all in no project (suggested_name). Nothing changes until someone adds the assets; {"key"} hides one until its assets change
Request body
application/json, required: object
Responses
Projects the caller can see
GET /projects
Projects the caller can see (members with project access only: theirs, each with their role), with asset_count; organisation-wide callers also get unfiled_assets, the assets in no active project. archived=true (admins) includes archived projects
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
archived | query | string |
Responses
Create a project
POST /projects
{"name", "description", "asset_ids"}
Request body
application/json, required: object
Responses
One project (with its grants, for admins)
GET /projects/{id}
A project; for admins also its grants
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Rename, describe, archive or restore a project
PATCH /projects/{id}
name, description, archived (true archives: grants on it stop giving access and routes limited to it stop matching; false restores)
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Add assets to a project
POST /projects/{id}/assets
{"asset_ids": [...]} (1 to 5000): add or remove assets; returns changed
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Remove assets from a project
DELETE /projects/{id}/assets
{"asset_ids": [...]} (1 to 5000): add or remove assets; returns changed
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Teams
GET /teams
Teams, each with members, asset_count (assets it owns: alerts go to it; no access) and access (what its members see through it)
Responses
Create a team
POST /teams
Request body
application/json, required: object
Responses
Change a team and its members
PATCH /teams/{id}
Change a team in one transaction: name, email, members, access (replaces its grants on projects and assets; members see them while in the team) and owns (replaces the assets whose owner team it is; ownership routes alerts and gives no access)
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
| Field | Type | Description |
|---|---|---|
name | string | |
email | string | |
members | array of integer | |
access | array of object | The team's grants, replaced as a whole; [] removes them. At most 500 items. |
access[].project_id | integer | |
access[].asset_id | integer | |
access[].role required | string | One of viewer, engineer, security, admin. |
owns | array of integer | Asset ids whose owner team this is, replaced as a whole. |
Responses
Delete a team
DELETE /teams/{id}
Manage teams and members (members must belong to the workspace)
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Users of the organisation
GET /users
Members of the organisation. Each has role (none: access through projects only), access (organisation or projects), phone, and project_grants and asset_grants (their own grants, not their teams'), teams and access_teams (their teams that can see something).
Responses
Add a user to the organisation
POST /users
Add a user and say what they can see, in one transaction: an organisation-wide role (every project and asset), or grants on chosen projects and assets with role none. There is no default: a request with neither is 400 and creates nothing; so is a grant on a project or asset of another organisation. teams adds them to teams in the same transaction (a team that can see nothing does not count as access). Off on Stackurity Cloud (invite_only).
Request body
application/json, required: object
| Field | Type | Description |
|---|---|---|
email required | string (email) | |
name | string | At most 200 characters. |
phone | string | Contact information only: digits, optional leading +, spaces, dots, dashes, brackets; 6 to 15 digits. At most 32 characters. |
password | string | For a new account; ignored for an existing one. At least 12 characters. |
role | string | Organisation-wide role, or none with grants. One of viewer, engineer, security, admin, none. |
grants | array of object | At most 500 items. |
grants[].project_id | integer | |
grants[].asset_id | integer | |
grants[].role required | string | One of viewer, engineer, security, admin. |
teams | array of integer | Teams to add them to; membership gives the team's access. With role none, may stand in for grants when one of the teams can see something. At most 50 items. |
Responses
Active users (id, email, name) for assignment
GET /users/directory
Active users (id, email, name) for assignment. Members with project access only get themselves and the people granted one of their projects
Responses
Change a user's role, name, phone or status
PATCH /users/{id}
Manage users. role none keeps someone a member with no organisation-wide role (access through projects only); each user has access: organisation or projects
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
| Field | Type | Description |
|---|---|---|
name | string | |
role | string | One of viewer, engineer, security, admin, none. |
disabled | boolean | |
password | string | At least 12 characters. |
phone | string | Contact information on the membership in this organisation; empty clears it. At most 32 characters. |
Responses
Remove a member from the organisation
DELETE /users/{id}
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Reset a member's two-factor sign-in (passkeys, app, email codes, recovery codes)
DELETE /users/{id}/mfa
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |