Stackurity Start free trial

API reference Projects and people

Projects and people

35 operations. Base URL https://app.stackurity.dev/api/v1 on Stackurity Cloud; see authentication.

Access grants, with project, asset, person and team names

GET /access-grants

Role: admin

Parameters

ParameterInTypeDescription
project_idquerystring
asset_idquerystring
user_idquerystring
team_idquerystring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Grant a role on a project or asset to a person, team or email

POST /access-grants

Role: admin

{"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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Change a grant's role

PATCH /access-grants/{id}

Role: admin

Change a grant's role, or remove it. Takes effect on the next request

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Remove a grant

DELETE /access-grants/{id}

Role: admin

Change a grant's role, or remove it. Takes effect on the next request

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

Invitations, open and recent

GET /invitations

Role: admin

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

ParameterInTypeDescription
project_idquerystring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Invite someone to the organisation or a project

POST /invitations

Role: admin (30 an hour per organisation)

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

FieldTypeDescription
email requiredstring (email)
namestringAt most 200 characters.
rolestringOrganisation-wide role, or none with grants (or the role on project_id, in the older form). One of viewer, engineer, security, admin, none.
grantsarray of objectAt most 500 items.
grants[].project_idinteger
grants[].asset_idinteger
grants[].role requiredstringOne of viewer, engineer, security, admin.
project_idintegerOlder form: role on this one project. Not with grants.
teamsarray of integerTeams 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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Accept an invitation

POST /invitations/accept

Role: none, or the invitee's session (rate limited)

{"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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

What an invitation link is for

POST /invitations/preview

Role: none (rate limited)

{"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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Withdraw a pending invitation

DELETE /invitations/{id}

Role: admin

Withdraw a pending invitation: its link stops working

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

The first-run flow

GET /onboarding

Role: admin

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Set the first-run flow's state and project

PUT /onboarding

Role: admin

{"state": "new" | "skipped" | "done", "project_id": N}; audited as onboarding.update

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

The waiting screen's poll

GET /onboarding/results

Role: viewer

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

ParameterInTypeDescription
sincequerystring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Owner rules, most specific first

GET /owner-rules

Role: viewer

Parameters

ParameterInTypeDescription
asset_idqueryintegerRules that can apply to this asset
project_idqueryintegerRules that can apply to this project

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Create an owner rule

POST /owner-rules

Role: admin

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Preview or apply the owner rules to open issues

POST /owner-rules/apply

Role: admin

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Replace an owner rule

PUT /owner-rules/{id}

Role: admin

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Delete an owner rule

DELETE /owner-rules/{id}

Role: admin

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

Groupings proposed from runs_on, built_from and deployed_as relations

GET /project-suggestions

Role: admin

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Hide a grouping suggestion

POST /project-suggestions/dismiss

Role: admin

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Projects the caller can see

GET /projects

Role: viewer, or any grant

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

ParameterInTypeDescription
archivedquerystring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Create a project

POST /projects

Role: admin

{"name", "description", "asset_ids"}

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

One project (with its grants, for admins)

GET /projects/{id}

Role: viewer, or a grant on it

A project; for admins also its grants

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Rename, describe, archive or restore a project

PATCH /projects/{id}

Role: admin

name, description, archived (true archives: grants on it stop giving access and routes limited to it stop matching; false restores)

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Add assets to a project

POST /projects/{id}/assets

Role: admin

{"asset_ids": [...]} (1 to 5000): add or remove assets; returns changed

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Remove assets from a project

DELETE /projects/{id}/assets

Role: admin

{"asset_ids": [...]} (1 to 5000): add or remove assets; returns changed

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

Teams

GET /teams

Role: viewer

Teams, each with members, asset_count (assets it owns: alerts go to it; no access) and access (what its members see through it)

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Create a team

POST /teams

Role: admin

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Change a team and its members

PATCH /teams/{id}

Role: admin

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

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

FieldTypeDescription
namestring
emailstring
membersarray of integer
accessarray of objectThe team's grants, replaced as a whole; [] removes them. At most 500 items.
access[].project_idinteger
access[].asset_idinteger
access[].role requiredstringOne of viewer, engineer, security, admin.
ownsarray of integerAsset ids whose owner team this is, replaced as a whole.

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Delete a team

DELETE /teams/{id}

Role: admin

Manage teams and members (members must belong to the workspace)

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

Users of the organisation

GET /users

Role: admin

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Add a user to the organisation

POST /users

Role: admin

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

FieldTypeDescription
email requiredstring (email)
namestringAt most 200 characters.
phonestringContact information only: digits, optional leading +, spaces, dots, dashes, brackets; 6 to 15 digits. At most 32 characters.
passwordstringFor a new account; ignored for an existing one. At least 12 characters.
rolestringOrganisation-wide role, or none with grants. One of viewer, engineer, security, admin, none.
grantsarray of objectAt most 500 items.
grants[].project_idinteger
grants[].asset_idinteger
grants[].role requiredstringOne of viewer, engineer, security, admin.
teamsarray of integerTeams 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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Active users (id, email, name) for assignment

GET /users/directory

Role: engineer

Active users (id, email, name) for assignment. Members with project access only get themselves and the people granted one of their projects

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Change a user's role, name, phone or status

PATCH /users/{id}

Role: admin

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

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

FieldTypeDescription
namestring
rolestringOne of viewer, engineer, security, admin, none.
disabledboolean
passwordstringAt least 12 characters.
phonestringContact information on the membership in this organisation; empty clears it. At most 32 characters.

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Remove a member from the organisation

DELETE /users/{id}

Role: admin

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

Reset a member's two-factor sign-in (passkeys, app, email codes, recovery codes)

DELETE /users/{id}/mfa

Role: admin

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError