Get started

Reference

API reference

Everything lives under /api/v1on your dashboard's address and answers in JSON.

Authentication

Create an API token in the dashboard under Settings → Integrations, and send it as a bearer token. It can reach everything in the team that created it, including environment variables, so treat it like a password.

shell
curl https://dash.example.com/api/v1/apps \
  -H "Authorization: Bearer $SKIFF_TOKEN"

Apps

GET/appsList the team's apps.
GET/apps/{name}One app: state, address, replicas and latest commit.
GET/apps/{name}/logsRecent output from the app and its workers. Add ?lines= up to 2000, or ?follow=1 to stream it as plain text.
GET/apps/{name}/insightsTraffic and uptime. Add ?range= with 1h, 24h or 7d. The default is 24h.

Deploys

POST/apps/{name}/deployDeploy the newest commit. For an image project, send {"image": "..."} to change the image.
GET/apps/{name}/deploysThe app's history, marking which can be rolled back to.
POST/apps/{name}/rollbackGo back to an earlier deploy. Send {"deploy": "<id>"}.
GET/deploys/{id}A deploy's status: building, live, failed or canceled.
GET/deploys/{id}/logA deploy's status and the last 200 lines of its build log.

Previews

POST/apps/{name}/previewsCreate or redeploy a branch's preview. Send {"branch": "feat/login"}.
DELETE/apps/{name}/previews?branch=Remove a branch's preview.

Environment variables

GET/apps/{name}/envRead the app's variables, including their values.
PUT/apps/{name}/envReplace all of them. Send {"vars": [{"key": "A", "value": "1", "build": false}]}. They apply on the next deploy.

Deploying from a script

A deploy starts in the background. Starting one answers 202with its ID, and you check it until it's no longer building.

shell
curl -X POST https://dash.example.com/api/v1/apps/shop-api/deploy \
  -H "Authorization: Bearer $SKIFF_TOKEN"
# {"app":"shop-api","id":"1793677298-2188f1","status":"building","url":"https://shop-api.example.com"}

curl https://dash.example.com/api/v1/deploys/1793677298-2188f1 \
  -H "Authorization: Bearer $SKIFF_TOKEN"

Errors

Errors answer with a status code and a message, like {"error": "app not found"}. A bad or missing token answers 401. Another team's app answers 404, the same as one that doesn't exist.

On GitHub, the Action does this for you. To let an AI agent use Skiff, see AI agents.

PreviousAI agents (MCP)