API overview
Base URL, authentication, errors and the OpenAPI description.
Everything the web app and the CLI do goes through a JSON API under /v1. The full list of routes is
in the reference pages in the sidebar, generated from the same code the server runs. The machine
readable version is /openapi.json.
Authentication
Send a token in the Authorization header:
Authorization: Bearer <token>A token is either a Cloudtifact API token (from cloudtifact login) or a session token from the web
app. CLI tokens expire 90 days after they were last used. List and revoke yours with
GET /v1/tokens and DELETE /v1/tokens/:id.
Errors
Any non-2xx response has this body:
{ "error": { "code": "forbidden", "message": "only workspace owners and admins can do this" } }| Code | Status |
|---|---|
bad_request | 400 |
unauthorized | 401 |
forbidden | 403 (also: a plan limit was reached) |
not_found | 404 (also: you can't see it) |
conflict | 409 |
gone | 410 (an expired or used-up link) |
too_large | 413 |
rate_limited | 429 |
Resources you aren't allowed to see answer 404, not 403, so their names don't leak.
TypeScript client
@cloudtifact/contract exports createClient, the typed client the web app and CLI use, and the zod
schemas for every request and response.