REST API

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 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 (Pro and Team plans).

terminal

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"}.

Rate limits

Limits are per-token, applied to the API surface (not the console).

Starter (free) - no API access
Pro - 100 requests / minute, 5 active tokens
Team - 500 requests / minute, 20 active tokens

Token format

API tokens look like ork_<random>. 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 builder output (Kaniko stderr) - 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 stored in the registry.

POST/projects/{project_id}/images/{tag}/scan

Trigger an on-demand security scan.

DELETE/projects/{project_id}/images/{tag}

Delete an image tag from the registry.

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 - every command's --help mirrors the underlying REST call. Per-endpoint reference docs land in a future revision of this page.

Next steps

CLI - terminal-driven workflows on top of the same API
MCP server - the same endpoints exposed as tool calls for AI agents
Workflow examples - PR preview, CI/CD, rollback scripts, batch operations