CLI & REST API

CLI Installation

The RailPush CLI lets you manage services, deployments, databases, and more from your terminal.

terminal

# macOS (Apple Silicon)
curl -fsSL https://railpush.com/dl/railpush-darwin-arm64 -o railpush && chmod +x railpush && sudo mv railpush /usr/local/bin/

# macOS (Intel)
curl -fsSL https://railpush.com/dl/railpush-darwin-amd64 -o railpush && chmod +x railpush && sudo mv railpush /usr/local/bin/

# Linux (amd64)
curl -fsSL https://railpush.com/dl/railpush-linux-amd64 -o railpush && chmod +x railpush && sudo mv railpush /usr/local/bin/

# Linux (arm64)
curl -fsSL https://railpush.com/dl/railpush-linux-arm64 -o railpush && chmod +x railpush && sudo mv railpush /usr/local/bin/

CLI Quick Start

terminal

# Login
railpush login --host railpush.com

# List your services
railpush services list

# Trigger a deploy
railpush deploy <service-id>

# View logs
railpush logs <service-id> --tail 100

# Manage environment variables
railpush env list <service-id>
railpush env set <service-id> DATABASE_URL=postgres://... NODE_ENV=production

# Blueprint operations
railpush blueprints list
railpush blueprints sync <blueprint-id>

# Database management
railpush databases list
railpush databases create --name mydb --engine postgresql --plan s

CLI Commands

Command	Description
railpush login	Authenticate and store credentials
railpush logout	Remove stored credentials
railpush whoami	Show current user info
railpush services list	List all services
railpush services get <id>	Show service details (JSON)
railpush services create	Create a service (--name, --type, --repo)
railpush services delete <id>	Delete a service
railpush services restart <id>	Restart a running service
railpush deploy <service-id>	Trigger a new deploy
railpush deploys list <service-id>	List deploy history
railpush logs <service-id>	View service logs (--tail N)
railpush env list <service-id>	List environment variables
railpush env set <service-id> K=V	Set environment variables
railpush blueprints list	List all blueprints
railpush blueprints sync <id>	Trigger blueprint sync
railpush databases list	List all databases
railpush databases create	Create a database (--name, --plan)
railpush domains list <service-id>	List custom domains
railpush domains add <sid> <domain>	Add a custom domain

REST API

The RailPush API is a RESTful JSON API. Authenticate with a Bearer token from /api/v1/auth/login (JWT) or a scoped API key from /api/v1/auth/api-keys.

Authentication

terminal

# Login and get a token
curl -X POST https://railpush.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

# Use the token in subsequent requests
curl https://railpush.com/api/v1/services \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoints

All endpoints are under /api/v1 and require a Bearer token unless noted.

Resource endpoints accept either full UUIDs or unique short UUID prefixes (for example 34a927ba). If a resource is not found, error responses include error_code, message, optional suggestion, and docs_url.

Destructive deletes use a confirmation-token flow and default to soft-delete with a 72-hour recovery window before hard delete is allowed.

List endpoints support optional cursor pagination via limit and cursor. When either is provided, responses use { data, pagination }.

error-response.json

{
  "error_code": "SERVICE_NOT_FOUND",
  "message": "no service with ID 34a927ba",
  "error": "no service with ID 34a927ba",
  "suggestion": "Did you mean 34a927ba-9c3b-4004-8a35-e7db26b12a81?",
  "docs_url": "https://docs.railpush.com/api/errors#SERVICE_NOT_FOUND"
}

Services

