Instances contract preview

Review the proposed instance lifecycle contract.

Overview

This page sketches the proposed instance lifecycle contract. No concrete public API host is published. The fields, commands, and responses are illustrative.

Proposed list request

GEThttps://{your-api-host}/orgs/{org_uuid}/api/instances

Illustrates a proposed organization instance listing.

Illustrative request

curl -X GET "https://{your-api-host}/orgs/{org_uuid}/api/instances" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Illustrative response

{
  "instances": [
    {
      "instance_uuid": "1234-5678-90ab-cdef",
      "status": "running",
      "image": "ubuntu-20.04",
      "size": "small",
      "created_at": "2025-01-10T12:00:00Z",
      "access_url": "https://instance.example"
    },
    {
      "instance_uuid": "abcd-efgh-ijkl-mnop",
      "status": "running",
      "image": "windows-10",
      "size": "medium",
      "created_at": "2025-01-10T11:30:00Z",
      "access_url": "https://instance.example"
    }
  ],
  "total": 2
}

Proposed create request

POSThttps://{your-api-host}/orgs/{org_uuid}/api/instances

Illustrates a proposed isolated instance request.

Proposed request fields

Proposed request fields
Parameter	Type	Description
`image`required	`string`	The browser image to use for the instance (e.g., ubuntu-20.04, windows-10) Example: `ubuntu-20.04`
`size`required	`string`	The size of the instance. Available sizes: small, medium, large Example: `small`

Illustrative request

curl -X POST "https://{your-api-host}/orgs/{org_uuid}/api/instances" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "ubuntu-20.04",
    "size": "small"
  }'

Illustrative response

{
  "instance_uuid": "1234-5678-90ab-cdef",
  "status": "running",
  "image": "ubuntu-20.04",
  "size": "small",
  "created_at": "2025-01-10T12:00:00Z",
  "access_url": "https://instance.example"
}

Illustrative response fields

Illustrative response fields
Parameter	Type	Description
`instance_uuid`	`string`	Unique identifier for the instance Example: `1234-5678-90ab-cdef`
`status`	`string`	Current status of the instance (running, stopped, terminated) Example: `running`
`image`	`string`	The browser image used for this instance Example: `ubuntu-20.04`
`size`	`string`	The size of the instance Example: `small`
`created_at`	`string`	ISO 8601 timestamp of when the instance was created Example: `2025-01-10T12:00:00Z`
`access_url`	`string`	URL to access the isolated browser instance Example: `https://instance.example`

Proposed delete request

DELETEhttps://{your-api-host}/orgs/{org_uuid}/api/instances/{instance_uuid}

Illustrates a proposed isolated instance deletion.

warning

Under the proposed contract, deletion would be irreversible. The example assumes associated data would also be deleted.

Illustrative request

curl -X DELETE "https://{your-api-host}/orgs/{org_uuid}/api/instances/{instance_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Proposed response: 204 No Content after successful deletion.