Developers
API reference
The Stackap HTTP API exposes every operation the command-line tool and the dashboard perform, authenticated by a bearer token that belongs to exactly one organization.
Conventions
Every route is under /v1, sends and receives JSON, and takes Authorization: Bearer <token>. A token belongs to one organization, and the organization comes from the token alone. A resource in another organization returns the same 404 as one that does not exist. Errors are JSON with an error field, and some also carry a stable code. Roles are owner, member and platform admin; routes marked as operator-only return 403 to anyone else.
Projects
| Route | What it does |
|---|---|
POST /v1/projects | Body {slug, name}. Creates a project and its git repository. Returns the project. Refused with 403 at the organization's project limit (default 10). |
GET /v1/projects, GET /v1/projects/:slug | List projects, or read one. |
PUT /v1/projects/:slug/settings | Body {port?, health_path?}; null resets a value. Applies from the next deploy. Owner only. |
Deployments
| Route | What it does |
|---|---|
GET /v1/projects/:slug/deployments | Up to 100 rows with id, number, status, build_id, image_ref, created_at, activated_at, retired_at and rolled_back_from. |
GET /v1/projects/:slug/builds, GET /v1/builds/:id, GET /v1/builds/:id/logs | Builds, one build, and the log of any build by id. |
POST /v1/projects/:slug/rollback | Returns {status, deployment}. 502 if the previous deployment is unhealthy, 409 if there is nothing to roll back to. |
PUT /v1/projects/:slug/scale | Body {replicas}, 1 to 8. Platform admin only. |
Variables and domains
| Route | What it does |
|---|---|
GET /v1/projects/:slug/env | Keys and a mask, never values. System variables are flagged. |
PUT /v1/projects/:slug/env/:key | Body {value}. 204. Refuses a system key with 409. DELETE removes one. |
POST /v1/projects/:slug/domains | Body {hostname}. 201 with dns_status, ssl_status and an instructions object giving the A record to create. |
GET /v1/projects/:slug/domains, DELETE …/domains/:hostname | List with refreshed status; detach. |
Cron
| Route | What it does |
|---|---|
GET /v1/projects/:slug/cron | Jobs with their last status and last run time. |
PUT /v1/projects/:slug/cron/:name | Body {schedule, path, enabled?}. UTC, five fields; the path starts with a slash. |
POST /v1/projects/:slug/cron/import | Body {crons: [{path, schedule}]} in vercel.json format. Returns {imported}. |
GET /v1/projects/:slug/cron/:name/runs | Run history. |
Data, backups and metrics
| Route | What it does |
|---|---|
GET, POST /v1/projects/:slug/database | Read or provision the project's database. Credentials are never returned. |
GET /v1/projects/:slug/data/tables and …/tables/:schema/:table | Table browser reads with limit, offset, sort, dir and q. POST …/rows with {values} and DELETE …/rows with {key} write; owner only. |
POST, GET /v1/projects/:slug/backups | Take a backup (201, {id, status}) or list the most recent 100. |
POST /v1/projects/:slug/restore | Body {backup_id?}. Restores into a new database and returns its name. The live database is never modified. |
POST /v1/backups/:id/verify | Restore a backup into a scratch database and compare row counts. |
GET /v1/projects/:slug/metrics?range=1h|24h|7d, …/timeline | Load-time metrics and a timeline of what changed. |
GET /v1/projects/:slug/logs?source=build|runtime&limit=N | Logs, 1 to 5000 lines. |
Access and organizations
| Route | What it does |
|---|---|
POST, GET /v1/api-tokens, DELETE /v1/api-tokens/:id | Body {name, role?, scopes?, expires_in_days?}. Roles are owner and member. GET /v1/capabilities lists the scope names. |
POST, GET /v1/ssh-keys, DELETE /v1/ssh-keys/:id | Register the public key you push with. Body {name, public_key}. |
GET /v1/me, /v1/overview, /v1/activity | Who you are, a dashboard summary, and recent changes in your organization. Values are never included. |
POST, GET /v1/orgs | Platform admin only. Body {slug, name, max_projects?}; the reply includes an owner token shown once. POST …/orgs/:slug/disable and …/enable suspend and restore one. |
GET /v1/approvals, GET /v1/approvals/:id | Your organization's approval requests and their status (pending, approved, denied, consumed or expired). After an approval_required answer, poll the one you were given, then repeat the identical request once it is approved. The decision link is never in an API response. |
DELETE /v1/projects/:slug, POST …/undelete | Soft-delete a project (it stops serving; code, database and backups are kept) and bring it back. With an approval-mode token the delete waits for a human approval. |
GET /v1/status, /v1/alerts, /v1/platform/overview | Platform admin only. Host-wide health, current alerts and the operator overview. |
What this page is not
The list of routes and scopes is also generated by the server itself at /v1/capabilities and /v1/openapi.json, with no token needed. This page adds the request bodies and responses, written by reading the route files, so fields not mentioned here may exist. Where a body shape is not given, the route takes no body.
Early-access scope
- Request and response shapes here are hand-written, so some optional fields may be undocumented.
Stackap is in early access. Tell us what you run and we will reply with a straight answer about whether it fits.
Ask for an invitationLast updated .