Endpoint reference

Every v1 endpoint, the permission it requires, and the shape it returns.

Reading this reference

All paths are relative to /api/v1. The Requires column names the minimum project or organization role; every endpoint additionally requires a valid token, an active account, and a completed onboarding unless noted.

Organizations bind by slug. Everything else binds by id - including projects, which is why shortspan project use stores the resolved id rather than the slug.

Unauthenticated

Method	Path	Does
`GET`	`/cli/releases/latest`	The current CLI release manifest. A client must be able to learn it is blocked before it can sign in.
`POST`	`/cli/releases/{version}/downloaded`	Record a download. Best-effort telemetry.
`POST`	`/auth/device-code`	Begin the device authorization flow.
`POST`	`/auth/device-token`	Poll for the token.

Auth and tokens

Method	Path	Requires	Does
`GET`	`/auth/me`	token	The authenticated user and the current token's abilities.
`POST`	`/auth/device-authorize`	token	Approve a pending device code. This is what the browser page calls.
`DELETE`	`/auth/token`	token	Revoke the token making the request. Works while suspended.
`GET`	`/tokens`	token	List your tokens.
`POST`	`/tokens`	token	Mint a token. Returns the plaintext once.
`DELETE`	`/tokens/{tokenId}`	token	Revoke a token.

Organizations

Method	Path	Requires	Does
`GET`	`/organizations`	token	Organizations you belong to.
`POST`	`/organizations`	token	Create one. Subject to your workspace allowance.
`GET`	`/organizations/{slug}`	viewer	One organization.
`GET`	`/organizations/{slug}/members`	viewer	Members and their roles.
`POST`	`/organizations/{slug}/members`	admin	Add a member. Needs the Team plan and a free seat.
`DELETE`	`/organizations/{slug}/members/{userId}`	admin	Remove a member from this organization only.
`GET`	`/organizations/{slug}/audit-logs`	admin	The audit log. Needs the Team plan and `audit:read`.

Projects

Method	Path	Requires	Does
`GET`	`/organizations/{slug}/projects`	viewer	Projects in an organization.
`POST`	`/organizations/{slug}/projects`	admin	Create a project.
`GET`	`/projects/{project}`	viewer	One project.
`PUT`	`/projects/{project}`	admin	Update a project.
`DELETE`	`/projects/{project}`	admin	Delete a project and everything scoped to it.

Secrets

Method	Path	Requires	Does
`GET`	`/secret-templates`	token	Every template and its field schema.
`GET`	`/projects/{project}/secrets`	viewer	Secrets and metadata. Never values. `?group=` filters.
`POST`	`/projects/{project}/secrets`	developer	Create a secret.
`PUT`	`/secrets/{secret}`	developer	Update, creating a new version.
`DELETE`	`/secrets/{secret}`	admin	Delete a secret and its history.
`GET`	`/secrets/{secret}/value`	developer	Reveal the plaintext. Reveal-limited, audited as a reveal.
`GET`	`/secrets/{secret}/inject`	developer	The value for injection into a process. Reveal-limited.

Secret groups

Method	Path	Requires	Does
`GET`	`/projects/{project}/secret-groups`	viewer	Groups in a project.
`POST`	`/projects/{project}/secret-groups`	developer	Create a group.
`GET`	`/secret-groups/{group}`	viewer	One group.
`PUT`	`/secret-groups/{group}`	developer	Update a group.
`GET`	`/secret-groups/{group}/secrets`	viewer	Keys in the group. No values.
`GET`	`/secret-groups/{group}/inject`	developer	Every value in the group, for injection. Reveal-limited.
`DELETE`	`/secret-groups/{group}`	admin	Delete the group, leaving its secrets ungrouped.

SSH targets

