Sign Up

Images

List images

GET
/images

Images are returned newest first.

Authorization

headerAuthorizationBearer <token>

Bearer project API key.

Scope: read:images

Query Parameters

limit?integer

Maximum number of items to return, 1–200 (default 100)

Formatint64
Range1 <= value <= 200
Default100
cursor?string

Opaque continuation token returned as next_cursor by a previous request

name?string

Match this exact image name.

sandbox_id?string

Return images captured from this sandbox ID.

anonymous?boolean

Return anonymous images when true and named images when false. Defaults to false.

platform?string

Which images to list. Defaults to false.

Value in"true""false""any"

Response Body

The page of images

application/json
  1. response

Page of images (GET /images).

images*array<>

The images in this page.

next_cursor?|

Opaque keyset token for the next page; null on the last page.

curl -X GET 'https://example.com/images'
{  "images": [    {      "anonymous": true,      "available_in": [        "string"      ],      "bytes": 0,      "class": "string",      "created_at": "2019-08-24T14:15:22Z",      "cursor": "string",      "default": true,      "deprecated": true,      "disk_mib": 0,      "error": "string",      "expires_at": "2019-08-24T14:15:22Z",      "format_outdated": true,      "format_version": 0,      "id": "string",      "imported_from": {        "id": "string",        "platform": "string"      },      "layer_count": 0,      "name": "string",      "origin": "string",      "platform": true,      "region": "string",      "retention": "permanent",      "source": null,      "status": "string",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "next_cursor": "string"}

Create an image

POST
/images

Authorization

headerAuthorizationBearer <token>

Bearer project API key.

Scope: write:images

Request Body

Build request. application/json carries a registry or named source; multipart/form-data carries an uploaded build context, with the fields name, optional dockerfile (a path within the context), region, cpu_arch, and the file field context (a build-context tar).

  1. body
cpu_arch?|

The CPU architecture: amd64 or arm64. Omit it to use the region default.

dockerfile?|

An inline, self-contained Dockerfile body to build (no COPY/ADD of local files — use the multipart/form-data variant to upload a real build context). The API synthesizes the trivial single-file context for you. Mutually exclusive with source.

idle_expiry_seconds?|

The idle-retention window in seconds for an anonymous image: the image is deleted once this long has passed without a sandbox being created from it, and every create from the image restarts the clock. Allowed only without name; a named image is permanent, and idle_expiry_seconds with name is a 400. Omitted or -1 uses the maximum, 7 days by default; 1 up to that maximum sets the window; 0, values below -1, and values above the maximum answer 400 IDLE_OUT_OF_RANGE, whose body carries max.

Formatint64
name?|

The project-unique image name. Omit it to create an anonymous image.

region?|

The target region. Omit it to use the project's default.

source?||

A registry image or an existing project image. Mutually exclusive with dockerfile; exactly one source is required.

Response Body

Accepted: the image build

application/json
  1. response

An accepted asynchronous operation.

id*string

The ID of the resource the operation acts on.

status*string

The resource's lifecycle status at acceptance.

curl -X POST 'https://example.com/images' \  -H 'Content-Type: application/json' \  -d '{}'
{  "id": "string",  "status": "string"}

Get an image

GET
/images/{id}

Optionally waits for the image to reach a requested status.

Authorization

headerAuthorizationBearer <token>

Bearer project API key.

Scope: read:images

Path Parameters

id*string

The image ID or name

Query Parameters

wait?string

Block until the resource reaches this status or a terminal status. Omit to return immediately.

timeout_ms?integer

Maximum time to block, in milliseconds. Default 30000, maximum 60000.

Formatint64
Range0 <= value
id_only?boolean

Resolve the path value strictly as an ID, without a name fallback.

Response Body

The image

application/json
  1. response
anonymous*boolean

Whether the image has no permanent name.

available_in*array<string>

Every region where the image is available.

bytes?|

The image size in bytes, or null until the build completes.

Formatint64
class*string

The sandbox class supported by the image.

created_at*string

When the image was created.

Formatdate-time
default*boolean

Whether this is the image a sandbox create without image boots.

deprecated*boolean

Whether this platform image is deprecated. A deprecated image is not listed and cannot be used by name, but its ID still resolves.

disk_mib?|

The disk size in MiB that a macOS sandbox created from this image gets when the create omits disk_mib. Set for saved macOS sandbox disks; null for every other image.

Formatint64
error?|

Build failure reason; null unless status is failed.

expires_at?|

When an anonymous image expires, or null for a permanent image.

Formatdate-time
format_outdated*boolean

format_version is below the current format. Such an image converts on its first Linux sandbox create (which waits queued meanwhile) or ahead of time with POST /images/{id}/convert; other operations refuse it with IMAGE_FORMAT_OUTDATED until then.

format_version*integer

The image's format generation: 1 marks an image imported from Daytona v0, and 2 the platform's current artifact. status is the pipeline state of the artifact at this format.

Formatint32
id*string

The image ID.

imported_from?

The source platform and resource ID when this image was imported.

layer_count?|

The number of filesystem layers, or null until the build completes.

Formatint32
name?|

The image name, or null for an anonymous image.

origin*string

How the image was created.

platform*boolean

Whether the platform publishes this image for every project. A project's own image with the same name takes precedence for that project, and platform images cannot be renamed, converted, or deleted.

region*string

The home region.

retention*ImageRetention

The retention policy: permanent or idle.

Value in"permanent""idle"
source?||||

The image source.

status*string

The build status.

updated_at*string

When the image was last updated.

Formatdate-time
curl -X GET 'https://example.com/images/string'
{  "anonymous": true,  "available_in": [    "string"  ],  "bytes": 0,  "class": "string",  "created_at": "2019-08-24T14:15:22Z",  "default": true,  "deprecated": true,  "disk_mib": 0,  "error": "string",  "expires_at": "2019-08-24T14:15:22Z",  "format_outdated": true,  "format_version": 0,  "id": "string",  "imported_from": {    "id": "string",    "platform": "string"  },  "layer_count": 0,  "name": "string",  "origin": "string",  "platform": true,  "region": "string",  "retention": "permanent",  "source": null,  "status": "string",  "updated_at": "2019-08-24T14:15:22Z"}

Update an image

PATCH
/images/{id}

Naming an anonymous image makes it permanent. Named images cannot be renamed.

Authorization

headerAuthorizationBearer <token>

Bearer project API key.

Scope: write:images

Path Parameters

id*string

The image ID or name

Query Parameters

id_only?boolean

Resolve the path value strictly as an ID, without a name fallback.

Request Body

application/json
  1. body
name*string

The permanent image name.

Response Body

The image

application/json
  1. response
anonymous*boolean

Whether the image has no permanent name.

available_in*array<string>

Every region where the image is available.

bytes?|

The image size in bytes, or null until the build completes.

Formatint64
class*string

The sandbox class supported by the image.

created_at*string

When the image was created.

Formatdate-time
default*boolean

Whether this is the image a sandbox create without image boots.

deprecated*boolean

Whether this platform image is deprecated. A deprecated image is not listed and cannot be used by name, but its ID still resolves.

disk_mib?|

The disk size in MiB that a macOS sandbox created from this image gets when the create omits disk_mib. Set for saved macOS sandbox disks; null for every other image.

Formatint64
error?|

Build failure reason; null unless status is failed.

expires_at?|

When an anonymous image expires, or null for a permanent image.

Formatdate-time
format_outdated*boolean

format_version is below the current format. Such an image converts on its first Linux sandbox create (which waits queued meanwhile) or ahead of time with POST /images/{id}/convert; other operations refuse it with IMAGE_FORMAT_OUTDATED until then.

format_version*integer

The image's format generation: 1 marks an image imported from Daytona v0, and 2 the platform's current artifact. status is the pipeline state of the artifact at this format.

Formatint32
id*string

The image ID.

imported_from?

The source platform and resource ID when this image was imported.

layer_count?|

The number of filesystem layers, or null until the build completes.

Formatint32
name?|

The image name, or null for an anonymous image.

origin*string

How the image was created.

platform*boolean

Whether the platform publishes this image for every project. A project's own image with the same name takes precedence for that project, and platform images cannot be renamed, converted, or deleted.

region*string

The home region.

retention*ImageRetention

The retention policy: permanent or idle.

Value in"permanent""idle"
source?||||

The image source.

status*string

The build status.

updated_at*string

When the image was last updated.

Formatdate-time
curl -X PATCH 'https://example.com/images/string' \  -H 'Content-Type: application/json' \  -d '{  "name": "string"}'
{  "anonymous": true,  "available_in": [    "string"  ],  "bytes": 0,  "class": "string",  "created_at": "2019-08-24T14:15:22Z",  "default": true,  "deprecated": true,  "disk_mib": 0,  "error": "string",  "expires_at": "2019-08-24T14:15:22Z",  "format_outdated": true,  "format_version": 0,  "id": "string",  "imported_from": {    "id": "string",    "platform": "string"  },  "layer_count": 0,  "name": "string",  "origin": "string",  "platform": true,  "region": "string",  "retention": "permanent",  "source": null,  "status": "string",  "updated_at": "2019-08-24T14:15:22Z"}

Delete an image

DELETE
/images/{id}

Deletion is refused while a sandbox, snapshot, or function depends on the image.

Authorization

headerAuthorizationBearer <token>

Bearer project API key.

Scope: delete:images

Path Parameters

id*string

The image ID or name

Query Parameters

id_only?boolean

Resolve the path value strictly as an ID, without a name fallback.

Response Body

Image deleted

curl -X DELETE 'https://example.com/images/string'
Empty

Get an image's build logs URL

GET
/images/{id}/build-logs-url

Authorization

headerAuthorizationBearer <token>

Bearer project API key.

Scope: read:images

Path Parameters

id*string

The image ID or name

Query Parameters

id_only?boolean

Resolve the path value strictly as an ID, without a name fallback.

Response Body

The image build logs URL

application/json
  1. response

A link to build logs.

url*string

The URL for reading the build logs.

curl -X GET 'https://example.com/images/string/build-logs-url'
{  "url": "string"}

Change an image format

POST
/images/{id}/convert

Converts the image to the format the platform currently boots. Repeating the request is safe and returns the in-progress conversion.

Authorization

headerAuthorizationBearer <token>

Bearer project API key.

Scope: write:images

Path Parameters

id*string

The image ID or name

Query Parameters

id_only?boolean

Resolve the path value strictly as an ID, without a name fallback.

Response Body

Accepted: the image conversion

application/json
  1. response

An image format conversion result.

converted*boolean

true when this call started or joined a conversion; false when the image was already at the current format and nothing was enqueued.

from_format*integer

The image's format before the call, as Image.format_version reported it.

Formatint32
id*string

The image ID.

status*string

The image's status after the call: pending/building while it converts, or its own status when it was already at the current format.

to_format*integer

The format the conversion targets: the current one.

Formatint32
curl -X POST 'https://example.com/images/string/convert'
{  "converted": true,  "from_format": 0,  "id": "string",  "status": "string",  "to_format": 0}

Create an image from a sandbox

POST
/sandboxes/{sandbox_id}/images

Captures only the sandbox disk as an image: Linux images have kind disk, Windows images kind block, and a persistent, stopped macOS sandbox saves a macOS image that a later macOS create can start from. To capture memory, create a snapshot instead.

Authorization

headerAuthorizationBearer <token>

Bearer project API key.

Scope: write:images

Path Parameters

sandbox_id*string

The sandbox ID

Request Body

application/json
  1. body
idle_expiry_seconds?|

The idle-retention window in seconds for an anonymous image: the image is deleted once this long has passed without a sandbox being created from it, and every create from the image restarts the clock. Allowed only without name; a named image is permanent, and idle_expiry_seconds with name is a 400. The same rule as POST /images: omitted or -1 uses the maximum, 7 days by default; 1 up to that maximum sets the window; 0, values below -1, and values above the maximum answer 400 IDLE_OUT_OF_RANGE, whose body carries max. Promote the image (PATCH /images/{id}) to keep it.

Formatint64
name?|

The project-unique image name, or null for an anonymous image.

Response Body

Accepted: the sandbox image capture

application/json
  1. response

An accepted asynchronous operation.

id*string

The ID of the resource the operation acts on.

status*string

The resource's lifecycle status at acceptance.

curl -X POST 'https://example.com/sandboxes/string/images' \  -H 'Content-Type: application/json' \  -d '{}'
{  "id": "string",  "status": "string"}

Computersfor Agents

Isolated sandboxes for agent code,
ready in under 100 ms.

Start for Free