Public REST API · v1

Runtime Clusters API

Drive every container in your cluster from code. Create, resize, power-cycle, delete — same rules as the dashboard, zero compromise.

8 results

Base URL

All endpoints are versioned and live under:

https://freemchost.com/api/public/clusters/v1

Authentication

Generate API keys from your cluster page (max 10 per cluster). Each request must include the key as a bearer token:

Authorization: Bearer fmch_xxx

The secret value is shown only once at creation time. Store it in a secrets manager — losing it means generating a new key.

Cluster

GET

/cluster

Get cluster details

Returns metadata about the authenticated cluster: plan, totals, used and remaining resources.

curl https://freemchost.com/api/public/clusters/v1/cluster \
  -H "Authorization: Bearer fmch_xxx"

GET

/capacity

Get capacity snapshot

Lightweight capacity payload: only totals and used resources. Useful for dashboards and scheduling logic.

curl https://freemchost.com/api/public/clusters/v1/capacity \
  -H "Authorization: Bearer fmch_xxx"

GET

/eggs

List allowed eggs

Returns the whitelist of server types (eggs) you may use when creating containers in this cluster.

curl https://freemchost.com/api/public/clusters/v1/eggs \
  -H "Authorization: Bearer fmch_xxx"

Containers

GET

/containers

List containers

Returns every container belonging to the cluster, with status and current allocation.

curl https://freemchost.com/api/public/clusters/v1/containers \
  -H "Authorization: Bearer fmch_xxx"

POST

/containers

Create a container

Provisions a new container inside the cluster. Allocation must fit within remaining capacity.

{
  "name": "build-runner",
  "egg_id": "<uuid from /eggs>",
  "cpu_cores": 1,
  "ram_mb": 1024,
  "storage_mb": 5120,
  "io": 100,
  "ports": 1,
  "databases": 0,
  "backups": 0
}

PATCH

/containers/:id

Update a container

Rename, switch egg, and/or resize a container. All fields are optional; resources can be partial — missing values keep their current allocation.

{
  "name": "build-runner-2",
  "egg_id": "<optional uuid>",
  "resources": {
    "ram_mb": 2048,
    "cpu_cores": 2
  }
}

DELETE

/containers/:id

Delete a container

Permanently destroys the container and frees its resources back into the cluster pool.

curl https://freemchost.com/api/public/clusters/v1/containers/a1b2… \
  -H "Authorization: Bearer fmch_xxx" \
  -X DELETE

POST

/containers/:id/power

Power signal

Send a power signal to the container: start, stop or restart.

{ "signal": "start" | "stop" | "restart" }

Errors

Every error returns a JSON body shaped as:

{ "error": { "code": "capacity_exceeded", "message": "Not enough RAM left in the pool." } }

Code	HTTP	Meaning
unauthorized	401	Missing or invalid bearer token.
invalid_cluster	403	Cluster is not active, suspended or expired.
invalid_input	400	Request body failed validation. Inspect the message.
below_minimum	400	An allocation field is below its minimum.
egg_not_allowed	400	Egg not in the cluster whitelist.
capacity_exceeded	409	Not enough remaining resources in the cluster pool.
container_limit_reached	409	Cluster already has the maximum number of containers.
action_not_allowed	409	Container state forbids this action (e.g. being provisioned).
not_found	404	Cluster, container or route does not exist.
forbidden	403	Caller lacks permission for this resource.
server_error	500	Unexpected backend error. Retry later.

Ready to automate?

Generate your first key from any cluster you own.