Method	Path	Requires	Does
`GET`	`/projects/{project}/ssh-targets`	viewer	Targets and metadata.
`POST`	`/projects/{project}/ssh-targets`	admin	Register a server.
`GET`	`/ssh-targets/{target}`	viewer	One target.
`PUT`	`/ssh-targets/{target}`	admin	Update a target, including its security policy.
`DELETE`	`/ssh-targets/{target}`	admin	Remove a target.
`POST`	`/ssh-targets/{target}/credential`	developer	Issue a proxy token - not the credential. Reveal-limited.
`POST`	`/ssh/exchange-credential`	developer	Redeem a proxy token for the credential. Single use.
`GET`	`/ssh-targets/{target}/checks`	viewer	The ten most recent readiness reports.
`POST`	`/ssh-targets/{target}/checks`	developer	Record a readiness report from `ssh check` or `runbook check`. Needs `ssh:use`; every string is redacted before storage.

Databases, AWS, Kubernetes

Method	Path	Requires	Does
`GET`	`/projects/{project}/database-targets`	viewer	Database targets.
`POST`	`/projects/{project}/database-targets`	admin	Register a database.
`GET`	`/database-targets/{target}`	viewer	One target.
`DELETE`	`/database-targets/{target}`	admin	Remove a target.
`POST`	`/database-targets/{target}/credential`	developer	Issue database credentials. Reveal-limited.
`GET`	`/projects/{project}/aws-profiles`	viewer	AWS profiles.
`POST`	`/projects/{project}/aws-profiles`	admin	Register a profile.
`GET`	`/aws-profiles/{profile}`	viewer	One profile.
`DELETE`	`/aws-profiles/{profile}`	admin	Remove a profile.
`POST`	`/aws-profiles/{profile}/inject`	developer	Issue AWS credentials. Reveal-limited.
`GET`	`/projects/{project}/k8s-contexts`	viewer	Kubernetes contexts.
`POST`	`/projects/{project}/k8s-contexts`	admin	Register a context.
`GET`	`/k8s-contexts/{context}`	viewer	One context.
`DELETE`	`/k8s-contexts/{context}`	admin	Remove a context.
`POST`	`/k8s-contexts/{context}/kubeconfig`	developer	Issue the kubeconfig. Reveal-limited.

Infrastructure profiles

Method	Path	Requires	Does
`GET`	`/projects/{project}/profiles`	viewer	Profiles in a project.
`POST`	`/projects/{project}/profiles`	admin	Create a profile.
`GET`	`/profiles/{profile}`	viewer	One profile.
`DELETE`	`/profiles/{profile}`	admin	Delete a profile. Its resources are untouched.
`POST`	`/profiles/{profile}/enter`	developer	Resolve every resource the caller can reach, and how to reach it.

Runbooks

Method	Path	Requires	Does
`GET`	`/projects/{project}/runbooks`	viewer	Runbooks in a project.
`POST`	`/projects/{project}/runbooks`	admin	Create a runbook.
`GET`	`/runbooks/{runbook}`	viewer	One runbook and its steps.
`PUT`	`/runbooks/{runbook}`	admin	Update, creating a new version.
`DELETE`	`/runbooks/{runbook}`	admin	Delete a runbook.
`POST`	`/runbooks/{runbook}/execute`	developer	Execute, or create a pending execution if approval is required.
`POST`	`/runbook-executions/{execution}/approve`	admin	Approve one execution.
`POST`	`/runbook-executions/{execution}/complete`	developer	Report the outcome of an execution, optionally with each step's status, exit code, duration, and output - redacted before it is stored.

Access requests

Method	Path	Requires	Does
`GET`	`/access-requests`	token	Requests you can see.
`POST`	`/projects/{project}/access-requests`	requester	Ask for temporary access. Reason required.
`GET`	`/access-requests/{request}`	requester	The status of one request.
`PUT`	`/access-requests/{request}/approve`	admin	Approve, creating a temporary grant.
`PUT`	`/access-requests/{request}/deny`	admin	Deny.

CLI command records

Method	Path	Requires	Does
`POST`	`/cli/commands`	token	Record the start of a command.
`POST`	`/cli/commands/{execution}/complete`	token	Record its outcome.

The CLI calls both automatically. They record which command ran, not its arguments or output.

Something here wrong or missing? Tell us.