REST API

The ready.dev API lets you manage your infrastructure programmatically. All endpoints return JSON and use standard HTTP methods.

Base URL https://cloud.ready.dev/api

Authentication

Authenticate requests by including your API key in the Authorization header. API keys are cluster-scoped and can optionally be restricted to specific projects or domains. Manage keys from your cluster settings.

Keep your keys safe

Never expose API keys in client-side code or commit them to version control. Use environment variables or a secrets manager.

Request Header

Authorization: Bearer your_api_key_here

Cluster

Retrieve information about the cluster associated with your API key.

GET /cluster

Get cluster details.

Example Request

curl https://cloud.ready.dev/api/cluster \
  -H "Authorization: Bearer your_api_key_here"

Response

{
  "cluster": {
    "name": "production",
    "project_count": 3,
    "resource_count": 12,
    "status": "active"
  }
}

Projects

Projects are logical groupings of resources within a cluster. Resource names must be unique within a project.

GET /projects

List all projects you have access to.

Example Request

curl https://cloud.ready.dev/api/projects \
  -H "Authorization: Bearer your_api_key_here"

Response

{
  "projects": [
    {
      "name": "my-saas-app",
      "description": "Production SaaS application",
      "resource_count": 3,
      "created_at": "2026-01-10T08:00:00Z",
      "updated_at": "2026-01-15T12:00:00Z"
    }
  ]
}

GET /projects/:name

Retrieve details for a specific project, including its resources.

Response

{
  "project": {
    "name": "my-saas-app",
    "description": "Production SaaS application",
    "resource_count": 2,
    "created_at": "2026-01-10T08:00:00Z",
    "updated_at": "2026-01-15T12:00:00Z",
    "resources": [
      {
        "name": "web",
        "resource_type": "github",
        "state": "active",
        "deployment_hash": "abc123",
        "hosts": ["host-1"]
      }
    ]
  }
}

POST /projects

Create a new project.

Parameter	Description
project[name]	(required) Project name
project[description]	Project description

Example Request

curl -X POST https://cloud.ready.dev/api/projects \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"project": {"name": "my-saas-app", "description": "Production SaaS application"}}'

Response (201)

{
  "project": {
    "name": "my-saas-app",
    "description": "Production SaaS application",
    "resource_count": 0,
    "created_at": "2026-01-10T08:00:00Z",
    "updated_at": "2026-01-10T08:00:00Z"
  }
}

PUT /projects/:name

Create or update a project. Creates if the project doesn't exist, updates if it does.

Parameter	Description
description	Project description

Example Request

curl -X PUT https://cloud.ready.dev/api/projects/my-saas-app \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description"}'

Response

{
  "project": {
    "name": "my-saas-app",
    "description": "Updated description",
    "resource_count": 2,
    "created_at": "2026-01-10T08:00:00Z",
    "updated_at": "2026-02-01T09:30:00Z"
  }
}

DELETE /projects/:name

Delete a project. The project must have no resources.

Response

{
  "status": "deleted",
  "project": "my-saas-app"
}

Resources

Resources are deployable units within a project — a GitHub repo, Docker container, managed database, or manual instance. Each resource runs on one or more hosts in your cluster.

GET /resources/:project

List all resources in a project.

Example Request

curl https://cloud.ready.dev/api/resources/my-saas-app \
  -H "Authorization: Bearer your_api_key_here"

Response

{
  "project": "my-saas-app",
  "resources": [
    {
      "name": "web",
      "state": "active",
      "resource_type": "github",
      "deployment_hash": "abc123",
      "instance_config": {
        "cpu": 2,
        "memory": 4.0,
        "storage": 20.0,
        "github_repo_url": "https://github.com/acme/web.git",
        "branch_name": "main"
      },
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-02-20T14:00:00Z",
      "project": "my-saas-app",
      "hosts": ["host-1"],
      "health_checks": [
        {
          "check_type": "http",
          "target": "/health",
          "port": 3000,
          "expected_status_code": 200,
          "expected_text": null,
          "timeout": 5,
          "status": "healthy",
          "last_checked_at": "2026-02-24T14:20:00Z"
        }
      ],
      "domains": [
        {
          "domain": "example.com",
          "subdomain": "app",
          "internal_port": 3000
        }
      ]
    }
  ]
}

GET /resources/:project/:name

Retrieve details for a specific resource.

Response

{
  "resource": {
    "name": "web",
    "state": "active",
    "resource_type": "github",
    "deployment_hash": "abc123",
    "instance_config": {
      "cpu": 2,
      "memory": 4.0,
      "storage": 20.0,
      "github_repo_url": "https://github.com/acme/web.git",
      "branch_name": "main"
    },
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-20T14:00:00Z",
    "project": "my-saas-app",
    "hosts": ["host-1"],
    "health_checks": [],
    "domains": []
  }
}

PUT /resources/:project/:name

Create or update a resource. Automatically triggers a deployment. If the project doesn't exist, it will be created.

Parameter	Description
resource[resource_type]	(required) One of: `github`, `dockerfile`, `manual`, `mysql`, `postgres`, `clickhouse`
resource[state]	Resource state
resource[hosts]	Host names to deploy on (defaults to first host)
resource[instance_config]	Instance configuration (see below)
resource[domains]	Domain routing configuration
resource[health_checks_attributes]	Health check configuration

The instance_config object supports the following fields depending on resource type:

