REST API Reference — Skyversal

The Skyversal REST API exposes everything the console does — it is the same surface the Skyversal CLI talks to. Projects, deployments, environment variables, domains, backups, cron jobs and the mail service are managed here.

Interactive: open the API Explorer to call endpoints live from your browser. Machine-readable spec: /api/openapi.yaml (or .json).

Authentication — device code (RFC 8628)

POST /device/code → returns device_code + user_code.
The user opens verification_uri and approves the code — the password never touches the terminal.
POST /device/token → returns a Bearer access_token.
Send Authorization: Bearer <token> on every authenticated call.

Role matrix and rate limits

Every project-scoped endpoint resolves {projectKey} as numeric id or slug, then checks your role: owner > manager > developer > viewer. Read endpoints need viewer, write endpoints need manager. Inaccessible or missing projects return 404 — resource existence is never leaked.

Bucket	Limit
Read (authenticated GET)	60 req/min
Write (POST/PUT/PATCH/DELETE)	10 req/min
Source upload	20 req/min
Device code / token polling	10 / 30 req/min
Public health & apps	60 req/min

Endpoints

Base URL: https://skyversal.com/api/cli

Authentication

POST/device/code

Request a device code

Starts the device authorization flow. Returns the codes the user must approve in the browser.

Body (application/json): client_id — required: client_id

200 · 422 · 429

POST/device/token

Poll for an access token

Poll until the user approves (authorization_pending) or the code expires. On approval returns a Bearer token.

Body (application/json): client_id, grant_type, device_code — required: client_id, grant_type, device_code

200 · 400 · 422 · 429

GET/whoami

Current token owner

200 · 401 · 429

Ecosystem

GET/health

Platform health

200 · 429

GET/apps

Installable app catalog

200 · 429

POST/apps/install

Install an app

Requires manager role.

Body (application/json): app_id — required: app_id

200 · 401 · 422 · 429

GET/doctor

Connectivity self-check

200 · 401 · 429

Projects

GET/projects

List accessible projects

Owned + shared projects, sorted by name. Viewer role is enough.

200 · 401 · 429

POST/projects

Create a project

Requires manager role. A verified e-mail address is required first (403 otherwise).

Body (application/json): name, framework, port — required: name

201 · 401 · 403 · 422 · 429

GET/projects/{projectKey}

Project detail

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

POST/projects/{projectKey}/restart

Restart the process

Requires manager role. Restarts the running container — no rebuild.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

Deployments

POST/projects/{projectKey}/deploy

Trigger a deploy

Requires manager role. Rebuilds from the linked source (GitHub/template) or the last uploaded artifact.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

GET/projects/{projectKey}/deploys

Deployment history

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

GET/projects/{projectKey}/deploys/{deploymentId}

Deployment status

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.
deploymentId *	path	(integer)

200 · 401 · 404 · 429

GET/projects/{projectKey}/deploys/{deploymentId}/logs

Deployment build log

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.
deploymentId *	path	(integer)

200 · 401 · 404 · 429

POST/projects/{projectKey}/deploys/{deploymentId}/rollback

Roll back to a deployment

Requires manager role. Re-points traffic to a previous image — no rebuild.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.
deploymentId *	path	(integer)

200 · 401 · 404 · 429

POST/projects/{projectKey}/deploys/{deploymentId}/cancel

Cancel a deployment

Requires manager role. Queued deploys cancel immediately; running builds stop at the next checkpoint.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.
deploymentId *	path	(integer)

200 · 401 · 404 · 429

POST/projects/{projectKey}/upload

Upload source artifact

Requires manager role. Multipart upload of a .tar.gz source
snapshot (max 100 MB). Pass deploy=true to deploy right after.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

Body (multipart/form-data): source, deploy — required: source

200 · 401 · 404 · 422 · 429

Environment

GET/projects/{projectKey}/env

List environment variables

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

POST/projects/{projectKey}/env

Set environment variables

Requires manager role. Keys must match ^[A-Za-z_][A-Za-z0-9_]*$.
Changes take effect on the next deploy.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

Body (application/json): vars — required: vars

200 · 401 · 404 · 422 · 429

DELETE/projects/{projectKey}/env/{envKey}

Delete an environment variable

Requires manager role.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.
envKey *	path

200 · 401 · 404 · 429

Logs & Metrics

GET/projects/{projectKey}/logs/runtime

Runtime logs

Live application logs from the running container.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

GET/projects/{projectKey}/logs/access

Access log summary

IP / user-agent / path breakdown for the project's own domains.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

GET/projects/{projectKey}/metrics

Resource metrics

CPU / RAM / disk usage of the running container.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

Domains

GET/projects/{projectKey}/domains

List domains

Domains attached to the project, with SSL state.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

POST/projects/{projectKey}/domains

Attach a domain

Requires manager role. Platform subdomains (*.skyversal.xyz etc.)
cannot be attached — they are auto-assigned. SSL starts as pending;
call verify once DNS has propagated.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

Body (application/json): domain — required: domain

200 · 401 · 404 · 409 · 422 · 429

DELETE/projects/{projectKey}/domains/{hostOrId}

Detach a domain

Requires manager role.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.
hostOrId *	path	Domain host (`www.example.com`) or numeric id.

200 · 401 · 404 · 429

POST/projects/{projectKey}/domains/{hostOrId}/verify

Verify domain (DNS + TLS)

Requires manager role. Runs a real TLS handshake; writes active only when the certificate is live — never fabricated.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.
hostOrId *	path	Domain host (`www.example.com`) or numeric id.

