Sign Up

Images

Create a build-context upload

POST
/build-contexts

Starts a direct upload of a build-context tar of up to 1 GiB. When the project already holds a verified upload of the same archive in the region, the response is that upload with state ready and no parts. Otherwise PUT each part's bytes to its URL, then call POST /build-contexts/{id}/complete.

Authorization

headerAuthorizationBearer <token>

Bearer project API key.

Scope: write:images

Request Body

application/json
  1. body
bytes*integer

The size of the build-context tar in bytes, at most 1 GiB.

Formatint64
Range1 <= value <= 1073741824
dockerfile?|

Path of the Dockerfile within the context. Defaults to Dockerfile.

region_id?|

The region the image will be built in. When omitted, the project's default region is used, then the organization's, then the platform's default region. A build can use the upload only in this region.

sha256*string

The SHA-256 of the build-context tar, as 64 lowercase hex characters.

tree_hash?|

The canonical tree hash of the build context, as 64 lowercase hex characters. Optional: when set, the upload is refused unless the stored archive hashes to it.

Response Body

The verified upload of the same archive

application/json
  1. response

A build-context upload.

bytes*integer

The size of the build-context tar in bytes.

Formatint64
dockerfile*string

Path of the Dockerfile within the context.

expires_at?|

When a ready upload can no longer be used by a build.

Formatdate-time
id*string

The upload ID.

Formatuuid
part_size?|

The size of every part but the last, in bytes. Set while uploading.

Formatint64
parts*array<>

The parts to upload. Empty once the upload is ready.

region_id*string

The region the upload belongs to.

sha256*string

The SHA-256 of the build-context tar.

state*BuildContextUploadState

uploading until the upload is completed and verified, then ready.

Value in"uploading""ready"
upload_expires_at?|

When an upload that was not completed expires and is deleted. Set while uploading.

Formatdate-time
urls_expire_at?|

When the part URLs stop accepting uploads. Set while uploading.

Formatdate-time
curl -X POST 'https://example.com/build-contexts' \  -H 'Content-Type: application/json' \  -d '{  "bytes": 1,  "sha256": "string"}'
{  "bytes": 0,  "dockerfile": "string",  "expires_at": "2019-08-24T14:15:22Z",  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "part_size": 0,  "parts": [    {      "bytes": 0,      "part_number": 0,      "url": "string"    }  ],  "region_id": "string",  "sha256": "string",  "state": "uploading",  "upload_expires_at": "2019-08-24T14:15:22Z",  "urls_expire_at": "2019-08-24T14:15:22Z"}

Complete a build-context upload

POST
/build-contexts/{id}/complete

Assembles the uploaded parts and verifies the stored archive: its size and SHA-256 must match the declared ones, it must be a well-formed tar, and its Dockerfile must pass the build admission checks. An archive that fails verification is deleted and the upload fails with a 400. Repeating the request on a ready upload returns it unchanged.

Authorization

headerAuthorizationBearer <token>

Bearer project API key.

Scope: write:images

Path Parameters

id*string

The upload ID

Formatuuid

Request Body

application/json
  1. body
region_id*string

The region the upload was created in, as POST /build-contexts returned it. Required: a multi-region deployment routes the request to that region's servers by it.

Response Body

The verified upload

application/json
  1. response

A build-context upload.

bytes*integer

The size of the build-context tar in bytes.

Formatint64
dockerfile*string

Path of the Dockerfile within the context.

expires_at?|

When a ready upload can no longer be used by a build.

Formatdate-time
id*string

The upload ID.

Formatuuid
part_size?|

The size of every part but the last, in bytes. Set while uploading.

Formatint64
parts*array<>

The parts to upload. Empty once the upload is ready.

region_id*string

The region the upload belongs to.

sha256*string

The SHA-256 of the build-context tar.

state*BuildContextUploadState

uploading until the upload is completed and verified, then ready.

Value in"uploading""ready"
upload_expires_at?|

When an upload that was not completed expires and is deleted. Set while uploading.

Formatdate-time
urls_expire_at?|

When the part URLs stop accepting uploads. Set while uploading.

