Images

Named images are project-scoped, pre-built boot artifacts. Building is asynchronous: POST /images returns a job_id and the image starts pending, becoming ready or failed. Sandboxes can then reference the image by name on POST /vms. See Image Sources and the Images concept guide.

POST /images (JSON)

Build (or re-build) a named image from a registry reference. Re-posting an existing name replaces its source and re-triggers the build. If the project has a registry credential matching the ref's host, the pull authenticates automatically.

Request

Field	Type	Required / default	Description
`name`	string	required	Project-unique image name.
`source`	object	required	Image source, e.g. `{ "type": "registry", "ref": "node:20" }`.
`docker`	bool	`false`	Mark the image Docker-capable: sandboxes created from it get a dedicated Docker data device by default.
`region`	string	resolved default	Home region for the build. Other regions replicate the artifact on first use.

cURL

curl -X POST https://api.rl.trydaytona.com/images \
  -H "Authorization: Bearer $RLP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "node-base",
    "source": { "type": "registry", "ref": "node:20" }
  }'

{
  "image_id": "4b6f2a91-3c8d-4f70-b1e5-9a2d07c3e816",
  "job_id": "a90d3e57-1f24-4c6b-8e02-5b7f9c1d4a38",
  "name": "node-base",
  "status": "pending",
  "region": "us1"
}

Errors

400 — invalid JSON, or an unknown/disabled region.
503 — build queue temporarily degraded; nothing was enqueued, safe to retry.

POST /images (multipart)

Build a named image from a Dockerfile and build context. Send multipart/form-data:

Field	Type	Required / default	Description
`name`	text	required	Project-unique image name.
`context`	file	required	Build context as a tar archive.
`dockerfile`	text	`"Dockerfile"`	Path to the Dockerfile within the context.
`docker`	text	`false`	`1`/`true`/`yes`/`on` to mark the image Docker-capable.
`region`	text	resolved default	Home region for the build.

cURL

tar -cf context.tar Dockerfile app/
curl -X POST https://api.rl.trydaytona.com/images \
  -H "Authorization: Bearer $RLP_API_KEY" \
  -F "name=my-app" \
  -F "dockerfile=Dockerfile" \
  -F "context=@context.tar"

The response is the same shape as the JSON form.

Errors

400 — missing name, missing context file, malformed multipart body, or an unknown/disabled region.

GET /images

List the project's images, newest first, with cursor pagination (limit default 100, max 200; cursor from a previous next_cursor).

cURL

curl "https://api.rl.trydaytona.com/images?limit=1" \
  -H "Authorization: Bearer $RLP_API_KEY"

{
  "images": [
    {
      "id": "4b6f2a91-3c8d-4f70-b1e5-9a2d07c3e816",
      "name": "node-base",
      "source": { "type": "registry", "ref": "node:20" },
      "manifest_name": "mani-4b6f2a.json",
      "status": "ready",
      "layer_count": 8,
      "docker": false
    }
  ],
  "next_cursor": null
}

Image statuses: pending → ready | failed. manifest_name and layer_count are set once the build completes.

GET /jobs/:id

Poll a background job — image builds, sandbox creates, and snapshot captures all return a job_id. A job is visible only when the sandbox or image it acts on belongs to the caller's project.

cURL

curl https://api.rl.trydaytona.com/jobs/a90d3e57-1f24-4c6b-8e02-5b7f9c1d4a38 \
  -H "Authorization: Bearer $RLP_API_KEY"

{
  "id": "a90d3e57-1f24-4c6b-8e02-5b7f9c1d4a38",
  "kind": "build",
  "status": "done",
  "attempts": 1,
  "error": null,
  "runner_id": "runner-a12"
}

Job statuses: queued → running → done | failed. Job kinds include build, vm.create, and snapshot.create.

Note: polling the resource itself (GET /images, GET /vms/:id?wait=, GET /snapshots/:id?wait=ready) is usually more convenient than polling the job.

Errors

404 — unknown job, or a job whose resource belongs to another project.

On this page