200 · 401 · 404 · 429

Backups

GET/projects/{projectKey}/backups

List backups

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

POST/projects/{projectKey}/backups

Take a backup now

Requires manager role. Runs asynchronously.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

DELETE/projects/{projectKey}/backups/{id}

Delete a backup

Requires manager role.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.
id *	path	(integer)

200 · 401 · 404 · 429

GET/projects/{projectKey}/backups/{id}/download

Download a backup

Returns the backup file for download. Viewer role is enough.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.
id *	path	(integer)

200 · 401 · 404 · 429

POST/projects/{projectKey}/backups/{id}/restore

Restore a backup

Requires manager role. Destructive — overwrites the live
database. Body confirm must exactly equal the backup's filename.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.
id *	path	(integer)

Body (application/json): confirm — required: confirm

200 · 401 · 404 · 422 · 429

GET/projects/{projectKey}/backup-schedule

Read backup schedule

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

PUT/projects/{projectKey}/backup-schedule

Set backup schedule

Requires manager role. Retention derives from interval (hourly → 3d, 3-hourly → 7d, daily → 30d). The newest successful backup is never pruned.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

Body (application/json): every_hours

200 · 401 · 404 · 422 · 429

PATCH/projects/{projectKey}/backup-schedule

Set backup schedule (PATCH)

Same as PUT — both verbs accepted.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

Body (application/json): every_hours

200 · 401 · 404 · 422 · 429

Scale

GET/projects/{projectKey}/scale

Current resource limits

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

PATCH/projects/{projectKey}/scale

Set resource limits

Requires manager role. Values must stay under the plan +
add-on ceiling — raising the ceiling is billing's job; the API
returns 422 instead of silently clipping.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

Body (application/json): ram_mb, cpu_mcpu, disk_mb

200 · 401 · 404 · 422 · 429

Cron

GET/projects/{projectKey}/cron

List scheduled jobs

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

POST/projects/{projectKey}/cron

Create a scheduled job

Requires manager role. cron_expression is validated up front — an invalid expression is rejected instead of silently never running.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

Body (application/json): name, command, cron_expression, timezone, timeout_seconds — required: name, command, cron_expression

200 · 401 · 404 · 422 · 429

DELETE/projects/{projectKey}/cron/{id}

Delete a job

Requires manager role.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.
id *	path	(integer)

200 · 401 · 404 · 429

POST/projects/{projectKey}/cron/{id}/toggle

Enable / disable a job

Requires manager role.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.
id *	path	(integer)

200 · 401 · 404 · 429

POST/projects/{projectKey}/cron/{id}/run

Run a job now

Requires manager role. Fires the command immediately, outside the schedule.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.
id *	path	(integer)

200 · 401 · 404 · 429

Mail

GET/projects/{projectKey}/mail

Mail service status

Enabled state, sender domain, quota usage, DNS health.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

PUT/projects/{projectKey}/mail

Configure mail service

Requires manager role. Set sender domain or toggle the service. Your MX records are never touched — inbound mail keeps working.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

Body (application/json): domain, enabled

200 · 401 · 404 · 422 · 429

PATCH/projects/{projectKey}/mail

Configure mail service (PATCH)

Same as PUT — both verbs accepted.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

Body (application/json): domain, enabled

200 · 401 · 404 · 422 · 429

DELETE/projects/{projectKey}/mail

Disable mail service

Requires manager role. DNS records are kept — re-enable any time.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

GET/projects/{projectKey}/mail/relay

Relay (SMTP) credentials info

Shared-relay SASL endpoint + username for direct SMTP use.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

GET/projects/{projectKey}/mail/dns

DNS records to publish

SPF + DKIM records needed for the sender domain.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

GET/projects/{projectKey}/mail/verify

Verify mail DNS

Live check whether published DNS matches expected records.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

GET/projects/{projectKey}/mail/usage

Quota usage + trend

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

GET/projects/{projectKey}/mail/log

Send history

Message-ID based send log for the project.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

POST/projects/{projectKey}/mail/test

Send a test e-mail

Requires manager role. Fails cleanly when the service is off — enable first.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

Body (application/json): to — required: to

200 · 401 · 404 · 422 · 429

POST/projects/{projectKey}/mail/provision

Provision / repair mail service

Requires manager role. (Re)creates SASL + DKIM for the project — idempotent repair path.

Param	In	Description / Type
projectKey *	path	Project numeric id or slug.

200 · 401 · 404 · 429

Databases

GET/databases

List databases

Account-scoped databases owned by the token user.

200 · 401 · 429

POST/databases

Create a database

Requires manager-equivalent account scope.

Body (application/json): engine, name — required: engine

200 · 401 · 422 · 429

DELETE/databases/{id}

Delete a database

Param	In	Description / Type
id *	path	`project_303`, `standalone_8` or bare numeric id.

200 · 401 · 404 · 429

GET/databases/{id}/credential

Database credentials

Connection credentials. Accepts project_303, standalone_8 or a bare 8 as id.

Param	In	Description / Type
id *	path	`project_303`, `standalone_8` or bare numeric id.

200 · 401 · 404 · 429

Redis

GET/redis

List Redis instances

Account-scoped Redis instances owned by the token user.

200 · 401 · 429

POST/redis

Create a Redis instance

200 · 401 · 422 · 429

DELETE/redis/{id}

Delete a Redis instance

Param	In	Description / Type
id *	path	`project_303`, `standalone_8` or bare numeric id.

200 · 401 · 404 · 429

This reference is generated from openapi.yaml — the page stays in sync with the spec.