The Apprail API

The console and the CLI are built on the same versioned REST API. Everything they do, your own tools can do.

Authentication

Send an API token as a bearer token. A token belongs to one workspace, carries its access (read, deploy, or full), and never exceeds its creator’s role.

curl https://console.apprail.io/api/v1/me \
  -H "Authorization: Bearer $APPRAIL_TOKEN"

Deploy with curl

curl -X POST https://console.apprail.io/api/v1/services/$SERVICE_ID/deployments \
  -H "Authorization: Bearer $APPRAIL_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"environment_id": "'$ENV_ID'", "image": "ghcr.io/acme/web:1.4"}'

curl https://console.apprail.io/api/v1/deployments/$DEPLOYMENT_ID \
  -H "Authorization: Bearer $APPRAIL_TOKEN"

Reference

The OpenAPI 3.1 description is the complete reference: https://console.apprail.io/api/openapi.yaml. Load it into your HTTP client or generate a typed client from it. GET /api/v1/capabilities needs no sign-in and says what this platform supports right now, separating what’s available from what’s planned.

All paths start with /api/v1. The JSON Schema for apprail.yml is at /api/apprail.schema.json.

Conventions

• Idempotency. Requests that create something (deployments, builds, databases, runs…) need an Idempotency-Key header. Retrying with the same key returns the original result instead of doing it twice — so retry freely after a timeout.
• Errors are JSON: {"error": {"code", "message", "request_id"}}. The code is stable and meant for programs (quota_exceeded, hostname_taken, approval_requires_person…); the message is for people. Quote the request ID when you contact support.
• Lists return {"items", "next_cursor"}; pass cursor for the next page.
• Streams. Logs and live command output stream as Server-Sent Events. A one-off run’s stream ends with a done event carrying its state and exit code.
• Long operations return at once with the thing they started (a deployment, build, or operation) for you to poll.
• Permissions. A token’s access is checked on every request: read tokens can’t change anything, and deploy tokens are limited to deploying, building, promoting, rolling back, and job runs. Some actions — approving deployments, changing protection, managing sessions, exporting values — refuse tokens entirely.