Field	Description
cpu	CPU cores (integer)
memory	Memory in GB (float)
storage	Storage in GB (float)
github_repo_url	GitHub repository URL (for `github` type)
branch_name	Branch to deploy (for `github` type)
project_folder	Subfolder in repo (for `github` type)
base_image	Base image name (for `github` type)
dockerfile_content	Inline Dockerfile (for `dockerfile` type)
docker_image	Docker Hub image (for `dockerfile` type)
docker_tag	Docker tag (for `dockerfile` type)
registry_username	Private registry username
registry_password	Private registry password
env_vars	Environment variables: `[{"key": "...", "value": "...", "include_in_build": true}]`
exposed_ports	Ports to expose: `[3000, 8080]`
injected_files	Files to inject: `[{"path": "...", "content": "...", "location": "..."}]`
persistent_volumes	Persistent volume paths

Example Request

curl -X PUT https://cloud.ready.dev/api/resources/my-saas-app/web \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": {
      "resource_type": "github",
      "instance_config": {
        "cpu": 2,
        "memory": 4.0,
        "storage": 20.0,
        "github_repo_url": "https://github.com/acme/web.git",
        "branch_name": "main",
        "base_image": "ruby",
        "env_vars": [
          {"key": "RAILS_ENV", "value": "production", "include_in_build": false}
        ]
      },
      "domains": {
        "0": {
          "subdomain": "app",
          "domain": "example.com",
          "port": 3000
        }
      }
    }
  }'

Response (201)

{
  "status": "created",
  "resource": {
    "name": "web",
    "state": "active",
    "resource_type": "github",
    "deployment_hash": "def456",
    "instance_config": {
      "cpu": 2,
      "memory": 4.0,
      "storage": 20.0,
      "github_repo_url": "https://github.com/acme/web.git",
      "branch_name": "main",
      "base_image": "ruby",
      "env_vars": [
        {"key": "RAILS_ENV", "value": "production", "include_in_build": false}
      ]
    },
    "created_at": "2026-02-24T14:22:00Z",
    "updated_at": "2026-02-24T14:22:00Z",
    "project": "my-saas-app",
    "hosts": ["host-1"],
    "health_checks": [],
    "domains": [
      {
        "domain": "example.com",
        "subdomain": "app",
        "internal_port": 3000
      }
    ]
  }
}

POST /resources/:project/:name/clone

Clone an existing resource. Only allows upsizing — CPU, memory, and storage cannot be decreased.

Parameter	Description
resource[name]	(required) Name for the cloned resource
resource[clone_data]	Clone data as well (for databases)
resource[state]	Override state on the clone
resource[hosts]	Override hosts on the clone
resource[instance_config]	Override `cpu`, `memory`, `storage` (upsizing only)

Example Request

curl -X POST https://cloud.ready.dev/api/resources/my-saas-app/web/clone \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": {
      "name": "web-staging",
      "instance_config": {
        "cpu": 4,
        "memory": 8.0
      }
    }
  }'

Response (201)

{
  "status": "cloned",
  "resource": {
    "name": "web-staging",
    "state": "active",
    "resource_type": "github",
    "deployment_hash": "ghi789",
    "instance_config": {
      "cpu": 4,
      "memory": 8.0,
      "storage": 20.0
    },
    "created_at": "2026-02-24T15:00:00Z",
    "updated_at": "2026-02-24T15:00:00Z",
    "project": "my-saas-app",
    "hosts": ["host-1"],
    "health_checks": [],
    "domains": []
  }
}

DELETE /resources/:project/:name

Delete a resource.

Response

{
  "status": "deleted",
  "project": "my-saas-app",
  "resource": "web"
}

Deploys

Check the status of a specific deployment by its hash. Deploys are triggered automatically when you create or update a resource.

GET /resources/:project/:name/deploys/:hash

Get the status of a deployment.

Example Request

curl https://cloud.ready.dev/api/resources/my-saas-app/web/deploys/abc123 \
  -H "Authorization: Bearer your_api_key_here"

Response

{
  "status": "completed",
  "started_at": "2026-02-24T14:22:00Z",
  "completed_at": "2026-02-24T14:23:15Z",
  "log": "Building image...\nDeploying to host-1...\nDeploy complete."
}

Errors

The API uses standard HTTP status codes. Error responses include a JSON body with error and message fields.

Error Response

{
  "error": "Not found",
  "message": "Project 'nonexistent' not found"
}

Status	Meaning
401	Missing or invalid API key
403	API key lacks required permission or project access
404	Project or resource not found
409	Conflict (e.g. duplicate domain configuration)
422	Validation error (e.g. deleting a project that has resources)
429	Rate limited — back off and retry after a delay

Examples

Deploy a GitHub repo

curl -X PUT https://cloud.ready.dev/api/resources/my-project/web \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": {
      "resource_type": "github",
      "instance_config": {
        "cpu": 2,
        "memory": 4.0,
        "storage": 20.0,
        "github_repo_url": "https://github.com/acme/web.git",
        "branch_name": "main",
        "base_image": "ruby",
        "exposed_ports": [3000],
        "env_vars": [
          {"key": "RAILS_ENV", "value": "production"}
        ]
      },
      "domains": {
        "0": {"subdomain": "app", "domain": "example.com", "port": 3000}
      }
    }
  }'

Create a MySQL database

curl -X PUT https://cloud.ready.dev/api/resources/my-project/db \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": {
      "resource_type": "mysql",
      "instance_config": {
        "cpu": 2,
        "memory": 4.0,
        "storage": 50.0,
        "mysql_username": "app",
        "mysql_password": "secret",
        "default_database": "myapp_production"
      }
    }
  }'

Create a manual instance with an SSH key

curl -X PUT https://cloud.ready.dev/api/resources/my-project/bastion \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": {
      "resource_type": "manual",
      "instance_config": {
        "cpu": 1,
        "memory": 1.0,
        "storage": 10.0,
        "ssh_keys": "ssh-ed25519 AAAAC3Nza... user@host"
      }
    }
  }'

Re-trigger a deploy

curl -X PUT https://cloud.ready.dev/api/resources/my-project/web \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"resource": {"deploy": true}}'