Method	Endpoint	Description
GET	/services	List services (filters: type,status,runtime,plan,name,repo_url,project_id,query,suspended; pagination: limit,cursor)
POST	/services	Create a service
POST	/services/:id/clone	Clone a service with optional field overrides and optional env-var copy
POST	/services/bulk-update	Apply a partial update payload to multiple services (supports dry_run, transaction_mode)
POST	/services/bulk-restart	Restart multiple services in one request (supports dry_run, transaction_mode)
GET	/services/:id	Get service details
GET	/services/:id/event-webhook	Get deploy event webhook config
PUT	/services/:id/event-webhook	Set deploy event webhook config
POST	/services/:id/event-webhook/test	Send deploy.test webhook payload
PATCH	/services/:id	Update a service (supports deletion_protection)
GET	/services/:id/retention	Get service log retention policy
PUT	/services/:id/retention	Set service log retention policy
GET	/services/:id/mtls	Get service mTLS policy (enabled/mode/allowed services)
PUT	/services/:id/mtls	Set service mTLS policy (strict/permissive + allowed services)
GET	/services/:id/access-control	Get service ingress access-control policy (IP allowlist/blocklist + active CIDRs)
PUT	/services/:id/access-control	Set service ingress access-control policy (mode, CIDR rules, optional deny response)
GET	/services/:id/access-control/log	List recent access-control policy change events for the service
GET	/services/:id/disks	List persistent disk attachment
PUT	/services/:id/disks	Create/replace persistent disk attachment
DELETE	/services/:id/disks	Delete persistent disk attachment
DELETE	/services/:id	Delete flow (token challenge -> soft-delete; optional hard_delete after recovery window)
POST	/services/:id/restore	Restore a soft-deleted service
POST	/services/:id/restart	Restart a service
POST	/services/:id/suspend	Suspend a service
POST	/services/:id/resume	Resume a suspended service
GET	/services/:id/dependencies	List service dependencies (databases, key-value, and service references)

Deploys

Method	Endpoint	Description
POST	/services/bulk-deploy	Trigger deploys for multiple services (supports dry_run, transaction_mode)
POST	/services/:id/deploys	Trigger a deploy
GET	/services/:id/deploys	List deploys (filters: status,branch,since,until; pagination: limit,cursor)
GET	/services/:id/deploys/:deployId	Get deploy details
GET	/services/:id/deploys/:deployId/queue	Get queue position and estimated wait time for a deploy
POST	/services/:id/deploys/:deployId/wait	Wait for deploy completion (timeout query param)
POST	/services/:id/deploys/:deployId/rollback	Rollback to a deploy
GET	/services/:id/ai-fix/diagnosis	Get a plain-English AI diagnosis for the latest failed deploy (optional deploy_id query)
POST	/services/:id/ai-fix	Start AI auto-fix for a failed deploy (supports hint and preview_only mode for proposed diff)
GET	/services/:id/ai-fix/status	Get AI auto-fix session status

Env Vars & Domains

Method	Endpoint	Description
POST	/services/bulk-set-env	Set env vars for multiple services (merge/replace + dry_run + transaction_mode)
GET	/services/:id/env-vars	List env vars (pagination: limit,cursor)
PUT	/services/:id/env-vars	Bulk replace all env vars (confirm required for removals)
PATCH	/services/:id/env-vars	Upsert env vars (additive)
GET	/services/:id/custom-domains	List custom domains (pagination: limit,cursor)
POST	/services/:id/custom-domains	Add custom domain (with optional redirect_target)
DELETE	/services/:id/custom-domains/:domain	Remove custom domain
GET	/services/:id/rewrite-rules	List rewrite/proxy rules
POST	/services/:id/rewrite-rules	Add rewrite/proxy rule
DELETE	/services/:id/rewrite-rules/:ruleId	Remove rewrite rule

Logs & Metrics

