Instances API

Manage isolated browser instances programmatically.

Overview

The Instances API allows you to create, list, and destroy isolated browser instances. Each instance provides a secure, ephemeral environment for web browsing that's completely isolated from your infrastructure.

List Instances

GET

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

Retrieve a list of all running instances for your organization.

Request Example

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

Response Example

{
  "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-1234-5678.legba.app"
    },
    {
      "instance_uuid": "abcd-efgh-ijkl-mnop",
      "status": "running",
      "image": "windows-10",
      "size": "medium",
      "created_at": "2025-01-10T11:30:00Z",
      "access_url": "https://instance-abcd-efgh.legba.app"
    }
  ],
  "total": 2
}

Create Instance

POST

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

Create a new isolated browser instance.

Request Body Parameters

Request Body Parameters
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`

Request Example

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

Response Example

{
  "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-1234-5678.legba.app"
}

Response Fields

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-1234-5678.legba.app`

Destroy Instance

DELETE

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

Terminate and permanently delete a specific instance.

⚠️ Warning

This action is irreversible. All data associated with the instance will be permanently deleted.

Request Example

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

Response: 204 No Content on successful deletion.