# REST API reference The platform REST API lives at `https://api.orkestr.eu/api/v1`. Everything the console does is also reachable here - create projects, manage environments, trigger deployments, read logs, attach add-ons, and rotate API tokens. For the sandbox runtime (LLM-isolated VM execution) see the separate [Sandboxes REST API](https://orkestr.eu/docs/sandboxes/api-reference) at `api.orkestr.eu/v1/sandboxes`. ## Authentication All requests require a Bearer token in the `Authorization` header. Generate tokens from **Settings -> API** in the console (available on every plan). ```bash curl -X GET https://api.orkestr.eu/api/v1/projects \ -H "Authorization: Bearer ork_your_token_here" \ -H "Content-Type: application/json" ``` ## Base URL ```bash https://api.orkestr.eu/api/v1 ``` All endpoints return JSON. Successful responses use 2xx status codes. Errors return `{"detail": "error message"}`. ## OpenAPI spec A machine-readable OpenAPI 3.1 spec is published at [api.orkestr.eu/openapi.json](https://api.orkestr.eu/openapi.json). Point your code generator, SDK tooling, or AI agent at it to build a typed client or tool definitions automatically. Interactive docs live at [api.orkestr.eu/docs](https://api.orkestr.eu/docs). ## Rate limits Limits are per-token, applied to the API surface (not the console). - **Starter (free)** - 1 active token - **Pro** - 100 requests / minute, 5 active tokens - **Team** - 500 requests / minute, 20 active tokens ## Token format API tokens look like `ork_`. The `ork_` prefix makes them easy to spot in logs and secret scanners. - Tokens are hashed (SHA-256) - we never store the raw value - Shown once on creation - copy immediately - Optional expiry: 30, 90, 180, or 365 days, or never ## Projects Create, manage, and analyze your projects. GET`/projects` List all projects. POST`/projects` Create a new project. GET`/projects/{project_id}` Get project details. PATCH`/projects/{project_id}` Update project settings. DELETE`/projects/{project_id}` Delete a project and destroy its containers. POST`/projects/{project_id}/analyze` Analyze repo - detect framework, generate Dockerfile. GET`/projects/{project_id}/env-vars` Return decrypted project-level env vars. GET`/projects/{project_id}/webhook` Webhook info: provider, URL, last delivery. POST`/projects/{project_id}/webhook/toggle` Enable or disable auto-deploy on git push. GET`/projects/check-name/{name}` Check whether a project slug is available. ## Environments Manage per-project environments (production, staging, dev) - each with its own branch, env vars, and deploy history. GET`/projects/{project_id}/environments` List environments. POST`/projects/{project_id}/environments` Create an environment. PATCH`/projects/{project_id}/environments/{env_id}` Update environment. DELETE`/projects/{project_id}/environments/{env_id}` Delete an environment (production cannot be deleted). GET`/projects/{project_id}/environments/{env_id}/env-vars` Return decrypted env vars for an environment. ## Deployments Trigger deployments, fetch logs, and roll back. POST`/projects/{project_id}/deployments` Trigger a deployment. Optional ?environment_id=uuid. GET`/projects/{project_id}/deployments` List deployments. GET`/deployments/{deployment_id}` Deployment details + pipeline steps. GET`/deployments/{deployment_id}/logs` All deployment logs by step. GET`/deployments/{deployment_id}/build-log` Full build output - useful when a build fails. POST`/deployments/{deployment_id}/rollback` Rollback to a previous deployment (Pro+). ## Monitoring Container stats, logs, health, request metrics, sleep / wake. GET`/projects/{project_id}/stats` Container CPU, memory, and network stats. GET`/projects/{project_id}/logs` Application runtime logs (stdout/stderr). GET`/projects/{project_id}/health` Container health: status, uptime, restart count. GET`/projects/{project_id}/app-health` Live app health badge from request traffic, with deploy-step fallback. GET`/projects/{project_id}/request-metrics` Request rate, error rate, p50 / p95 / p99 latency. GET`/projects/{project_id}/deployment-stats` Success rate, average deploy duration, last deploy timestamp. POST`/projects/{project_id}/sleep` Manually put a container to sleep. POST`/projects/{project_id}/wake` Wake a sleeping container. ## Functions Serverless handlers - paste code, pick a runtime (Node.js or Python), get a public URL. Scale-to-zero, wake-on-request, optional API-key auth. GET`/functions` List your functions. POST`/functions` Create a new function. GET`/functions/{function_id}` Function details (handler code, runtime, URL, node placement). PATCH`/functions/{function_id}` Update handler code, auth mode, idle timeout, or env vars. DELETE`/functions/{function_id}` Destroy the function container, image, and DNS record. POST`/functions/{function_id}/deploy` Build and deploy the function - pulls the latest handler code from the DB. POST`/functions/{function_id}/invoke` Proxy an invocation through the backend (auto-injects API key if set). GET`/functions/{function_id}/logs` Recent container stdout / stderr. GET`/functions/{function_id}/env-vars` Return decrypted env vars for the function. GET`/functions/{function_id}/metrics` Function request metrics: requests / min, error rate, latency. POST`/functions/{function_id}/rotate-api-key` Generate a new API key (full key returned once). GET`/functions/check-name/{name}` Check whether a function slug is available. ## Add-ons Postgres and Redis add-ons. Pro+ required. GET`/projects/{project_id}/addons` List add-ons for a project. POST`/projects/{project_id}/addons` Provision a new add-on (postgres or redis). GET`/projects/{project_id}/addons/{addon_id}` Get a single add-on with connection URL. DELETE`/projects/{project_id}/addons/{addon_id}` Destroy an add-on and its data (irreversible). PATCH`/projects/{project_id}/addons/{addon_id}/auto-backup` Toggle daily auto-backup on / off. GET`/projects/{project_id}/addons/{addon_id}/backup-info` Backup plan info: retention days, daily quota, next run. ## Backups Manual and automatic backups for Postgres and Redis add-ons. GET`/projects/{project_id}/addons/{addon_id}/backups` List backups for an add-on. POST`/projects/{project_id}/addons/{addon_id}/backups` Trigger a manual backup. GET`/projects/{project_id}/addons/{addon_id}/backups/{backup_id}/download` Get a presigned download URL for a backup. DELETE`/projects/{project_id}/addons/{addon_id}/backups/{backup_id}` Delete a backup. ## Domains Custom domains (CNAME to your project subdomain on `orkestr.run`). GET`/domains` List your projects with their custom domain status. POST`/domains/{project_id}/verify` Re-check that the project domain DNS points to orkestr. ## Registry Docker registry images per project. The currently-live image is protected from deletion. GET`/projects/{project_id}/images` List images built for the project. POST`/projects/{project_id}/images/{tag}/scan` Trigger an on-demand security scan. DELETE`/projects/{project_id}/images/{tag}` Delete a built image tag. ## Activity Audit log + dashboard summary. GET`/activity` Recent activity for the current user. GET`/dashboard/summary` Project count, plan usage, recent deployments. ## Notifications In-product notifications. GET`/notifications` 50 most recent notifications. PATCH`/notifications/{notification_id}/read` Mark a notification as read. POST`/notifications/read-all` Mark all notifications as read. ## API tokens Self-service API token management. GET`/api-tokens` List your tokens (hashes only). POST`/api-tokens` Create a new token. Plaintext returned once. DELETE`/api-tokens/{token_id}` Revoke a token. ## Project groups Workspaces that bundle related projects together. GET`/groups` List your project groups. POST`/groups` Create a project group. GET`/groups/{group_id}` Get a group with its assigned projects. PATCH`/groups/{group_id}` Update a group. DELETE`/groups/{group_id}` Delete a group (projects are not deleted). POST`/groups/{group_id}/projects/{project_id}` Assign a project to a group. DELETE`/groups/{group_id}/projects/{project_id}` Remove a project from a group. ## Response codes | Status | Meaning | | --- | --- | | 200 | Success. | | 201 | Created. | | 204 | Deleted - no content. | | 400 | Bad request - invalid input. | | 401 | Unauthorized - invalid or expired token. | | 403 | Forbidden - plan limit or insufficient permissions. | | 404 | Resource not found. | | 409 | Conflict - name taken or deployment in progress. | | 429 | Rate limit exceeded. | > **More detail per endpoint** > > Need the full request body and parameter docs for a specific endpoint? Use the [CLI](https://orkestr.eu/docs/cli) - every command's `--help` mirrors the underlying REST call. Per-endpoint reference docs land in a future revision of this page. ### Next steps - [CLI](https://orkestr.eu/docs/cli) - terminal-driven workflows on top of the same API - [MCP server](https://orkestr.eu/docs/mcp) - the same endpoints exposed as tool calls for AI agents - [Workflow examples](https://orkestr.eu/docs/workflows) - PR preview, CI/CD, rollback scripts, batch operations