Migrations Migrating from Heroku, Render, Hatchbox or Cloud 66? We move your production app within 48 hours →
REST API

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/json on 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

ScopeCan
readevery GET
writeeverything 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: 400 bad request · 401 unauthenticated · 403 wrong scope · 404 not found (or not in your team) · 409 conflict (e.g. a deploy is already running) · 422 validation failed · 429 rate limit.
  • Timestamps — ISO-8601 UTC (2026-09-02T14:03:11Z).
  • IDs — integers, stable per team.
  • Pagination — list endpoints that take limit accept 1–100 (default 30). 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/me returns team.plan, team.plan_name, team.features (what the plan and its add-ons include, e.g. canary, status_pages, sso) and team.addons. Turning on a feature the plan doesn’t include answers 403 with a plain message naming the plan that includes it. Without a plan, adding servers or apps answers 403 too.
  • Flags — team.flags lists the client-facing feature flags turned on for the team (today: app_notification_modes). Hide a screen when its flag is missing.

Endpoints

MethodPathScopePurpose
GET/api/mereadToken + team info (plan, features, add-ons), limits, counts
GET/api/jobsreadLong-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/:idreadOne 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/canceldeployAsk a running job to stop (202; 409 when that job can’t be cancelled)
DELETE/api/sessionreadRevoke the calling token (sign out)
GET/api/mobile_devicesreadDevices registered with this token
POST/api/mobile_devicesreadRegister this device for push (upserts by APNs token)
PATCH/api/mobile_devices/:idreadChoose which events reach the device
DELETE/api/mobile_devices/:idreadStop pushing to the device
GET/api/status_pagesreadThe team’s customer status pages with overall status and open incident counts
GET/api/status_pages/:idreadOne page: components with 30 days of uptime, and its last 20 incidents with updates
POST/api/status_pageswrite (admin)Create a page (title, slug, application_ids)
PATCH/api/status_pages/:idwrite (admin)Change title, description or published
DELETE/api/status_pages/:idwrite (admin)Delete a page and its incident history
POST/api/status_pages/:id/componentswrite (admin)Add an app to the page (application_id, optional name)
DELETE/api/status_pages/:id/components/:component_idwrite (admin)Remove an app from the page
POST/api/status_pages/:id/incidentswrite (admin)Open an incident (title, impact, status, body, optional application_id)
POST/api/status_pages/:id/incidents/:incident_id/updateswrite (admin)Post an update (status, body); resolved closes it
POST/api/device_challengesread (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_tokenswrite (admin) + phone signatureCreate 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/setupphone signatureStart setting up an authenticator app (signed over railyard-setup_authenticator:<team_id>:<nonce>:setup); returns the secret and otpauth:// uri
POST/DELETE/api/account/authenticatortoken made by a personTurn the authenticator on with a current code (returns backup codes) or off with a current code
POST/api/account/passkeys/optionsphone signatureWebAuthn creation options for a new passkey (signed over railyard-add_passkey:<team_id>:<nonce>:options), with rp_id
POST/api/account/passkeystoken made by a personFinish adding a passkey: name and the WebAuthn credential (id, rawId, type, response.clientDataJSON, response.attestationObject)
DELETE/api/account/passkeys/:idphone signatureRemove one of your passkeys, signed over railyard-remove_passkey:<team_id>:<nonce>:<id>
DELETE/api/accountphone signatureDelete 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_tokenswrite (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/:idwrite (admin)Revoke a token straight away (not the calling one; use DELETE /api/session for that)
GET/api/account/securityread (token made by a person)The token owner’s email, two-factor status, passkeys and active web sessions
DELETE/api/account/sessions/:idread (token made by a person)Sign the token owner out of one web session
DELETE/api/account/sessionsread (token made by a person)Sign the token owner out of every web session (API tokens keep working)
GET/api/ssh_keysread (whole-team token)The team’s SSH public keys: name, fingerprint, who added them
POST/api/ssh_keyswrite (admin)Add an OpenSSH public key (public_key, optional name)
DELETE/api/ssh_keys/:idwrite (admin)Remove an SSH key
GET/api/applications/:id/networkingreadIP allow and block lists, password protection (never the password), path routes and published ports
PATCH/api/applications/:id/ip_ruleswrite (admin)Replace ip_allowlist and ip_denylist (addresses or CIDR ranges)
PUT/DELETE/api/applications/:id/passwordwrite (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_destinationread / 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/importswrite (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_idwrite (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_idwrite (admin)Import it onto server_id (optional git_url, copy_data); returns the new app and its first deploy
GET/api/canvasread (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_conversationsoperator tokenRailyard operators only: support conversations (filter unread, open, mine, unassigned, website, closed)
GET/api/operator/support_conversations/:idoperator tokenA conversation’s messages; marks it read
POST/api/operator/support_conversations/:id/replyoperator write tokenReply as support (body)
GET/api/membersreadTeam members, pending invitations and what the caller may change
PATCH/api/members/:idwrite (admin)Change a member’s role or the apps they can see
DELETE/api/members/:idwrite (admin)Remove a member from the team
POST/api/invitationswrite (admin)Invite someone by email (existing Railyard users join straight away)
POST/api/invitations/:id/resendwrite (admin)Send a pending invitation again and restart its 14 days
DELETE/api/invitations/:idwrite (admin)Revoke a pending invitation
POST/api/acknowledgementsreadRecord that you’ve seen an alert ({"key":"deploy-41"})
GET/api/activitiesreadTeam activity as sentences, newest first (?application_id=, ?before=<id>, ?locale=)
GET/api/approval_requestsreadPending approval requests from agents
POST/api/approval_requests/:id/approvewrite, adminApprove with a device signature ({"device_id":9,"signature":"…"})
POST/api/approval_requests/:id/rejectwrite, adminReject
GET/api/applicationsreadList apps
POST/api/applicationswriteCreate an app
GET/api/applications/:idreadApp detail
PATCH/api/applications/:idwriteUpdate an app
DELETE/api/applications/:idwriteDelete an app (and its deploys/logs)
POST/api/applications/:id/archivewriteStop the container, keep the record
POST/api/applications/:id/unarchivewriteUn-archive
GET/api/applications/:id/envreadRead env vars
PATCH/api/applications/:id/envwriteMerge env vars (null value deletes)
DELETE/api/applications/:id/env?key=KEYwriteDelete one env var
GET/api/applications/:id/edgereadEdge settings (same shape as the manifest’s edge: section, see Edge rules)
PATCH/api/applications/:id/edgewriteMerge edge settings: {"edge":{"access_logs":false,"headers":[…],"cors":{…}}}
GET/api/applications/:id/certificatesreadUploaded certificates (names, covered hosts, validity, fingerprint; never the key)
POST/api/applications/:id/certificateswriteUpload {"certificate":{"certificate_pem":"…","private_key_pem":"…"}}
DELETE/api/applications/:id/certificates/:cert_idwriteRemove one (automatic certificates after the next deploy)
GET/api/applications/:id/domainsreadList custom domains
POST/api/applications/:id/domainswriteAdd a custom domain
DELETE/api/applications/:id/domains/:domain_idwriteRemove a custom domain
POST/api/applications/:id/domains/:domain_id/checkwriteRe-check DNS and the certificate now; returns the domain with its fresh status (unverified, pending, unrouted, misconfigured or live)
GET/api/applications/:id/deploysreadDeploys for one app
POST/api/applications/:id/deployswriteTrigger a deploy ({"image": "registry/repo:tag"} deploys that prebuilt image once)
GET/api/applications/:id/registrywriteThe team’s build registry for deploy --local: repository, username, password, platform
POST/api/applications/:id/tunnelwriteOpen 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/consolewrite (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/consolewrite (team owner, whole-team token)Same, for a root shell on the server; logged as server.console_opened
GET/api/applications/:id/logsreadRuntime container logs (?tail=, ?process=)
GET/api/applications/:id/processesreadPer-container state (for ps)
POST/api/applications/:id/restartwriteBounce every container, or one ?process=
GET/api/applications/:id/process_typesreadProcess types with env, shutdown and size settings
PATCH/api/applications/:id/process_types/:pt_idwriteSet env_vars_text, kill_timeout_seconds, stop_signal, size, cpu_limit, memory_limit
GET/api/applications/:id/commandsreadRecent one-off command runs
POST/api/applications/:id/commandswriteRun a one-off command ({"command": "..."})
GET/api/applications/:id/commands/:cmd_idreadOne run: status, output, exit code
POST/api/applications/:id/reindexwriteRebuild 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/clonewriteClone the app into a staging copy
POST/api/applications/:id/promotewritePromote a staging app’s release to production
GET/api/applications/:id/manifestreadThe app as railyard.yml (?secrets=true includes variable values)
POST/api/applications/:id/apply_manifestwriteApply a manifest ({"manifest": "<yaml text>"})
POST/api/applications/validate_manifestreadCheck 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_querywriteRun 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_tableswriteThe app database’s tables, largest first: {engine, database, tables: [{schema, name, rows, bytes}]} (rows/bytes may be strings)
GET/api/applications/:id/db_insightswritePostgres 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_lockswriteQueries 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_cancelwriteStop a query ({"pid": 123, "force": false}; force ends the whole connection); logged as db.query_stopped
GET/api/applications/:id/database_importsreadThe 20 most recent imports with status, phase and percent
POST/api/applications/:id/database_imports/uploadswriteStart 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_idwriteResume one (?key=&byte_size=): done part numbers and fresh parts: [{number, url}] for the rest
POST/api/applications/:id/database_importswriteStart 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_backupsread / writeList backups / take one now
POST/api/database_backups/:id/restorewriteRestore a backup
GET/api/database_backups/:id/downloadreadSigned download link
GET/POST/api/applications/:id/volume_backupsread / writeList backups / back up one volume ({"volume": "name"})
POST/api/volume_backups/:id/restorewriteRestore a volume backup
GET/api/applications/:id/trafficreadRequests, p95, error rate and slowest endpoints (?range=1h|24h|7d|30d)
PATCH/api/applications/:id/autoscalewriteScale web replicas on p95/CPU ({"max":N,"min":N,"p95":ms,"cpu":pct}); {"max":null} turns it off
POST/api/applications/:id/data_movewriteMove the app’s data to a database server ({"database_server_id": 12}); 202 with what gets copied
POST/api/applications/:id/external_datastoreswritePoint 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/:kindwriteBring that data back under Railyard (?copy=true copies it back)
GET/api/applications/:id/addons/:kind/transfersreadRecent exports/imports of an add-on (redis, mongodb, elasticsearch, storage, influxdb, rabbitmq), with download links
POST/api/applications/:id/addons/:kind/transferswriteExport the add-on’s data; with multipart file + confirm=<app name>, load a file into it
GET/api/applications/:id/storage/objectsreadBrowse the storage add-on’s bucket (?prefix=, ?token=): folders, files with size, public flag and a signed link
POST/api/applications/:id/storage/objectswriteUpload a file (multipart file, prefix or key)
DELETE/api/applications/:id/storage/object?key=writeDelete a file, or a folder when the key ends in /
PATCH/api/applications/:id/storage/visibilitywriteMake a folder public or private ({"prefix":"avatars/","public":true})
GET/api/applications/:id/redisreadWhere the app’s Redis lives (shared db N or its own), its limit and policy, memory used
PATCH/api/applications/:id/rediswrite{"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/deploysreadDeploys across the team (?application_id=, ?limit=)
GET/api/deploys/:idreadDeploy detail
GET/api/deploys/:id/logsreadDeploy log lines (oldest first, ≤5000; ?after=<id> pages forward 2000 at a time)
GET/api/applications/:id/log_searchreadStored log lines: time range, search, cursor pages (see Logs, metrics and alerts)
GET/api/applications/:id/log_downloadreadStored log lines for a range as text
GET/PATCH/DELETE/api/applications/:id/otel_exportread / writeOpenTelemetry export settings (see Logs, metrics and alerts)
GET/POST/api/applications/:id/metric_alertsread / writeMetric threshold alerts and their history
PATCH/DELETE/api/applications/:id/metric_alerts/:alert_idwriteChange or remove an alert
GET/api/applications/:id/job_queuereadJob queue stats, failed jobs, history (see Logs, metrics and alerts)
POST/api/applications/:id/job_queue/failed/:job_id/retrywriteRetry a failed job
DELETE/api/applications/:id/job_queue/failed/:job_idwriteDiscard a failed job
GET/api/serversreadThe fleet
GET/api/servers/:idreadServer detail + live process states
GET/api/servers/:id/metricsreadCPU/memory/disk series (?range=live|1h|6h|24h|7d|30d)
GET/api/costsreadThe 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/scanwriteRefresh the spend report from the connected cloud accounts (202; one scan at a time)
GET/api/cloud_connectionswriteThe team’s connected cloud accounts, with the regions, sizes (and monthly prices) and operating systems each can create
GET/api/providersreadEvery cloud provider with label, connected (whether the team linked an account), default_region, default_size, and regions/sizes as [{slug, name}]
POST/api/server_attachmentswriteCreate 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]readServer setups in flight (or failed in the last day), with live progress
POST/api/servers/:id/reboot | /power_cycle | /cordon | /uncordon | /prune_dockerwriteServer lifecycle actions
PATCH/api/servers/:id/resizewriteResize at the provider ({"size": "..."})
POST/api/servers/:id/trust_ipwriteUnban 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_hooksread / writeDeploy hooks; create with {"deploy_hook":{"stage":"before_release|after_release|after_deploy","command":"…"}}
DELETE/api/applications/:id/deploy_hooks/:hook_idwriteRemove a hook
GET/POST/api/applications/:id/log_drainsread / writeLog drains; create with {"log_drain":{"kind":"https_json|syslog","url":"…"}}
DELETE/api/applications/:id/log_drains/:drain_idwriteRemove a drain
GET/POST/api/applications/:id/secret_filesread / writeFiles mounted into the app’s containers; create with {"secret_file":{"name":"…","content":"…"}} (content is never returned)
DELETE/api/applications/:id/secret_files/:file_idwriteRemove a file
GET/api/applications/:id/scheduled_tasksreadCron tasks with schedule, command and last status
POST/api/applications/:id/scheduled_tasks/:task_id/runwriteRun one now
PATCH/api/applications/:id/auto_deploywrite{"auto_deploy":true} deploys every push to the tracked branch; returns the webhook_url
POST/api/applications/:id/auto_deploy/regeneratewriteIssue a new push webhook URL
POST/api/applications/:id/maintenancewrite{"on":true} shows the maintenance page instead of the app (queues a deploy); {"on":false} brings it back
PATCH/api/applications/:id/scalewriteReplicas for non-web processes ({"replicas":{"worker":3}}); web replicas come from autoscale or the app’s web_replicas
PATCH/api/applications/:id/sleepwriteStop when idle and wake on the next request ({"minutes":30}; null turns it off)
POST/api/applications/:id/wakewriteWake a sleeping app now
PATCH/api/applications/:id/deploy_windowwrite{"days":["mon","tue"],"start":"09:00","end":"17:00","time_zone":"America/Toronto"}; no days clears it
POST/api/applications/:id/create_environmentwriteClone the app into a new environment ({"environment":"staging","git_ref":"main"})
POST/api/applications/:id/apply_profilewriteApply a deployment profile ({"profile_id":4})
PATCH/api/applications/:id/databasewriteBackup 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/resetwriteDrop and recreate it ({"engine":"postgres","confirm":"<app name>"}) — irreversible
GET/DELETE/api/applications/:id/database_forks/:fork_idread / writeOne fork / drop it (GET/POST /api/applications/:id/database_forks lists and creates them, see below)
GET/POST/api/deployment_profilesread / writeDeployment 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/:idwriteChange or remove one
POST/api/servers/:id/standby_rejoinwriteRe-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_ipwriteBlock or unblock an IP on the server’s firewall ({"ip":"…"})
GET/PATCH/api/servers/:id/maintenance_windowread / writePer-server data maintenance window (same shape as the team one)
GET/POST/api/notification_rulesread / 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/:idwrite (whole-team token)Change (enabled, flags) or remove a rule
PATCH/api/applications/:id/notification_modewriteWhich rules notify about the app: team, own or muted (flag app_notification_modes)
GET/POST/api/webhook_endpointsread / writeWebhook endpoints; create with {"url":"https://…","events":["deploy.started","deploy.approved"],"application_id":null}
PATCH/DELETE/api/webhook_endpoints/:idwriteChange (url, events, enabled) or remove an endpoint
GET/POST/api/configread / writeTeam-wide config entries; set with {"key":"REGION","value":"eu","secret":true,"description":"…"} (POST on an existing key updates it)
DELETE/api/config/:keywriteRemove an entry
POST/api/cli/authnoneStart a CLI sign-in: returns a code and the url to confirm it in the browser
GET/api/cli/auth/:codenonePolled 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 (or server_id) may be a server id or hostname. Omit it and the app lands on the first uncordoned server in the team.
  • Blank hostname is derived — <name>.<server app_domain>, else APP_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’s git_ref, which a ref never changes. The deploy’s trigger is ref and its ref field shows what it used. Names with characters git refs can’t have get 422. Ignored for an image:// app.
  • message (optional) — a deploy note (up to 500 characters), returned as message and shown in the dashboard, activity, notifications and the deploy.* webhooks.
  • at (optional) — ISO 8601 time to deploy at instead of now. Answers 201 with status: "scheduled" and scheduled_for; the time must be in the future and inside the deploy window (422 otherwise). Cancel it with POST /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 answers 409 with outside_window: true and window_opens_at.
  • rollback_to (optional) — id of an earlier succeeded deploy. Redeploys its commit and puts back the variables it ran with; the response adds restored_config. Send "restore_config": false to 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 with status: "pending_approval" if the app requires deploy approval (approve it in the dashboard).
  • 409 if a deploy is already active or awaiting approval for that app.
  • 429 if the team’s deploys-per-hour limit is hit.
  • 422 if the app is archived.
  • 422 with missing_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": true to 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.

MethodPathScopePurpose
GET/api/cloud/sizesreadServer sizes with hourly cost, markup and price
GET/api/cloud/ssh_keysreadList SSH keys
POST/api/cloud/ssh_keyswriteAdd an SSH key (201; 200 if the same key already exists)
DELETE/api/cloud/ssh_keys/:idwriteRemove an SSH key
GET/api/cloud/serversreadList live servers
POST/api/cloud/serverswriteLaunch a server (201, pending)
GET/api/cloud/servers/:idreadServer detail, refreshed on read
DELETE/api/cloud/servers/:idwriteTerminate a server (200, terminated)
POST/api/cloud/servers/:id/powerwriteStart a stopped server
DELETE/api/cloud/servers/:id/powerwriteStop a running server
POST/api/cloud/servers/:id/imageswriteSnapshot a server into an image (201, creating)
GET/api/cloud/imagesreadList images (?name= filters)
GET/api/cloud/images/:idreadImage detail, refreshed on read
DELETE/api/cloud/images/:idwriteDelete an image
GET/api/cloud/addressesreadList static addresses
POST/api/cloud/addresseswriteAllocate a static address
GET/api/cloud/addresses/:idreadAddress detail
DELETE/api/cloud/addresses/:idwriteRelease a static address
POST/api/cloud/addresses/:id/assignmentwriteAttach it to a server ({"server_id": 9})
DELETE/api/cloud/addresses/:id/assignmentwriteDetach it
GET/api/cloud/zonereadThe team’s DNS zone
GET/api/cloud/zone/recordsreadList records
PUT/api/cloud/zone/records/:type/:namewriteCreate or replace a record
DELETE/api/cloud/zone/records/:type/:namewriteRemove a record
GET/api/cloud/bucketsreadList buckets
POST/api/cloud/bucketswriteCreate a bucket; the response carries the team’s storage key
DELETE/api/cloud/buckets/:idwriteDelete a bucket (must be empty)
GET/api/cloud/usagereadThis 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:

StatusWhen
402No card on file. Body: {"error": "add a card before using Railyard Cloud", "card_url": "https://app.railyard.run/cloud/card/new"}
403Read-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
409Conflict: 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
422Invalid input: unknown size, unknown image, image/size architecture mismatch, DNS name outside your zone, private IP in an A record
502The cloud rejected the request; the message says why
503Railyard 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,...}}
  • name is relative to the zone (n8n-production) or fully qualified inside it; anything outside your zone is 422, 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.
  • A values must be public addresses. A CNAME can’t share its name with other records.
  • PUT replaces the record’s values; DELETE on 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).

Found an issue or have a question?
Theme
Colors