REST API
The team-scoped JSON API behind the CLI: apps, env, deploys, logs and servers.
A small, team-scoped JSON API for driving Railyard from a CLI, CI job, or script — list and create apps, set env, trigger deploys, read deploy logs, check the fleet.
- Base URL — your control plane, under
/api. Local Compose:http://localhost:3000/api - Format — JSON only. Send
Content-Type: application/jsonon writes. No CSRF, no session, no cookies. - Everything is scoped to one team — the team the token belongs to.
Authentication
Every request needs a bearer token:
Authorization: Bearer rly_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Get a token: dashboard → Team → API tokens → name it, pick a scope,
Create. The rly_… string is shown once — copy it then. Admin only.
Scopes
| Scope | Can |
|---|---|
read | every GET |
write | everything read can, plus POST / PATCH / DELETE |
A read-only token on a mutating endpoint → 403 {"error":"this API token is read-only"}.
Missing / bad / revoked / expired token → 401 {"error":"missing or invalid API token"}.
Revoke from the same Team page; a revoked or past-expires_at token stops
working immediately. A client can also sign itself out with
DELETE /api/session, which revokes the calling token (204).
Native apps sign in with OAuth 2.1 + PKCE (/oauth/register,
/oauth/authorize, /oauth/token). Besides https and loopback redirects,
registration accepts a reverse-DNS app scheme such as
run.railyard.ios:/oauth (RFC 8252). The token is named after the
registered client.
Sign in by QR code: Security → Railyard for iPhone shows a code that
works once and expires after 2 minutes. It encodes
railyard://signin?url=<this Railyard>&code=<code>. The app exchanges it with
POST /api/mobile_sign_in {"code": "…", "device_name": "…"}, which needs no
other credentials and returns 201 {"token": "rly_…", "scope": "write", "team": {"id": 2, "name": "…"}}.
The token belongs to the person who showed the code, is capped at their role,
and is named “Railyard for iOS”. Expired, used or unknown codes get 404, and
the endpoint allows 10 tries a minute per IP.
Conventions
- Errors — non-2xx responses are
{ "error": "<message>" }. Status codes:400bad request ·401unauthenticated ·403wrong scope ·404not found (or not in your team) ·409conflict (e.g. a deploy is already running) ·422validation failed ·429rate limit. - Timestamps — ISO-8601 UTC (
2026-09-02T14:03:11Z). - IDs — integers, stable per team.
- Pagination — list endpoints that take
limitaccept1–100(default30). No cursor yet; newest-first where ordered by time. - Rate limit — deploy creation is capped per team per hour
(
GET /api/me→limits.deploys_per_hour); over it →429. - Plans —
GET /api/mereturnsteam.plan,team.plan_name,team.features(what the plan and its add-ons include, e.g.canary,status_pages,sso) andteam.addons. Turning on a feature the plan doesn’t include answers403with a plain message naming the plan that includes it. Without a plan, adding servers or apps answers403too. - Flags —
team.flagslists the client-facing feature flags turned on for the team (today:app_notification_modes). Hide a screen when its flag is missing.
Endpoints
| Method | Path | Scope | Purpose |
|---|---|---|---|
| GET | /api/me | read | Token + team info (plan, features, add-ons), limits, counts |
| GET | /api/jobs | read | Long-running work from the last 15 minutes (backups, imports, forks, moves, upgrades, attachments…): each with kind, id, title, app, status, phase, percent, steps, eta_seconds, cancellable and error. App-restricted tokens see only their apps’ jobs |
| GET | /api/jobs/:kind/:id | read | One job, same shape — poll it to follow progress. Starting a backup, fork, upgrade, volume backup, command or server attachment returns job: {kind, id} |
| POST | /api/jobs/:kind/:id/cancel | deploy | Ask a running job to stop (202; 409 when that job can’t be cancelled) |
| DELETE | /api/session | read | Revoke the calling token (sign out) |
| GET | /api/mobile_devices | read | Devices registered with this token |
| POST | /api/mobile_devices | read | Register this device for push (upserts by APNs token) |
| PATCH | /api/mobile_devices/:id | read | Choose which events reach the device |
| DELETE | /api/mobile_devices/:id | read | Stop pushing to the device |
| GET | /api/status_pages | read | The team’s customer status pages with overall status and open incident counts |
| GET | /api/status_pages/:id | read | One page: components with 30 days of uptime, and its last 20 incidents with updates |
| POST | /api/status_pages | write (admin) | Create a page (title, slug, application_ids) |
| PATCH | /api/status_pages/:id | write (admin) | Change title, description or published |
| DELETE | /api/status_pages/:id | write (admin) | Delete a page and its incident history |
| POST | /api/status_pages/:id/components | write (admin) | Add an app to the page (application_id, optional name) |
| DELETE | /api/status_pages/:id/components/:component_id | write (admin) | Remove an app from the page |
| POST | /api/status_pages/:id/incidents | write (admin) | Open an incident (title, impact, status, body, optional application_id) |
| POST | /api/status_pages/:id/incidents/:incident_id/updates | write (admin) | Post an update (status, body); resolved closes it |
| POST | /api/device_challenges | read (token with a registered phone) | A single-use nonce (5 minutes) for a phone-signed action: for is create_token or remove_passkey |
| POST | /api/api_tokens | write (admin) + phone signature | Create a token (name, scope, optional application_id, expires_in_days) with nonce, device_id and signature: ES256 by the phone’s Secure Enclave key over `railyard-create_token:<team_id>: |
| POST | /api/account/authenticator/setup | phone signature | Start setting up an authenticator app (signed over railyard-setup_authenticator:<team_id>:<nonce>:setup); returns the secret and otpauth:// uri |
| POST/DELETE | /api/account/authenticator | token made by a person | Turn the authenticator on with a current code (returns backup codes) or off with a current code |
| POST | /api/account/passkeys/options | phone signature | WebAuthn creation options for a new passkey (signed over railyard-add_passkey:<team_id>:<nonce>:options), with rp_id |
| POST | /api/account/passkeys | token made by a person | Finish adding a passkey: name and the WebAuthn credential (id, rawId, type, response.clientDataJSON, response.attestationObject) |
| DELETE | /api/account/passkeys/:id | phone signature | Remove one of your passkeys, signed over railyard-remove_passkey:<team_id>:<nonce>:<id> |
| DELETE | /api/account | phone signature | Delete your account, signed over railyard-delete_account:<team_id>:<nonce>:<your email>; no password needed. Same rules as the web: teams where you’re the only member close with it, a team you share needs another owner first (422), and your sessions and API tokens stop working |
| GET | /api/api_tokens | write (admin) | The team’s live tokens: name, masked value, scope, app, who made it, last used, expiry, phones signed in with it |
| DELETE | /api/api_tokens/:id | write (admin) | Revoke a token straight away (not the calling one; use DELETE /api/session for that) |
| GET | /api/account/security | read (token made by a person) | The token owner’s email, two-factor status, passkeys and active web sessions |
| DELETE | /api/account/sessions/:id | read (token made by a person) | Sign the token owner out of one web session |
| DELETE | /api/account/sessions | read (token made by a person) | Sign the token owner out of every web session (API tokens keep working) |
| GET | /api/ssh_keys | read (whole-team token) | The team’s SSH public keys: name, fingerprint, who added them |
| POST | /api/ssh_keys | write (admin) | Add an OpenSSH public key (public_key, optional name) |
| DELETE | /api/ssh_keys/:id | write (admin) | Remove an SSH key |
| GET | /api/applications/:id/networking | read | IP allow and block lists, password protection (never the password), path routes and published ports |
| PATCH | /api/applications/:id/ip_rules | write (admin) | Replace ip_allowlist and ip_denylist (addresses or CIDR ranges) |
| PUT/DELETE | /api/applications/:id/password | write (admin) | Password protect the app (user, password) or remove it |
| POST/DELETE | /api/applications/:id/path_routes[/:route_id] | write (admin) | Route host + path_prefix (another app’s address on the same server) to this app; strip_prefix |
| POST/DELETE | /api/applications/:id/published_ports[/:port_id] | write (admin) | Publish ports (5432 or 7000-7010) over protocol tcp or udp, optional public_port and trusted_sources |
| GET/PATCH/DELETE | /api/backup_destination | read / write (admin) | The team’s own backup bucket: show (never the keys), set provider, endpoint, region, bucket, prefix, access_key_id, secret_access_key (checked before use), or stop using it |
| POST | /api/imports | write (admin) | Start an import from platform (heroku, render, fly, railway) with an API token (kept encrypted 30 minutes); returns the apps found |
| GET | /api/imports/:id/apps/:source_id | write (admin) | What would come across: repo, branch, image, port, variable names, add-ons, domains, whether there’s a database, notes; never variable values or the database URL |
| POST | /api/imports/:id/apps/:source_id | write (admin) | Import it onto server_id (optional git_url, copy_data); returns the new app and its first deploy |
| GET | /api/canvas | read (whole-team token) | The canvas graph: nodes (servers, apps, databases, add-ons with status, traffic and load) and edges (data links, environments) |
| GET | /api/operator/support_conversations | operator token | Railyard operators only: support conversations (filter unread, open, mine, unassigned, website, closed) |
| GET | /api/operator/support_conversations/:id | operator token | A conversation’s messages; marks it read |
| POST | /api/operator/support_conversations/:id/reply | operator write token | Reply as support (body) |
| GET | /api/members | read | Team members, pending invitations and what the caller may change |
| PATCH | /api/members/:id | write (admin) | Change a member’s role or the apps they can see |
| DELETE | /api/members/:id | write (admin) | Remove a member from the team |
| POST | /api/invitations | write (admin) | Invite someone by email (existing Railyard users join straight away) |
| POST | /api/invitations/:id/resend | write (admin) | Send a pending invitation again and restart its 14 days |
| DELETE | /api/invitations/:id | write (admin) | Revoke a pending invitation |
| POST | /api/acknowledgements | read | Record that you’ve seen an alert ({"key":"deploy-41"}) |
| GET | /api/activities | read | Team activity as sentences, newest first (?application_id=, ?before=<id>, ?locale=) |
| GET | /api/approval_requests | read | Pending approval requests from agents |
| POST | /api/approval_requests/:id/approve | write, admin | Approve with a device signature ({"device_id":9,"signature":"…"}) |
| POST | /api/approval_requests/:id/reject | write, admin | Reject |
| GET | /api/applications | read | List apps |
| POST | /api/applications | write | Create an app |
| GET | /api/applications/:id | read | App detail |
| PATCH | /api/applications/:id | write | Update an app |
| DELETE | /api/applications/:id | write | Delete an app (and its deploys/logs) |
| POST | /api/applications/:id/archive | write | Stop the container, keep the record |
| POST | /api/applications/:id/unarchive | write | Un-archive |
| GET | /api/applications/:id/env | read | Read env vars |
| PATCH | /api/applications/:id/env | write | Merge env vars (null value deletes) |
| DELETE | /api/applications/:id/env?key=KEY | write | Delete one env var |
| GET | /api/applications/:id/edge | read | Edge settings (same shape as the manifest’s edge: section, see Edge rules) |
| PATCH | /api/applications/:id/edge | write | Merge edge settings: {"edge":{"access_logs":false,"headers":[…],"cors":{…}}} |
| GET | /api/applications/:id/certificates | read | Uploaded certificates (names, covered hosts, validity, fingerprint; never the key) |
| POST | /api/applications/:id/certificates | write | Upload {"certificate":{"certificate_pem":"…","private_key_pem":"…"}} |
| DELETE | /api/applications/:id/certificates/:cert_id | write | Remove one (automatic certificates after the next deploy) |
| GET | /api/applications/:id/domains | read | List custom domains |
| POST | /api/applications/:id/domains | write | Add a custom domain |
| DELETE | /api/applications/:id/domains/:domain_id | write | Remove a custom domain |
| POST | /api/applications/:id/domains/:domain_id/check | write | Re-check DNS and the certificate now; returns the domain with its fresh status (unverified, pending, unrouted, misconfigured or live) |
| GET | /api/applications/:id/deploys | read | Deploys for one app |
| POST | /api/applications/:id/deploys | write | Trigger a deploy ({"image": "registry/repo:tag"} deploys that prebuilt image once) |
| GET | /api/applications/:id/registry | write | The team’s build registry for deploy --local: repository, username, password, platform |
| POST | /api/applications/:id/tunnel | write | Open a tunnel ({"target": "web|db|redis|<process>", "local_port": 5432}): returns a 12-hour ticket for the TunnelChannel WebSocket, the remote port, and a localhost url for databases; logged as app.tunnel_opened |
| POST | /api/applications/:id/console | write (team admin) | Open an interactive console ({"process": "web", "shell": "sh|bash|rails|tinker|django|node|python|auto"}; auto picks the framework console): returns a 2-minute ticket for the ExecChannel WebSocket; logged as app.console_opened |
| POST | /api/servers/:id/console | write (team owner, whole-team token) | Same, for a root shell on the server; logged as server.console_opened |
| GET | /api/applications/:id/logs | read | Runtime container logs (?tail=, ?process=) |
| GET | /api/applications/:id/processes | read | Per-container state (for ps) |
| POST | /api/applications/:id/restart | write | Bounce every container, or one ?process= |
| GET | /api/applications/:id/process_types | read | Process types with env, shutdown and size settings |
| PATCH | /api/applications/:id/process_types/:pt_id | write | Set env_vars_text, kill_timeout_seconds, stop_signal, size, cpu_limit, memory_limit |
| GET | /api/applications/:id/commands | read | Recent one-off command runs |
| POST | /api/applications/:id/commands | write | Run a one-off command ({"command": "..."}) |
| GET | /api/applications/:id/commands/:cmd_id | read | One run: status, output, exit code |
| POST | /api/applications/:id/reindex | write | Rebuild the search indices: runs the app’s search.reindex_command in a one-off container (202; 422 without a command or a successful deploy, 409 while one runs). Set reindex_command / auto_reindex with PATCH /api/applications/:id; GET shows them under search with the detected library |
| POST | /api/applications/:id/clone | write | Clone the app into a staging copy |
| POST | /api/applications/:id/promote | write | Promote a staging app’s release to production |
| GET | /api/applications/:id/manifest | read | The app as railyard.yml (?secrets=true includes variable values) |
| POST | /api/applications/:id/apply_manifest | write | Apply a manifest ({"manifest": "<yaml text>"}) |
| POST | /api/applications/validate_manifest | read | Check a manifest for mistakes without applying it — no :id, any app’s token works ({"manifest": "<yaml text>"} → {"problems": [...]}, empty when it’s valid) |
| POST | /api/applications/:id/db_query | write | Run SQL ({"sql": "...", "write": false, "engine": "postgres"}). Reads run in a read-only transaction; write: true allows changes and is logged. Needs a write-scoped token for both, like the web console (admins) and the MCP tools. Returns columns, rows (up to 500), row_count, truncated, ms, command, or error |
| GET | /api/applications/:id/db_tables | write | The app database’s tables, largest first: {engine, database, tables: [{schema, name, rows, bytes}]} (rows/bytes may be strings) |
| GET | /api/applications/:id/db_insights | write | Postgres health: stats (cache_hit, index_hit, connections, max_connections, db_bytes), running queries, unused_indexes, seq_scans, and slow (from pg_stat_statements, null when it isn’t enabled) |
| GET | /api/applications/:id/db_locks | write | Queries waiting on a lock and the query holding it: {locks: [{blocked_pid, blocked_query, waiting_seconds, blocking_pid, blocking_state, blocking_query}]} |
| POST | /api/applications/:id/db_cancel | write | Stop a query ({"pid": 123, "force": false}; force ends the whole connection); logged as db.query_stopped |
| GET | /api/applications/:id/database_imports | read | The 20 most recent imports with status, phase and percent |
| POST | /api/applications/:id/database_imports/uploads | write | Start a direct upload of a dump ({"filename", "byte_size"}, up to 5 GB): returns key, upload_id, part_size and one presigned urls entry per part to PUT |
| GET | /api/applications/:id/database_imports/uploads/:upload_id | write | Resume one (?key=&byte_size=): done part numbers and fresh parts: [{number, url}] for the rest |
| POST | /api/applications/:id/database_imports | write | Start an import from an upload (object_key, upload_id, byte_size, filename) or a source_url; mode replace (default, needs confirm = the app name when data exists) or add; backup_first and deploy_after default to true. Returns the import with a job to follow |
| GET/POST | /api/applications/:id/database_backups | read / write | List backups / take one now |
| POST | /api/database_backups/:id/restore | write | Restore a backup |
| GET | /api/database_backups/:id/download | read | Signed download link |
| GET/POST | /api/applications/:id/volume_backups | read / write | List backups / back up one volume ({"volume": "name"}) |
| POST | /api/volume_backups/:id/restore | write | Restore a volume backup |
| GET | /api/applications/:id/traffic | read | Requests, p95, error rate and slowest endpoints (?range=1h|24h|7d|30d) |
| PATCH | /api/applications/:id/autoscale | write | Scale web replicas on p95/CPU ({"max":N,"min":N,"p95":ms,"cpu":pct}); {"max":null} turns it off |
| POST | /api/applications/:id/data_move | write | Move the app’s data to a database server ({"database_server_id": 12}); 202 with what gets copied |
| POST | /api/applications/:id/external_datastores | write | Point the app’s database, redis or elasticsearch at an outside URL ({"kind","url","copy"}); the URL is checked first (502 if unreachable), 202 when queued |
| DELETE | /api/applications/:id/external_datastores/:kind | write | Bring that data back under Railyard (?copy=true copies it back) |
| GET | /api/applications/:id/addons/:kind/transfers | read | Recent exports/imports of an add-on (redis, mongodb, elasticsearch, storage, influxdb, rabbitmq), with download links |
| POST | /api/applications/:id/addons/:kind/transfers | write | Export the add-on’s data; with multipart file + confirm=<app name>, load a file into it |
| GET | /api/applications/:id/storage/objects | read | Browse the storage add-on’s bucket (?prefix=, ?token=): folders, files with size, public flag and a signed link |
| POST | /api/applications/:id/storage/objects | write | Upload a file (multipart file, prefix or key) |
| DELETE | /api/applications/:id/storage/object?key= | write | Delete a file, or a folder when the key ends in / |
| PATCH | /api/applications/:id/storage/visibility | write | Make a folder public or private ({"prefix":"avatars/","public":true}) |
| GET | /api/applications/:id/redis | read | Where the app’s Redis lives (shared db N or its own), its limit and policy, memory used |
| PATCH | /api/applications/:id/redis | write | {"dedicated":true,"maxmemory_mb":512,"policy":"allkeys-lru"} gives the app its own Redis (keys copied) or changes its limit; {"dedicated":false} moves it back |
| GET | /api/deploys | read | Deploys across the team (?application_id=, ?limit=) |
| GET | /api/deploys/:id | read | Deploy detail |
| GET | /api/deploys/:id/logs | read | Deploy log lines (oldest first, ≤5000; ?after=<id> pages forward 2000 at a time) |
| GET | /api/applications/:id/log_search | read | Stored log lines: time range, search, cursor pages (see Logs, metrics and alerts) |
| GET | /api/applications/:id/log_download | read | Stored log lines for a range as text |
| GET/PATCH/DELETE | /api/applications/:id/otel_export | read / write | OpenTelemetry export settings (see Logs, metrics and alerts) |
| GET/POST | /api/applications/:id/metric_alerts | read / write | Metric threshold alerts and their history |
| PATCH/DELETE | /api/applications/:id/metric_alerts/:alert_id | write | Change or remove an alert |
| GET | /api/applications/:id/job_queue | read | Job queue stats, failed jobs, history (see Logs, metrics and alerts) |
| POST | /api/applications/:id/job_queue/failed/:job_id/retry | write | Retry a failed job |
| DELETE | /api/applications/:id/job_queue/failed/:job_id | write | Discard a failed job |
| GET | /api/servers | read | The fleet |
| GET | /api/servers/:id | read | Server detail + live process states |
| GET | /api/servers/:id/metrics | read | CPU/memory/disk series (?range=live|1h|6h|24h|7d|30d) |
| GET | /api/costs | read | The team’s cloud spend: forecast, budget, month to date and daily spend per provider, each server’s monthly cost and load, and savings Railyard found |
| POST | /api/costs/scan | write | Refresh the spend report from the connected cloud accounts (202; one scan at a time) |
| GET | /api/cloud_connections | write | The team’s connected cloud accounts, with the regions, sizes (and monthly prices) and operating systems each can create |
| GET | /api/providers | read | Every cloud provider with label, connected (whether the team linked an account), default_region, default_size, and regions/sizes as [{slug, name}] |
| POST | /api/server_attachments | write | Create a server through a connected cloud account ({"provider":"vultr","region":"fra","size":"vc2-2c-4gb","os":"ubuntu"}) — 202 with the setup |
| GET | /api/server_attachments[/:id] | read | Server setups in flight (or failed in the last day), with live progress |
| POST | /api/servers/:id/reboot | /power_cycle | /cordon | /uncordon | /prune_docker | write | Server lifecycle actions |
| PATCH | /api/servers/:id/resize | write | Resize at the provider ({"size": "..."}) |
| POST | /api/servers/:id/trust_ip | write | Unban and trust an IP ({"ip": "..."}) — ActiveProtect lifts the ban within ~1 min. Lets Watchtower clear a ban without opening the dashboard. |
| GET/POST | /api/applications/:id/deploy_hooks | read / write | Deploy hooks; create with {"deploy_hook":{"stage":"before_release|after_release|after_deploy","command":"…"}} |
| DELETE | /api/applications/:id/deploy_hooks/:hook_id | write | Remove a hook |
| GET/POST | /api/applications/:id/log_drains | read / write | Log drains; create with {"log_drain":{"kind":"https_json|syslog","url":"…"}} |
| DELETE | /api/applications/:id/log_drains/:drain_id | write | Remove a drain |
| GET/POST | /api/applications/:id/secret_files | read / write | Files mounted into the app’s containers; create with {"secret_file":{"name":"…","content":"…"}} (content is never returned) |
| DELETE | /api/applications/:id/secret_files/:file_id | write | Remove a file |
| GET | /api/applications/:id/scheduled_tasks | read | Cron tasks with schedule, command and last status |
| POST | /api/applications/:id/scheduled_tasks/:task_id/run | write | Run one now |
| PATCH | /api/applications/:id/auto_deploy | write | {"auto_deploy":true} deploys every push to the tracked branch; returns the webhook_url |
| POST | /api/applications/:id/auto_deploy/regenerate | write | Issue a new push webhook URL |
| POST | /api/applications/:id/maintenance | write | {"on":true} shows the maintenance page instead of the app (queues a deploy); {"on":false} brings it back |
| PATCH | /api/applications/:id/scale | write | Replicas for non-web processes ({"replicas":{"worker":3}}); web replicas come from autoscale or the app’s web_replicas |
| PATCH | /api/applications/:id/sleep | write | Stop when idle and wake on the next request ({"minutes":30}; null turns it off) |
| POST | /api/applications/:id/wake | write | Wake a sleeping app now |
| PATCH | /api/applications/:id/deploy_window | write | {"days":["mon","tue"],"start":"09:00","end":"17:00","time_zone":"America/Toronto"}; no days clears it |
| POST | /api/applications/:id/create_environment | write | Clone the app into a new environment ({"environment":"staging","git_ref":"main"}) |
| POST | /api/applications/:id/apply_profile | write | Apply a deployment profile ({"profile_id":4}) |
| PATCH | /api/applications/:id/database | write | Backup policy of the managed database ({"engine":"postgres","app_database":{"backup_interval_hours":6,"backup_keep":20,"backup_keep_days":30,"verify_backups":true,"pooled":false}}) |
| POST | /api/applications/:id/database/reset | write | Drop and recreate it ({"engine":"postgres","confirm":"<app name>"}) — irreversible |
| GET/DELETE | /api/applications/:id/database_forks/:fork_id | read / write | One fork / drop it (GET/POST /api/applications/:id/database_forks lists and creates them, see below) |
| GET/POST | /api/deployment_profiles | read / write | Deployment profiles shared by apps ({"deployment_profile":{"name","build_method","release_command","health_path","docker_build_target","dockerfile_path","cpu_limit","memory_limit","container_port"}}) |
| PATCH/DELETE | /api/deployment_profiles/:id | write | Change or remove one |
| POST | /api/servers/:id/standby_rejoin | write | Re-attach a server that lost a database failover as a standby of the new primary (202 with the engines) |
| POST | /api/servers/:id/block_ip | /unblock_ip | write | Block or unblock an IP on the server’s firewall ({"ip":"…"}) |
| GET/PATCH | /api/servers/:id/maintenance_window | read / write | Per-server data maintenance window (same shape as the team one) |
| GET/POST | /api/notification_rules | read / write (whole-team token) | Notification rules; create with kind (slack, discord, telegram, webhook, email, sms), endpoint, optional application_id and on_* flags (on_deploy_failure, on_server_offline, on_app_down, on_metric_alert, …) |
| PATCH/DELETE | /api/notification_rules/:id | write (whole-team token) | Change (enabled, flags) or remove a rule |
| PATCH | /api/applications/:id/notification_mode | write | Which rules notify about the app: team, own or muted (flag app_notification_modes) |
| GET/POST | /api/webhook_endpoints | read / write | Webhook endpoints; create with {"url":"https://…","events":["deploy.started","deploy.approved"],"application_id":null} |
| PATCH/DELETE | /api/webhook_endpoints/:id | write | Change (url, events, enabled) or remove an endpoint |
| GET/POST | /api/config | read / write | Team-wide config entries; set with {"key":"REGION","value":"eu","secret":true,"description":"…"} (POST on an existing key updates it) |
| DELETE | /api/config/:key | write | Remove an entry |
| POST | /api/cli/auth | none | Start a CLI sign-in: returns a code and the url to confirm it in the browser |
| GET | /api/cli/auth/:code | none | Polled by the CLI: {"status":"pending"} until confirmed, then the token |
GET /api/me
curl -s https://cp.example.com/api/me -H "Authorization: Bearer $RLY"
{
"team": { "id": 1, "name": "Acme", "slug": "acme", "suspended": false, "plan": "scale", "plan_name": "Scale", "features": ["canary"], "addons": [], "flags": ["app_notification_modes"] },
"user": { "email": "ops@acme.test", "role": "admin" },
"token": { "name": "ci", "scope": "write", "effective_scope": "write", "application_id": null, "last_used_at": "2026-09-02T14:00:00Z" },
"limits": { "servers": 10, "apps": 50, "deploys_per_hour": 30, "included_servers": 5, "included_seats": 5 },
"counts": { "applications": 11, "servers": 3 }
}
effective_scope is the scope the token acts with today: it is capped at the
issuing member’s current role. user is null for tokens with no issuer.
Applications
app object (list form):
{
"id": 11,
"name": "chatwoot-copy",
"environment": "production",
"parent_id": null,
"git_url": "image://chatwoot/chatwoot:v4.17.1",
"git_ref": "main",
"hostname": "chatwoot-copy.apps.example.com",
"url": "https://chatwoot-copy.apps.example.com",
"server": "railyard-8",
"container_port": 3000,
"addons": ["postgres", "redis"],
"maintenance_mode": false,
"parent_id": null, "preview_pr": null,
"sleep_after_minutes": null, "sleeping": false,
"archived": false,
"auto_deploy": false,
"latest_deploy": { "id": 31, "status": "succeeded", "sha": null, "created_at": "2026-09-02T13:00:00Z" },
"created_at": "2026-09-01T09:00:00Z"
}
parent_id is the production app an environment belongs to (null for production), and preview_pr the pull request number of a preview. sleep_after_minutes is when the app sleeps when idle (null = never) and sleeping whether it’s asleep now.
GET /api/applications/:id adds: autoscale ({min, max, p95_ms, cpu}; max null or equal to min means off), release_command, health_path,
deploy_approval_required, deploy_window {days, start, end, time_zone, open_now, opens_at}, strict_pushes, db_extensions[],
processes[] {name, command, role}, env_keys[] (names only — values are
never returned in app detail; use the env endpoint),
domains[] {hostname, redirect, cert_state}.
Create — POST /api/applications
curl -s -X POST https://cp.example.com/api/applications \
-H "Authorization: Bearer $RLY" -H "Content-Type: application/json" \
-d '{"application":{
"name":"blog",
"git_url":"https://github.com/acme/blog",
"git_ref":"main",
"container_port":3000,
"server":"railyard-8",
"addons":["postgres"],
"env_vars":{"RAILS_ENV":"production"}
}}'
Body is {"application": { … }}. Accepted keys: name, git_url,
git_ref, container_port, hostname, health_path, release_command,
build_method (auto | dockerfile | nixpacks), dockerfile_path,
docker_build_target, cpu_limit, memory_limit, process_types_text
(one name: command per line), scheduled_tasks_text
(name | cron | command per line), db_extensions,
deploy_approval_required, strict_pushes (a git push whose build
fails is rejected; default true), disable_no_new_privileges (for images
that switch users on boot), addons (array), env_vars (object).
On update also: server_id.
server(orserver_id) may be a server id or hostname. Omit it and the app lands on the first uncordoned server in the team.- Blank
hostnameis derived —<name>.<server app_domain>, elseAPP_DOMAIN_SUFFIX, else<name>.<server-ip>.sslip.io. - Creating does not deploy. Follow with
POST …/deploys. - Over the team app limit →
422.
201 with the detailed app object. PATCH → 200. DELETE → 204.
Archive / unarchive — POST /api/applications/:id/archive stops the
running container and sets archived: true; the record, config and history
stay. unarchive clears the flag (redeploy to bring it back).
Env vars — /api/applications/:id/env
# read
curl -s https://cp.example.com/api/applications/11/env -H "Authorization: Bearer $RLY"
# {"env":{"RAILS_ENV":"production","LOG_LEVEL":"info"}}
# merge (set two, delete one)
curl -s -X PATCH https://cp.example.com/api/applications/11/env \
-H "Authorization: Bearer $RLY" -H "Content-Type: application/json" \
-d '{"env":{"LOG_LEVEL":"debug","FEATURE_X":"1","OLD_KEY":null}}'
# delete one
curl -s -X DELETE "https://cp.example.com/api/applications/11/env?key=FEATURE_X" \
-H "Authorization: Bearer $RLY"
PATCH merges into the existing set; a null value removes that key.
All three return the full {"env": { … }}. Changes take effect on the next
deploy.
Custom domains — /api/applications/:id/domains
curl -s -X POST https://cp.example.com/api/applications/11/domains \
-H "Authorization: Bearer $RLY" -H "Content-Type: application/json" \
-d '{"domain":{"hostname":"support.acme.com","redirect":false}}'
{ "id": 4, "hostname": "support.acme.com", "redirect": false,
"cert_state": "pending", "dns_target": "203.0.113.9", "cert_issuer": null }
redirect: true makes the hostname 301 to the app’s primary hostname
instead of serving it. Point the shown dns_target at your DNS and Caddy
issues the cert. DELETE …/domains/:domain_id → 204.
Deploys
deploy object:
{
"id": 31, "application_id": 11, "application": "chatwoot-copy",
"status": "succeeded", "ref": "main", "trigger": "manual", "message": null, "sha": null, "rollback": false,
"created_at": "2026-09-02T13:00:00Z",
"started_at": "2026-09-02T13:00:04Z",
"finished_at": "2026-09-02T13:02:31Z"
}
status ∈ queued · pending_approval · running · succeeded ·
failed. GET /api/deploys/:id adds error, triggered_by (email),
duration_seconds and diagnosis. diagnosis is null unless the deploy
failed:
"diagnosis": {
"known": true,
"title": "STRIPE_SECRET_KEY isn't set",
"fix": "The app reads STRIPE_SECRET_KEY with ENV.fetch and stops at boot when it isn't set. Add it under Variables, then deploy again.",
"action": "env",
"variable": "STRIPE_SECRET_KEY",
"evidence": "KeyError: key not found: \"STRIPE_SECRET_KEY\""
}
action says where the fix lives (env, settings, …); with env,
variable names the variable to set.
A canary deploy also has a canary object (null otherwise):
"canary": {
"percent": 10, "state": "running", "started_at": "2026-09-29T12:00:00Z",
"promote_at": "2026-09-29T12:15:00Z", "requests": 412, "error_rate": 0.49, "p95_ms": 88.4,
"rest_of_app": { "requests": 3710, "error_rate": 0.4, "p95_ms": 91.0 }
}
state ∈ running · promoted · rolled_back · replaced.
Canary — POST /api/deploys/:id/canary/promote starts the promotion
deploy (202, promotion_deploy_id); DELETE /api/deploys/:id/canary
rolls it back. Both need a write token and answer 409 once the canary is
no longer live.
Notification mode — PATCH /api/applications/:id/notification_mode with
notification_mode: team (team-wide rules and the app’s own rules, the default),
own (only the app’s own rules) or muted (nothing). Approval requests always go out,
and events that aren’t about one app (servers, costs) are never affected. Needs a write
token; answers { "id": 12, "name": "shop", "notification_mode": "own" }. notification_mode is also
accepted by PATCH /api/applications/:id and shown by GET /api/applications/:id.
While the app_notification_modes flag is off for the team, writes answer 403.
Deploy strategy — PATCH /api/applications/:id/deploy_strategy with any
of deploy_strategy (standard · canary), canary_percent (1–99),
canary_steps_text (comma-separated ascending percentages, e.g. "5, 25, 50";
blank = one step), canary_promote_after_minutes (1–1440, empty = by hand),
canary_max_error_rate (0–100). GET /api/applications/:id shows the same
fields. With steps set, promoting a step starts the next step as its own
canary instead of going straight to 100%.
Redeploy when the image changes (image apps only, else 422) —
PATCH /api/applications/:id/image_watch with enabled (true/false);
POST /api/applications/:id/image_watch/check checks the registry now
(202). Both return, and GET /api/applications/:id shows as
image_watch:
{ "enabled": true, "image": "ghcr.io/acme/api:prod",
"webhook_url": "https://cp.example.com/webhooks/image/2cV…",
"digest": "sha256:fb84…", "checked_at": "2026-09-29T12:05:00Z", "error": null }
Registries call POST /webhooks/image/<token> (no API token; any body) to
trigger a check.
Trigger — POST /api/applications/:id/deploys
curl -s -X POST https://cp.example.com/api/applications/11/deploys \
-H "Authorization: Bearer $RLY" -H "Content-Type: application/json" \
-d '{"ref":"v2.1.0"}'
ref(optional) — branch, tag, or SHA to deploy once; defaults to the app’sgit_ref, which arefnever changes. The deploy’striggerisrefand itsreffield shows what it used. Names with characters git refs can’t have get422. Ignored for animage://app.message(optional) — a deploy note (up to 500 characters), returned asmessageand shown in the dashboard, activity, notifications and thedeploy.*webhooks.at(optional) — ISO 8601 time to deploy at instead of now. Answers201withstatus: "scheduled"andscheduled_for; the time must be in the future and inside the deploy window (422otherwise). Cancel it withPOST /api/deploys/:id/cancel(also cancels a queued or running deploy).ignore_window(optional) — deploy even though the app is outside its deploy window. Without it such a deploy answers409withoutside_window: trueandwindow_opens_at.rollback_to(optional) — id of an earlier succeeded deploy. Redeploys its commit and puts back the variables it ran with; the response addsrestored_config. Send"restore_config": falseto roll back the code only. Releases deployed before Railyard kept a copy of their variables always roll back code only.202 Accepted+ the deploy object when it’s queued and running.200 OK+ the object withstatus: "pending_approval"if the app requires deploy approval (approve it in the dashboard).409if a deploy is already active or awaiting approval for that app.429if the team’s deploys-per-hour limit is hit.422if the app is archived.422withmissing_env(array of names) if the app has never deployed successfully and credentials its repo documents are unset or still placeholders. Set them via the env endpoint, or send"force": trueto deploy anyway — those names aren’t asked for again.
Deploy window — PATCH /api/applications/:id/deploy_window
curl -s -X PATCH https://cp.example.com/api/applications/11/deploy_window \
-H "Authorization: Bearer $RLY" -H "Content-Type: application/json" \
-d '{"days":["mon","tue","wed","thu","fri"],"start":"09:00","end":"17:00","time_zone":"America/Toronto"}'
Returns {days, start, end, time_zone, open_now, opens_at} (also under
deploy_window in GET /api/applications/:id). "days": [] removes the
window. Pushes, GitHub/GitLab webhooks and coalesced pushes outside the
window become one scheduled deploy that starts when it opens.
Logs — GET /api/deploys/:id/logs
{
"deploy_id": 31,
"status": "succeeded",
"lines": [
{ "stream": "system", "line": "Deploying web (web)", "at": "2026-09-02T13:00:05Z" },
{ "stream": "stdout", "line": "Pulled chatwoot/chatwoot:v4.17.1", "at": "2026-09-02T13:00:40Z" },
{ "stream": "system", "line": "Deployed at https://chatwoot-copy.apps.example.com", "at": "2026-09-02T13:02:30Z" }
]
}
stream ∈ stdout · stderr · system. Capped at 5000 lines, oldest
first. Poll while status is queued/running.
Each line has an id. To follow a running deploy, pass ?after=<id>
(start with after=0). The response holds up to 2000 lines with a higher
id, plus next_after to use on the next call. Stop when status is
final and a page comes back with fewer than 2000 lines.
List — GET /api/deploys?application_id=11&limit=50 or
GET /api/applications/11/deploys.
Runtime — logs, processes, commands, restart
The programmatic half of the app-page console. Everything here goes to the agent on the box over an mTLS channel.
Runtime logs — GET /api/applications/:id/logs?tail=200&process=web
What the running app is printing now — not the build output (that’s
/api/deploys/:id/logs). tail is 1–5000 (default 200); process filters to
one process. 409 with {"error": "No running deployment"} when nothing is
up yet, or the agent is unreachable.
Live logs over a socket: connect to wss://<host>/cable with
Authorization: Bearer rly_… and subscribe to
{"channel":"AppLogsChannel","application_id":11,"tail":500} (ActionCable
protocol). Messages are {"type":"status","state":"streaming"} or
{"type":"line","stream":"stdout","process":"web","at":"…","line":"…"}.
App-scoped tokens and limited members only reach their own apps.
{
"application_id": 11,
"lines": [
{ "stream": "stdout", "process": "web", "line": "GET / 200 12ms", "at": "2026-09-06T12:00:01Z" }
]
}
There is no server-push follow yet — railyard logs --follow re-requests on
an interval.
Processes — GET /api/applications/:id/processes
Last-reported state of every container, refreshed each agent heartbeat. Empty list = nothing running.
{ "processes": [
{ "name": "web", "container": "railyard-app-11-web", "state": "running",
"status": "running", "health": "healthy", "crash_looping": false,
"restarts": 0, "cpu_percent": 1.2, "mem_bytes": 92210000,
"mem_percent": 44.1, "last_seen_at": "2026-09-06T12:00:00Z" } ] }
status ∈ running · unhealthy · crash-looping · exited · dead · …
Restart — POST /api/applications/:id/restart[?process=web]
Bounces every container, or just one process’s. 409 if nothing is running.
{ "restarted": 2, "processes": ["railyard-app-11-web", "railyard-app-11-worker-1"] }
Process types — GET /api/applications/:id/process_types,
PATCH /api/applications/:id/process_types/:pt_id
{ "id": 7, "name": "worker", "role": "worker", "command": "bundle exec sidekiq",
"replicas": 2, "env_vars": {}, "kill_timeout_seconds": 30, "stop_signal": "",
"size": "small", "cpu_limit": "0.5", "memory_limit": "512m", "cpus": "0.5", "memory": "512m" }
size is small, medium, large (mapped from PROCESS_SIZE_*), custom
(then send cpu_limit and memory_limit) or blank for the app-wide limit.
cpus / memory are the effective limits after that fallback.
kill_timeout_seconds (1–300, blank for the default) is how long the process
gets after stop_signal (SIGTERM, SIGINT, SIGQUIT, blank for the
image’s own) before it is killed. Changes apply on the next deploy. An invalid
value → 422.
One-off commands — POST /api/applications/:id/commands
curl -s -X POST https://cp.example.com/api/applications/11/commands \
-H "Authorization: Bearer $RLY" -H "Content-Type: application/json" \
-d '{"command":"bin/rails db:migrate"}'
Runs inside the web container via the agent’s RunTask RPC. 202 Accepted
with the row; poll GET /api/applications/:id/commands/:cmd_id for status
(queued → running → succeeded/failed), streamed output, and
exit_code. GET /api/applications/:id/commands lists recent runs.
Interactive console (a TTY, Exec RPC) is not in the API yet.
Servers
curl -s https://cp.example.com/api/servers -H "Authorization: Bearer $RLY"
server object:
{
"id": 5, "hostname": "railyard-8", "name": "railyard-8",
"status": "online",
"agent_version": "20260902-a9821d1",
"cpu_percent": 1.5, "memory_percent": 64.5, "disk_percent": 40.3,
"last_heartbeat_at": "2026-09-02T14:03:00Z",
"cordoned": false,
"provider": "hetzner", "region": "fsn1", "size": "cx42", "cloud": true
}
status ∈ online (heartbeat < 30 s) · stale (< 5 min) · offline.
provider is the cloud the server was created in (null for a machine you
attached yourself), with its region and size slugs; cloud is true when Railyard created it there, so
power-cycling and resizing work on it.
GET /api/servers/:id adds apps[] (names) and
processes[] {container, state, restarts, crash_looping}, and, for tokens
that cover the whole team, protection {active, bans[] {ip, reason, hits, expires_at}, blocked_ips[], trusted_ips[]}: what ActiveProtect is blocking
right now and the team’s own block and trust lists. Unban with
POST /api/servers/:id/trust_ip; block or unblock everywhere with
POST /api/servers/block_ip / unblock_ip.
GET /api/servers/:id/metrics?range=1h returns the same series the server
page charts: t[] (bucket start, unix seconds) and series keyed by metric
(cpu_percent, memory_percent, disk_percent, load1, mem_used_bytes,
…). Each array lines up with t; null means no sample in that bucket.
apps[] {id, name, cpu[], mem[]} lists only the apps the token can see.
Cordoning, rebooting, power-cycling, pruning and resizing an existing server
are POST/PATCH on /api/servers/:id (see the table above).
Creating a server goes through a cloud account the team connected under
Team → Cloud accounts. GET /api/cloud_connections lists them:
{
"cloud_connections": [{
"provider": "vultr", "name": "Vultr", "color": "#007BFC", "account": "ops@acme.test", "needs_reconnect": false,
"default_region": "ewr", "default_size": "vc2-1c-2gb",
"regions": [{"slug": "fra", "name": "Frankfurt (fra)"}],
"sizes": [{"slug": "vc2-2c-4gb", "name": "2 vCPU · 4 GB", "monthly": 20.0, "currency": "$"}]
}],
"operating_systems": [{"slug": "ubuntu", "name": "Ubuntu 24.04"}]
}
monthly is null until the provider’s prices have been fetched once (they’re
cached for 12 hours). POST /api/server_attachments with provider and,
optionally, region, size, os and role ("database" for a database
server) checks the saved credentials with the provider, then returns 202 and
the setup; region and size default to the provider’s. Railyard creates the
machine, installs Docker and the agent, and the server shows up in
/api/servers once it checks in. Poll GET /api/server_attachments/:id for
status (pending → provisioning → installing → ready or failed),
phase, percent, steps[] {key, label}, log_tail[], server_id once ready
and error if it failed. Errors: 422 for an unknown provider, region, size or
OS, an account that isn’t connected, credentials the provider rejects, or the
plan’s server limit; 409 when the same provider, region and size was asked for
in the last 10 seconds.
Data maintenance window — GET/PATCH /api/maintenance_window (team) and
GET/PATCH /api/servers/:id/maintenance_window (one server; blank day = use the
team’s). Fields: maintenance_day 0–6 (Sunday = 0), maintenance_hour 0–23 UTC,
maintenance_hours 1–12. See Database servers.
Postgres major upgrades — GET/POST /api/servers/:id/postgres_upgrades
(to_image; creating one runs the compatibility check), GET …/:id (with the
log), PATCH …/:id (when=window to wait for the maintenance window, otherwise
it starts now), POST …/:id/rollback, DELETE …/:id (removes the kept old
version, or drops an unstarted plan).
Connection pooler — GET/POST/DELETE /api/servers/:id/connection_pooler
(PgBouncer, transaction mode, port 6432). Per app: PATCH /api/applications/:id/database with app_database[pooled]=true points
DATABASE_URL at the pooler from the next deploy and keeps
DATABASE_DIRECT_URL for migrations.
Database forks — GET/POST /api/applications/:id/database_forks
(target_server_id for a new database or target_application_id for a
staging/preview env, source=live|backup, optional mask_sql),
GET …/:id (with the fork’s URL once ready), DELETE …/:id (drops it).
Standby replicas — GET/POST /api/servers/:id/database_replicas
(replica_server_id), POST …/:id/promote, DELETE …/:id.
Cloud
Railyard Cloud makes a team’s Railyard account its own small cloud: servers,
images, static addresses, a DNS zone and S3 buckets, billed at cloud cost plus
a published markup. It is built for tools such as AliaJS that expect a cloud
provider’s API, so the shapes follow Hetzner’s: every response wraps its
object ({"server": {...}}, {"servers": [...]}). A card must be on file
(add it on the Cloud page), and the endpoints answer 503 until the operator
turns Railyard Cloud on.
| Method | Path | Scope | Purpose |
|---|---|---|---|
| GET | /api/cloud/sizes | read | Server sizes with hourly cost, markup and price |
| GET | /api/cloud/ssh_keys | read | List SSH keys |
| POST | /api/cloud/ssh_keys | write | Add an SSH key (201; 200 if the same key already exists) |
| DELETE | /api/cloud/ssh_keys/:id | write | Remove an SSH key |
| GET | /api/cloud/servers | read | List live servers |
| POST | /api/cloud/servers | write | Launch a server (201, pending) |
| GET | /api/cloud/servers/:id | read | Server detail, refreshed on read |
| DELETE | /api/cloud/servers/:id | write | Terminate a server (200, terminated) |
| POST | /api/cloud/servers/:id/power | write | Start a stopped server |
| DELETE | /api/cloud/servers/:id/power | write | Stop a running server |
| POST | /api/cloud/servers/:id/images | write | Snapshot a server into an image (201, creating) |
| GET | /api/cloud/images | read | List images (?name= filters) |
| GET | /api/cloud/images/:id | read | Image detail, refreshed on read |
| DELETE | /api/cloud/images/:id | write | Delete an image |
| GET | /api/cloud/addresses | read | List static addresses |
| POST | /api/cloud/addresses | write | Allocate a static address |
| GET | /api/cloud/addresses/:id | read | Address detail |
| DELETE | /api/cloud/addresses/:id | write | Release a static address |
| POST | /api/cloud/addresses/:id/assignment | write | Attach it to a server ({"server_id": 9}) |
| DELETE | /api/cloud/addresses/:id/assignment | write | Detach it |
| GET | /api/cloud/zone | read | The team’s DNS zone |
| GET | /api/cloud/zone/records | read | List records |
| PUT | /api/cloud/zone/records/:type/:name | write | Create or replace a record |
| DELETE | /api/cloud/zone/records/:type/:name | write | Remove a record |
| GET | /api/cloud/buckets | read | List buckets |
| POST | /api/cloud/buckets | write | Create a bucket; the response carries the team’s storage key |
| DELETE | /api/cloud/buckets/:id | write | Delete a bucket (must be empty) |
| GET | /api/cloud/usage | read | This month’s usage lines with cost, markup and price |
Request bodies are JSON and may be flat ({"name": "web"}) or wrapped
({"server": {"name": "web"}}). App-scoped tokens are refused (403).
Errors on top of the usual ones:
| Status | When |
|---|---|
402 | No card on file. Body: {"error": "add a card before using Railyard Cloud", "card_url": "https://app.railyard.run/cloud/card/new"} |
403 | Read-only or app-scoped token, a team limit reached ("this team has reached its limit of 3 servers"), or the monthly spend limit would be passed |
409 | Conflict: an SSH key name with a different key, a bucket name already used, a bucket that still has objects, a CNAME clash, starting a server that isn’t stopped |
422 | Invalid input: unknown size, unknown image, image/size architecture mismatch, DNS name outside your zone, private IP in an A record |
502 | The cloud rejected the request; the message says why |
503 | Railyard Cloud isn’t turned on |
Sizes: GET /api/cloud/sizes
{ "sizes": [
{ "name": "t4g.small", "vcpus": 2, "memory_gb": 2, "disk_gb": 20, "arch": "arm64",
"hourly_cost": "0.023992", "markup_percent": "10.0", "hourly_price": "0.026391", "monthly_price": "19.27" }
] }
hourly_cost is what the server costs Railyard (machine, public IPv4 and
disk); hourly_price is what the team pays: cost × (1 + markup_percent / 100).
Servers
curl -s -X POST https://app.railyard.run/api/cloud/ssh_keys \
-H "Authorization: Bearer $RLY" -H "Content-Type: application/json" \
-d "{\"name\":\"laptop\",\"public_key\":\"$(cat ~/.ssh/id_ed25519.pub)\"}"
curl -s -X POST https://app.railyard.run/api/cloud/servers \
-H "Authorization: Bearer $RLY" -H "Content-Type: application/json" \
-d '{"name":"n8n-production","size":"t4g.small","image":"ubuntu-24.04","ssh_keys":["laptop"]}'
{ "server": { "id": 9, "name": "n8n-production", "status": "pending", "size": "t4g.small", "arch": "arm64",
"image": "ubuntu-24.04", "disk_gb": 20, "public_ipv4": null, "private_ipv4": null, "public_ipv6": null,
"ssh_keys": ["laptop"], "hourly_price": "0.026391", "failure": null, "created_at": "2026-10-10T12:00:00Z" } }
Poll GET /api/cloud/servers/9 every couple of seconds until status is
running and public_ipv4 is set (usually 10 to 30 seconds), then
ssh ubuntu@<public_ipv4>. failed means the launch was refused; failure
says why. image is ubuntu-24.04 or the name of one of your own images
built for the same architecture as the size.
Images
curl -s -X POST https://app.railyard.run/api/cloud/servers/9/images \
-H "Authorization: Bearer $RLY" -H "Content-Type: application/json" -d '{"name":"n8n-base"}'
Poll GET /api/cloud/images/:id until status is available (a few
minutes). Launch new servers from it with "image": "n8n-base". A dormant
image costs only its stored size (stored_gb), which is how a standby copy
of a service can wait for cents a month.
Addresses: a static IPv4 that survives replacing the server behind it.
curl -s -X POST https://app.railyard.run/api/cloud/addresses -H "Authorization: Bearer $RLY"
# {"address":{"id":3,"ip":"198.51.100.9","server_id":null,"created_at":"..."}}
curl -s -X POST https://app.railyard.run/api/cloud/addresses/3/assignment \
-H "Authorization: Bearer $RLY" -H "Content-Type: application/json" -d '{"server_id":9}'
DNS zone: every team gets its own zone, so no domain of your own is needed.
curl -s https://app.railyard.run/api/cloud/zone -H "Authorization: Bearer $RLY"
# {"zone":{"name":"acme.cloud.railyard.run"}}
curl -s -X PUT https://app.railyard.run/api/cloud/zone/records/A/n8n-production \
-H "Authorization: Bearer $RLY" -H "Content-Type: application/json" -d '{"values":["198.51.100.9"],"ttl":300}'
# {"record":{"id":11,"name":"n8n-production","fqdn":"n8n-production.acme.cloud.railyard.run","type":"A","values":["198.51.100.9"],"ttl":300,...}}
nameis relative to the zone (n8n-production) or fully qualified inside it; anything outside your zone is422, and the zone apex is reserved.- Types:
A,AAAA,CNAME,TXT. TXT works for certbot’s DNS-01 challenge:PUT /api/cloud/zone/records/TXT/_acme-challenge.n8n-production. Avalues must be public addresses. A CNAME can’t share its name with other records.PUTreplaces the record’s values;DELETEon the same path removes it (204).
Buckets
curl -s -X POST https://app.railyard.run/api/cloud/buckets \
-H "Authorization: Bearer $RLY" -H "Content-Type: application/json" -d '{"name":"n8n-backups"}'
{ "bucket": { "id": 2, "name": "n8n-backups", "url": "s3:https://s3.us-east-2.amazonaws.com/rly-7-n8n-backups-ab12cd",
"region": "us-east-2", "created_at": "2026-10-10T12:00:00Z", "access_key_id": "AKIA…", "secret_access_key": "…" } }
url is in restic’s s3: form. The access key belongs to the team and
works only on the team’s buckets; every bucket you create returns the same
key, and listing buckets never shows it. DELETE needs the bucket empty.
Usage: GET /api/cloud/usage
{ "usage": {
"lines": [ { "description": "Server n8n-production (t4g.small)", "metric": "server_hours", "quantity": "1.0",
"period_start": "2026-10-10T12:00:00Z", "cost_usd": "0.023992", "markup_percent": "10.0",
"price_usd": "0.026391", "invoiced": false } ],
"cost_usd": "0.023992", "price_usd": "0.026391", "our_cut_usd": "0.002399", "daily_price_usd": "2.21",
"spend_limit_usd": "100.0" } }
Usage is metered every hour per resource: server hours, outbound traffic,
static address hours, image storage and bucket storage. daily_price_usd
is what the last 24 metered hours cost. Cards are charged when the unbilled
total passes a threshold or at the start of each month.
Templates
Pre-built one-click apps — the same catalog the dashboard’s “deploy a template” page offers.
curl -s https://cp.example.com/api/templates -H "Authorization: Bearer $RLY"
{ "templates": [
{ "key": "n8n", "name": "n8n", "category": "automation", "verified": true,
"addons": ["postgres"], "description": "Workflow automation" }
] }
Launch — POST /api/templates/:key/launch
curl -s -X POST https://cp.example.com/api/templates/n8n/launch \
-H "Authorization: Bearer $RLY" -H "Content-Type: application/json" \
-d '{"server_id":9}'
{ "application_id": 42, "name": "n8n", "url": "https://n8n.apps.example.com", "deploy_id": 101 }
server_id is optional — omit it and Railyard picks the first online app
host. 201 with the first deploy already queued. 422 if the team is over
its app limit or the template’s defaults fail validation.
Activity feed
GET /api/activities returns the same feed as the dashboard’s Activity page,
50 at a time:
{ "activities": [
{ "id": 812, "action": "deploy.succeeded", "summary": "deployed shop (abc1234)", "by": "ops@acme.test",
"application": "shop", "at": "2026-11-11T21:40:00.000Z" } ],
"next_before": 763 }
Pass next_before back as before for the next page. locale is one of
en, fr, es, de, pt. Members limited to some apps only see those
apps’ entries.
GET /api/applications/:id/traffic also returns step, t[] and series
(rpm, s2xx–s5xx, error_rate, bandwidth, p50_ms, p95_ms, p99_ms),
each lined up with t, so clients can chart it.
Status pages and incidents
Status pages are the public pages at /status/<slug> that show customers
whether your apps are up. They need a token covering the whole team; changes
need a write token from a team admin and are recorded in the activity feed.
GET /api/status_pages/:id:
{ "id": 5, "title": "Acme status", "slug": "acme", "description": null, "published": true,
"url": "https://app.railyard.run/status/acme", "status": "degraded", "uptime": 99.91,
"active_incidents": 1,
"components": [
{ "id": 4, "name": "Shop", "application_id": 7, "status": "operational", "uptime": 99.94,
"days": [ { "day": "2026-11-12", "uptime": 100.0 } ] } ],
"incidents": [
{ "id": 9, "title": "Checkout errors", "status": "identified", "impact": "major",
"automatic": false, "application_id": 7, "started_at": "2026-11-12T09:00:00Z", "resolved_at": null,
"updates": [ { "id": 72, "status": "identified", "body": "Found it", "at": "2026-11-12T09:20:00Z" } ] } ] }
status is operational, degraded, partial, major or empty; a
component’s is operational, degraded, down, maintenance, sleeping or
unknown. uptime is over 90 days (null without checks). Incident status
is investigating, identified, monitoring or resolved; impact is
minor, major, critical or maintenance. Incidents with automatic: true
were opened by health checks and close themselves when the app recovers. The
list endpoint returns { "status_pages": [...], "you_can_manage": true }
without incidents or per-day uptime.
Team members and invitations
These need a token that covers the whole team (not one limited to some apps). Changes also need a write token created by an admin or owner of the team, and follow the same rules as the dashboard’s Team page: only owners grant, change or remove the owner role, and the team’s last owner can’t be demoted or removed.
GET /api/members:
{ "members": [
{ "id": 12, "email": "ana@acme.test", "name": "Ana", "role": "deployer",
"apps": [ { "id": 7, "name": "shop" } ], "you": false, "last_owner": false,
"since": "2026-10-02T09:00:00Z" } ],
"invitations": [
{ "id": 4, "email": "new@acme.test", "role": "viewer",
"invited_at": "2026-11-10T09:00:00Z", "expires_at": "2026-11-24T09:00:00Z" } ],
"roles": ["viewer", "deployer", "admin", "owner"],
"you_can_manage": true, "you_can_grant_owner": false }
apps is null when the member sees every app. PATCH /api/members/:id
takes role and app_ids (an empty list means every app; admins and owners
always see every app). POST /api/invitations takes email, role and
app_ids and returns { "invitation": … } for a new address or
{ "member": … } when the address already has a Railyard account. Every
change is recorded in the activity feed.
Mobile devices and push
The iOS app registers each install per token:
curl -s -X POST https://cp.example.com/api/mobile_devices -H "Authorization: Bearer $RLY" \
-H "Content-Type: application/json" \
-d '{"apns_token":"<64+ hex>","environment":"production","name":"iPhone","public_key":"<base64 DER P-256>"}'
{ "id": 9, "name": "iPhone", "environment": "production",
"events": ["deploy_failure","deploy_awaiting_approval","approval_requested","app_down","server_offline","process_crash_looping","metric_alert"],
"snoozes": {} }
events can be any of deploy_failure, deploy_success,
deploy_awaiting_approval, approval_requested, app_down, server_offline,
process_crash_looping, metric_alert, resource_alert.
A device only gets alerts for apps its token can see. Members limited to some apps don’t get server-wide alerts. Revoking the token stops its devices at once.
Snooze — POST /api/mobile_devices/:id/snooze with minutes (1 to
10080) and optionally app_id or server_id silences that app’s or server’s
alerts on this device, or every alert when neither is given.
DELETE /api/mobile_devices/:id/snooze (same optional ids) turns them back on.
Both return the device’s active snoozes, keyed all, app-<id> or
server-<id> with the time each ends:
{ "snoozes": { "app-12": "2026-11-12T15:30:00Z" } }
Approval requests always come through. Snoozes end on their own, and each one shows in the team’s activity feed.
The push carries only ids and a localisation key. The app fetches the
details over the API, so no log text goes through Apple. The control plane
needs APPLE_TEAM_ID, APNS_KEY_ID, APNS_KEY_P8 and IOS_BUNDLE_ID;
until all four are set, nothing is sent. See IOS.md.
Approval requests
Destructive MCP tools (delete an app, remove a variable or domain, restore a backup, reboot a server) don’t act. They create an approval request, and a team admin decides it in the dashboard (Approvals) or in the iOS app.
Approving over the API needs proof that a person approved on a registered
device. The device signs railyard-approval:<team_id>:<request_id>:approve
with the P-256 key it registered (public_key on POST /api/mobile_devices).
The app keeps that key in the Secure Enclave, behind Face ID / Touch ID.
Send the DER signature, base64-encoded:
curl -s -X POST https://cp.example.com/api/approval_requests/5/approve -H "Authorization: Bearer $RLY" \
-H "Content-Type: application/json" -d '{"device_id":9,"signature":"MEUCIQ…"}'
The token that made the request can’t approve it. Only admins with a full
(write) token decide. A request that’s already decided answers 409.
Quick recipes
Deploy on every push (CI):
curl -fsS -X POST "$RAILYARD/api/applications/$APP_ID/deploys" \
-H "Authorization: Bearer $RAILYARD_TOKEN" -H "Content-Type: application/json" \
-d "{\"ref\":\"$GIT_SHA\"}"
Wait for a deploy to finish:
id=$(curl -fsS -X POST "$RAILYARD/api/applications/$APP_ID/deploys" \
-H "Authorization: Bearer $TOKEN" -d '{}' | jq .id)
while :; do
s=$(curl -fsS "$RAILYARD/api/deploys/$id" -H "Authorization: Bearer $TOKEN" | jq -r .status)
case $s in succeeded) exit 0;; failed) exit 1;; esac
sleep 5
done
Sync env from a file (KEY=value lines):
jq -Rn '[inputs | select(test("=")) | split("=") | {(.[0]): (.[1:] | join("="))}] | add | {env: .}' .env.prod \
| curl -fsS -X PATCH "$RAILYARD/api/applications/$APP_ID/env" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d @-
Not in the API yet
Interactive console (a TTY over the Exec RPC), attaching an existing host
over SSH, add-on management beyond the addons array. These are
dashboard-only today; open an issue if you need one over the API.
MCP (AI agents)
POST /api/mcp is a Model Context Protocol server (JSON-RPC over streamable HTTP), so AI agents can use Railyard with the same API tokens.
- A read token can list servers and apps, show an app and read its logs.
- A write token can also deploy, restart and set env vars.
- Deleting an app or removing an env var never runs directly: it creates an approval request. A team admin approves or rejects it under Approvals (it also shows on the dashboard).
Claude Code:
claude mcp add --transport http railyard https://app.railyard.run/api/mcp --header "Authorization: Bearer rly_..."
Cursor (.cursor/mcp.json):
{ "mcpServers": { "railyard": { "url": "https://app.railyard.run/api/mcp", "headers": { "Authorization": "Bearer rly_..." } } } }
Tools: list_servers, list_apps, get_app, app_logs, deploy_app (optional ref: commit SHA, tag or branch), restart_app, set_env, unset_env (approval), delete_app (approval).