Formatdate-time
curl -X POST 'https://example.com/build-contexts/497f6eca-6276-4993-bfeb-53cbbbba6f08/complete' \  -H 'Content-Type: application/json' \  -d '{  "region_id": "string"}'
{  "bytes": 0,  "dockerfile": "string",  "expires_at": "2019-08-24T14:15:22Z",  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "part_size": 0,  "parts": [    {      "bytes": 0,      "part_number": 0,      "url": "string"    }  ],  "region_id": "string",  "sha256": "string",  "state": "uploading",  "upload_expires_at": "2019-08-24T14:15:22Z",  "urls_expire_at": "2019-08-24T14:15:22Z"}

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,      "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_id": "string",      "region_ids": [        "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, an inline Dockerfile, or the context_upload_id of a build context uploaded with POST /build-contexts; multipart/form-data carries a build context of up to 64 MiB, with the fields name, optional dockerfile (a path within the context), region_id, cpu_arch, and the file field context (a build-context tar).

  1. body
context_upload_id?|

A ready build-context upload from POST /build-contexts to build: the Dockerfile at the upload's dockerfile path, with the uploaded archive as its context. The image must be created in the upload's region. Mutually exclusive with source and dockerfile.

Formatuuid
cpu_arch?|

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

dockerfile?|

An inline, self-contained Dockerfile body to build. Local files cannot be used with COPY or ADD; use multipart/form-data to upload a build context. 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. Reusing an anonymous image only extends its retention. Promote it to keep it. 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_id?|

The region to create the image in. When omitted, the project's default region is used, then the organization's, then the platform's default region.

source?||

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

Response Body

Accepted: a new image build, an identical named import replay (same image id and current pending/building/ready status, no new job), or a failed identical named import retry (same image id, reset to pending with a new job after build admission)

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"}

Search images

GET
/images/search

Searches the project's images using the supplied filters. Results may be briefly stale after a change.

Authorization

headerAuthorizationBearer <token>

Bearer project API key.

Scope: read:images

Query Parameters

q?string

Free text over the image name. A value that is an image ID matches that image exactly.

name?string

Match this exact image name.

name_prefix?string

name starts with this string (case-sensitive).

status?array<>

Comma-separated build statuses. An unrecognized value answers 400.

class?array<>

Comma-separated sandbox classes the image supports.

origin?array<>

Comma-separated origins: how the image was created.

region_ids?string

Comma-separated home region IDs. A broader region (a geo group, or earth) matches every region inside it. An unknown region answers 400. Defaults to every region.

sandbox_id?string

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 return: the project's own (false, the default), the platform's (true), or both (any). Deprecated platform images are never returned.

Value in"true""false""any"
created_start_at?string

Inclusive lower bound on creation time.

Formatdate-time
created_end_at?string

Exclusive upper bound on creation time.

Formatdate-time
updated_start_at?string

Inclusive lower bound on last-modified time.

Formatdate-time
updated_end_at?string

Exclusive upper bound on last-modified time.

Formatdate-time
sort?string

Sort field. Defaults to created_at; ties break on the ID.

Value in"created_at""updated_at""name""bytes"
order?string

Sort order. Defaults to desc.

Value in"asc""desc"
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

Response Body

The page of matching images

application/json
  1. response

A page of matching images.

images*array<>

Matching images in this page.

next_cursor?|

Continuation token for the next page; null on the last page.

total*integer

The number of matching images. Exact when total_relation is eq, and a lower bound of 10000 when it is gte.

Formatint64
Range0 <= value
total_relation*SearchTotalRelation

Whether total is exact (eq) or a lower bound (gte).

Value in"eq""gte"
curl -X GET 'https://example.com/images/search'
{  "images": [    {      "anonymous": true,      "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_id": "string",      "region_ids": [        "string"      ],      "retention": "permanent",      "source": null,      "status": "string",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "next_cursor": "string",  "total": 0,  "total_relation": "eq"}

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.

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; a create cannot ask for less. Set for images captured from a macOS sandbox; null for other images.

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

Image format version: 1 for images imported from Daytona v0, 2 for the current format. See status for image readiness.

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_id*string

The home region.

region_ids*array<string>

Every region where the image is available.

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,  "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_id": "string",  "region_ids": [    "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.

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; a create cannot ask for less. Set for images captured from a macOS sandbox; null for other images.

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

Image format version: 1 for images imported from Daytona v0, 2 for the current format. See status for image readiness.

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_id*string

The home region.

region_ids*array<string>

Every region where the image is available.

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,  "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_id": "string",  "region_ids": [    "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 or snapshot 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 the sandbox disk as an image. A persistent, stopped macOS sandbox produces an image usable by a later macOS create. To capture memory, create a snapshot instead.

Authorization

headerAuthorizationBearer <token>

Bearer project API key.

Scope: write:images, write:sandboxes

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