v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Provision a computer for an agent

Creates and provisions a new computer resource associated with the specified agent. The computer is allocated in the requested region (defaulting to iad) and its status transitions from provisioning to running once it is ready.

Requires an app-scoped API key. The agent identified by agent must belong to the same app. Supplying a lookup_key lets you retrieve this computer later without storing its ID — the key must be unique within the app.

post/api/v1/agents/{agent}/agent_computers

Path parameters

agentstring required

Agent ID (agt_...). The computer is associated with this agent.

Request body

configobject

Provider-specific configuration for the computer. Supported keys vary by region and plan.

lookup_keystring

Stable, user-defined key for this computer. Must be unique within the app. Use it to look up the computer without storing its ID.

metadataobject

Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads.

namestring required

Human-readable display name for the computer.

regionstring

Region in which to provision the computer, e.g. "iad". Defaults to "iad" when omitted.

Example request

{
  "config": {},
  "lookup_key": "string",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "region": "string"
}

Response

Successful response

agentstring

ID of the agent that owns this computer (agi_...). null if the computer is not yet assigned to an agent.

appstring

ID of the app this computer belongs to (dap_...).

configobject

Provider-specific configuration key-value pairs for the computer. Structure depends on the underlying compute provider.

created_atstring date-time

When the computer was created (ISO 8601).

error_messagestring

Human-readable error description when status is "error". null otherwise.

idstring required

Computer ID (cmp_...).

last_active_atstring date-time

When the computer last reported activity or received a command. null if the computer has never been active.

lookup_keystring

Unique, stable identifier you assign to this computer within its app. null if not set.

metadataobject

Arbitrary key-value metadata you attached to the computer. null if none was provided.

namestring

Human-readable display name for the computer. null if not set.

regionstring

Cloud region where the computer is hosted, e.g. "us-east-1". null if not yet assigned.

sprite_urlstring

URL of the live screenshot sprite used to render a real-time preview of the computer's screen. null when no sprite is available.

statusstring

Current lifecycle state of the computer. Common values include "provisioning", "ready", "error", and "terminated".

updated_atstring date-time

When the computer record was last modified (ISO 8601).

Example response

{
  "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
  "config": {
    "key": "value"
  },
  "created_at": "2024-01-01T00:00:00Z",
  "error_message": "string",
  "id": "cmp_0aBcDeFgHiJkLmNoPqRsTu",
  "last_active_at": "2024-01-01T00:00:00Z",
  "lookup_key": "main-computer",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "region": "us-east-1",
  "sprite_url": "https://example.com",
  "status": "ready",
  "updated_at": "2024-01-01T00:00:00Z"
}