Cloud API Reference

The Cloud API is the hosted REST interface for smol cloud.

Use the generated OpenAPI document for the routes and schemas it includes. Specialized operations and newly added fields can land ahead of the website’s generated snapshot, so use this page and the linked lifecycle guides for behavior that the schema does not yet describe.

Authentication

Create an API key in the console and send it as a bearer token:

Authorization: Bearer smk_your_key_here

For shell examples:

export SMOL_CLOUD_TOKEN="smk_your_key_here"
export SMOL_CLOUD_URL="https://api.smolmachines.com"

Keep API keys on trusted servers. Use separate keys for development, CI, and production, and revoke keys that are no longer needed.

Core resources

Machines

Machines are persistent cloud microVMs. The core lifecycle is:

POST   /v1/machines
GET    /v1/machines
GET    /v1/machines/{id}
POST   /v1/machines/{id}/start
POST   /v1/machines/{id}/stop
DELETE /v1/machines/{id}

Machine creation accepts an OCI image or a .smolmachine registry reference as its source. Specify CPU, memory, network policy, environment, working directory, lifecycle limits, mounts, and other supported fields in the create request.

Current defaults are a blocked network, 1 vCPU, and 256 MB of memory. Disks can be configured up to 16 TiB where capacity is available. Check the OpenAPI document for the current request limits.

Commands and sessions

Run a command with:

POST /v1/machines/{id}/exec

command accepts a shell string or an argv array. Requests can also include cwd, env, stdin, timeoutSeconds, stream, and background for detached execution. Verify the generated schema for the deployment you target before relying on optional fields.

Sessions preserve a working directory and environment across related exec calls:

GET    /v1/machines/{id}/sessions
POST   /v1/machines/{id}/sessions
POST   /v1/machines/{id}/sessions/{sessionId}/exec
DELETE /v1/machines/{id}/sessions/{sessionId}

Files

The API supports file upload and download for a machine. Use the current OpenAPI or API Explorer for the path shape and request encoding.

Volumes

Cloud volumes are managed resources:

GET    /v1/volumes
POST   /v1/volumes
GET    /v1/volumes/{id}
DELETE /v1/volumes/{id}

Attach a volume through the machine create request. See Cloud Lifecycle, Storage, and Networking.

Operational endpoints

The Cloud API also provides endpoints for:

  • Running Python or JavaScript through /code
  • Machine events and logs
  • Per-machine usage and cached images
  • Sharing a machine through scoped share links
  • Forking a forkable machine
  • Creating, listing, and restoring snapshots where snapshots are enabled

Use the OpenAPI document or Explorer to inspect the exact routes, request bodies, and feature availability for your account.

Usage and account

Use /v1/usage for usage over a time range. The API also exposes account and billing-meter endpoints where enabled. Plan limits and pricing can change; use the pricing page for current public rates.

API keys

The API supports listing, creating, and revoking keys:

GET    /v1/apikeys
POST   /v1/apikeys
DELETE /v1/apikeys/{id}

The plaintext value of a newly created key is shown once.

Readiness and lifecycle

Do not treat state: "started" as application readiness. Poll GET /v1/machines/{id} until ready is true before executing dependent work or connecting to a published service.

Stopping a machine preserves its stored state. Deleting it removes the machine. See the lifecycle page for billing and storage details.

Errors and request IDs

Use the HTTP status code first. Error bodies may be plain text.

Common statuses include:

  • 400: invalid request
  • 401: missing or invalid credentials
  • 403: insufficient scope
  • 404: resource not found or not owned by the caller
  • 409: conflicting resource
  • 402: billing or budget restriction
  • 422: quota, capacity, or validation constraint
  • 429: rate limit exceeded
  • 500: server error
  • 503: service or feature unavailable

Every response includes x-request-id. A safe client-provided ID is echoed; otherwise the service generates one. Record it with the status and response body when reporting a failed request.

Forks and snapshots

Fork and snapshot routes are specialized cloud operations. They do not move a running local VM into cloud or provide a portable cross-architecture restore format. Snapshot availability depends on the cloud environment; handle an unavailable snapshot feature as a service response, not as a fallback for persistent data.