Method	Endpoint	Description
GET	/services/:id/logs	Query service logs (supports type,search,regex,since,until,level,filter for structured fields)
GET	/services/:id/log-drains	List configured external log forwarding drains for a service
POST	/services/:id/log-drains	Create a log drain (destination, config, filters, and delivery controls)
DELETE	/services/:id/log-drains/:drainId	Delete a configured log drain
GET	/services/:id/log-drains/:drainId/stats	Get log drain delivery stats (sent, failed, lag, last error)
POST	/services/:id/log-drains/:drainId/test	Send a synthetic test log entry through a drain
GET	/services/:id/log-alerts	List log-based alert rules for a service
POST	/services/:id/log-alerts	Create a log-based alert rule (filter/pattern + threshold/window + channels/cooldown)
PATCH	/services/:id/log-alerts/:alertId	Update a log-based alert rule
DELETE	/services/:id/log-alerts/:alertId	Delete a log-based alert rule
GET	/services/:id/metrics	Get current resource usage
GET	/services/:id/metrics/history	Get Prometheus-backed usage history (period=1h

Autoscaling & Jobs

Method	Endpoint	Description
GET	/services/:id/autoscaling	Get autoscaling policy
PUT	/services/:id/autoscaling	Set autoscaling policy
POST	/services/:id/exec	Execute a command in the running service container (synchronous)
POST	/services/:id/shell	Create persistent shell session for a service container
POST	/shell/:sessionId/exec	Execute command inside an existing shell session
DELETE	/shell/:sessionId	Close shell session
GET	/services/:id/fs	List files/directories in service container (read-only)
GET	/services/:id/fs/read	Read file content from service container (read-only, size-limited)
GET	/services/:id/fs/search	Search files in service container by glob pattern
GET	/services/:id/jobs	List one-off jobs (pagination: limit,cursor)
POST	/services/:id/jobs	Run a one-off job
GET	/jobs/:jobId	Get job details

Databases (PostgreSQL)

Method	Endpoint	Description
GET	/databases	List databases (filters: plan,status,pg_version,name,query; pagination: limit,cursor)
POST	/databases	Create a database
POST	/databases/bulk-update	Apply a partial update payload to multiple databases (supports dry_run, transaction_mode)
GET	/databases/:id	Get database details (credentials redacted by default)
POST	/databases/:id/credentials/reveal	Reveal plaintext credentials (explicit acknowledgement required)
POST	/databases/:id/rotate-password	Rotate database password and sync linked service references
POST	/databases/:id/query	Execute SQL (default read-only; optional write mode requires explicit acknowledgement)
GET	/databases/:id/retention	Get database backup retention policy
PUT	/databases/:id/retention	Set database backup retention policy
GET	/databases/:id/recovery-window	Get available point-in-time recovery window
PATCH	/databases/:id	Update a database (supports deletion_protection)
DELETE	/databases/:id	Delete flow (token challenge -> soft-delete; optional confirm_linked_services and hard_delete after recovery window)
POST	/databases/:id/restore	Restore a soft-deleted database, restore from backup_id, or perform time-targeted restore with target_time (new database by default, optional in-place)
POST	/databases/:id/clone	Clone a database from latest backup, backup_id, or target_time; supports optional plan override and sanitization rules
GET	/databases/:id/clone-status	Get clone progress/status for a cloned database
GET	/databases/:id/restores	List database restore jobs and statuses
GET	/databases/:id/backups	List backups (pagination: limit,cursor)
POST	/databases/:id/backups	Trigger a backup
GET	/databases/:id/connected-services	List services connected to this database
GET	/databases/:id/impact	Show blast radius / affected services for this database
GET	/databases/:id/replicas	List read replicas
POST	/databases/:id/replicas	Create a read replica
POST	/databases/:id/replicas/:rid/promote	Promote replica
POST	/databases/:id/ha/enable	Enable high availability

Key-Value (Redis)

Method	Endpoint	Description
GET	/keyvalue	List key-value stores (filters: plan,status,name,query; pagination: limit,cursor)
POST	/keyvalue	Create a key-value store
GET	/keyvalue/:id	Get key-value details (credentials redacted by default)
POST	/keyvalue/:id/credentials/reveal	Reveal plaintext credentials (explicit acknowledgement required)
PATCH	/keyvalue/:id	Update plan, eviction policy, or deletion_protection
DELETE	/keyvalue/:id	Delete flow (token challenge -> soft-delete; optional hard_delete after recovery window)
POST	/keyvalue/:id/restore	Restore a soft-deleted key-value store

MySQL

Method	Endpoint	Description
GET	/mysql	List MySQL instances
POST	/mysql	Create a MySQL instance
GET	/mysql/:id	Get MySQL details
POST	/mysql/:id/credentials/reveal	Reveal credentials
PATCH	/mysql/:id	Update MySQL instance
DELETE	/mysql/:id	Soft-delete with 72h recovery window
POST	/mysql/:id/restore	Restore a soft-deleted instance

MongoDB

Method	Endpoint	Description
GET	/mongodb	List MongoDB instances
POST	/mongodb	Create a MongoDB instance
GET	/mongodb/:id	Get MongoDB details
POST	/mongodb/:id/credentials/reveal	Reveal credentials
PATCH	/mongodb/:id	Update MongoDB instance
DELETE	/mongodb/:id	Soft-delete with 72h recovery window
POST	/mongodb/:id/restore	Restore a soft-deleted instance

Meilisearch

Method	Endpoint	Description
GET	/meilisearch	List Meilisearch instances
POST	/meilisearch	Create a Meilisearch instance
GET	/meilisearch/:id	Get Meilisearch details
POST	/meilisearch/:id/credentials/reveal	Reveal API key
PATCH	/meilisearch/:id	Update Meilisearch instance
DELETE	/meilisearch/:id	Soft-delete with 72h recovery window
POST	/meilisearch/:id/restore	Restore a soft-deleted instance

Object Storage (MinIO)

Method	Endpoint	Description
GET	/object-storage	List object storage instances
POST	/object-storage	Create an object storage instance
GET	/object-storage/:id	Get object storage details
POST	/object-storage/:id/credentials/reveal	Reveal access/secret keys
PATCH	/object-storage/:id	Update object storage instance
DELETE	/object-storage/:id	Soft-delete with 72h recovery window
POST	/object-storage/:id/restore	Restore a soft-deleted instance

Blueprints

Method	Endpoint	Description
GET	/blueprints	List blueprints
POST	/blueprints	Create a blueprint (auto-syncs)
GET	/blueprints/:id	Get blueprint details
PATCH	/blueprints/:id	Update blueprint (move to folder)
DELETE	/blueprints/:id	Delete a blueprint
POST	/blueprints/:id/sync	Trigger blueprint sync

Env Groups

Method	Endpoint	Description
GET	/env-groups	List env groups
POST	/env-groups	Create an env group
GET	/env-groups/:id	Get env group details
PATCH	/env-groups/:id	Update an env group
DELETE	/env-groups/:id	Delete an env group
GET	/env-groups/:id/vars	List group variables
PUT	/env-groups/:id/vars	Bulk update group variables
POST	/env-groups/:id/link	Link a service
DELETE	/env-groups/:id/link/:serviceId	Unlink a service
GET	/env-groups/:id/services	List linked services (set include_usage=true for used/missing key analysis)

Projects & Environments

Method	Endpoint	Description
GET	/projects	List projects
POST	/projects	Create a project
GET	/projects/:id	Get project details
PATCH	/projects/:id	Update a project
DELETE	/projects/:id	Delete a project
GET	/projects/:id/environments	List environments
POST	/projects/:id/environments	Create an environment
PATCH	/environments/:id	Update an environment
DELETE	/environments/:id	Delete an environment
GET	/project-folders	List project folders
POST	/project-folders	Create a project folder
PATCH	/project-folders/:id	Update or move a folder
DELETE	/project-folders/:id	Delete a folder
GET	/preview-environments	List preview environments
POST	/preview-environments	Create or upsert a preview environment manually
PATCH	/preview-environments/:id	Update preview metadata/service overrides and optionally redeploy
DELETE	/preview-environments/:id	Close preview and delete preview service resources

Registered Domains & DNS

Method	Endpoint	Description
GET	/domains	List registered domains
POST	/domains	Register a domain
GET	/domains/:id	Get domain details
DELETE	/domains/:id	Delete a registered domain
GET	/domains/:id/dns	List DNS records
POST	/domains/:id/dns	Create a DNS record
PUT	/domains/:id/dns/:recordId	Update a DNS record
DELETE	/domains/:id/dns/:recordId	Delete a DNS record

Workspace & Billing

Method	Endpoint	Description
GET	/search	Workspace search across services, databases, and key-value stores (?q=...)
GET	/workspace/topology	Get dependency graph for default workspace
GET	/workspaces/:id/topology	Get dependency graph for a specific workspace
GET	/rate-limit	Current API rate-limit state (limit, remaining, reset_at, window)
GET	/workspaces/:id/members	List workspace members
POST	/workspaces/:id/members	Invite a member
PATCH	/workspaces/:id/members/:userId	Update member role
DELETE	/workspaces/:id/members/:userId	Remove a member
GET	/workspaces/:id/compliance	Get workspace compliance guardrails (phase 1)
PUT	/workspaces/:id/compliance	Set workspace compliance guardrails (phase 1)
GET	/workspaces/:id/compliance/report	Generate SOC2/HIPAA/GDPR policy readiness report (phase 1)
GET	/workspaces/:id/retention	Get workspace retention policy (audit/deploy/metrics)
PUT	/workspaces/:id/retention	Set workspace retention policy (audit/deploy/metrics)
GET	/workspaces/:id/audit-logs	List audit logs (pagination: limit,cursor)
GET	/billing	Get billing overview

Support

Method	Endpoint	Description
GET	/support/tickets	List support tickets (status/category/component/tags/query filters)
POST	/support/tickets	Create a ticket (category/component/tags supported)
GET	/support/tickets/:id	Get ticket details
PATCH	/support/tickets/:id/tags	Replace ticket tags
POST	/support/tickets/:id/messages	Reply to a ticket