Computers are persistent desktop VMs with a Linux desktop, streamed desktop access, and APIs for exec, files, apps, metrics, and desktop control. Base path: /api/v1/computers.

Verbs supported: GET (list/get/config), POST (create/start/stop/restart/clone/resize), PATCH (update), PUT (update), DELETE (delete).

Create a Computer

POST /api/v1/computers

Creates a new computer and begins provisioning.

Request Body

Response - 201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "...",
  "owner_user_id": "...",
  "name": "my-computer",
  "slug": "my-computer",
  "template_type": "miosa-desktop",
  "size": "small",
  "vcpus": 1,
  "memory_mb": 4096,
  "status": "provisioning",
  "vm_id": null,
  "workspace_id": "660e8400-e29b-41d4-a716-446655440001",
  "project_id": "770e8400-e29b-41d4-a716-446655440002",
  "external_workspace_id": null,
  "external_user_id": null,
  "external_project_id": null,
  "sandbox_url": "https://my-computer.sandbox.miosa.ai",
  "desktop_url": "https://my-computer.computer.miosa.ai/desktop/index.html",
  "selected_apps": [],
  "settings": {},
  "ai_config": {},
  "agent_session_id": null,
  "agent_status": null,
  "resolution": "1280x720",
  "auto_stop": 0,
  "created_at": "2026-04-11T00:00:00Z",
  "updated_at": "2026-04-11T00:00:00Z"
}

sandbox_url is a legacy preview field on the Computer response. Use desktop_url for the desktop stream and the /computers/{id}/urls endpoint for short-lived desktop and terminal URLs.

Errors

curl -X POST https://api.miosa.ai/api/v1/computers 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "my-computer",
    "template_type": "miosa-desktop",
    "size": "small",
    "workspace_slug": "dr-smith-clinic",
    "workspace_name": "Dr. Smith Clinic",
    "project_slug": "records-portal",
    "project_name": "Records Portal",
    "external_workspace_id": "clinic_123",
    "external_user_id": "dr-smith-456",
    "external_project_id": "project_789"
  }'

List Computers

GET /api/v1/computers

Returns all computers belonging to the authenticated user’s tenant.

Query Parameters

Response - 200 OK

{
  "computers": [
    {
      "id": "...",
      "name": "my-computer",
      "status": "running",
      "size": "small",
      "created_at": "2026-04-11T00:00:00Z"
    }
  ],
  "total": 1
}

# All computers
curl https://api.miosa.ai/api/v1/computers 
  -H "Authorization: Bearer $MIOSA_API_KEY"

# Filtered to a workspace
curl "https://api.miosa.ai/api/v1/computers?workspace_id=660e8400-e29b-41d4-a716-446655440001" 
  -H "Authorization: Bearer $MIOSA_API_KEY"

# Filtered to a project
curl "https://api.miosa.ai/api/v1/computers?project_id=770e8400-e29b-41d4-a716-446655440002" 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Get a Computer

GET /api/v1/computers/{id}

Path Parameters

Response - 200 OK

Full computer object (same as create response, with current status).

Errors

curl https://api.miosa.ai/api/v1/computers/{id} 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Update a Computer

PATCH /api/v1/computers/{id}

Currently supports updating agent_session_id only.

Request Body

Response - 200 OK

Updated computer object.

curl -X PATCH https://api.miosa.ai/api/v1/computers/{id} 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"agent_session_id": "session-uuid"}'

Delete a Computer

DELETE /api/v1/computers/{id}

Permanently destroys the VM and removes the computer record.

Response - 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "deleted": true
}

Errors

curl -X DELETE https://api.miosa.ai/api/v1/computers/{id} 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Start a Computer

POST /api/v1/computers/{id}/start

Resumes a stopped or paused computer.

Response - 200 OK

Updated computer object with status: "running".

Errors

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/start 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Stop a Computer

POST /api/v1/computers/{id}/stop

Pauses a running computer. Can be restarted later.

Response - 200 OK

Updated computer object with status: "stopped".

Errors

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/stop 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Restart a Computer

POST /api/v1/computers/{id}/restart

Stops and immediately restarts a running computer.

Response - 200 OK

Updated computer object.

Errors

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/restart 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Get Auto-Stop Configuration

GET /api/v1/computers/{id}/auto-stop

Response - 200 OK

{
  "auto_stop_seconds": 3600,
  "enabled": true
}

curl https://api.miosa.ai/api/v1/computers/{id}/auto-stop 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Update Auto-Stop Configuration

PATCH /api/v1/computers/{id}/auto-stop

Request Body

Response - 200 OK

Updated auto-stop configuration.

curl -X PATCH https://api.miosa.ai/api/v1/computers/{id}/auto-stop 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"auto_stop_seconds": 3600}'

Get Desktop Stream Credentials

GET /api/v1/computers/{id}/vnc-credentials

Returns credentials for direct desktop streaming access.

Response - 200 OK

{
  "desktop_url": "https://my-computer.computer.miosa.ai/desktop/index.html",
  "ws_url": "wss://my-computer.computer.miosa.ai/ws/vnc/550e8400-e29b-41d4-a716-446655440000?auth=stream_token",
  "token": "stream_auth_token",
  "expires_at": 1712700060,
  "computer_id": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-computer"
}

curl https://api.miosa.ai/api/v1/computers/{id}/vnc-credentials 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Get Stream Token

POST /api/v1/computers/{id}/stream-token

Returns a time-limited auth token for desktop and terminal WebSocket connections.

Response - 200 OK

{
  "token": "stream_auth_token",
  "expires_at": 1712700060
}

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/stream-token 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Get Computer URLs

GET /api/v1/computers/{id}/urls

Returns all connection URLs for the computer.

Response - 200 OK

{
  "desktop_url": "https://my-computer.computer.miosa.ai/desktop/index.html",
  "stream_url": "https://my-computer.computer.miosa.ai/desktop/index.html",
  "terminal_url": "wss://my-computer.computer.miosa.ai/ws/terminal/550e8400-e29b-41d4-a716-446655440000",
  "computer_id": "550e8400-e29b-41d4-a716-446655440000"
}

curl https://api.miosa.ai/api/v1/computers/{id}/urls 
  -H "Authorization: Bearer $MIOSA_API_KEY"

List Installed Apps

GET /api/v1/computers/{id}/apps

Returns the list of applications installed on the computer.

Response - 200 OK

Response containing the list of installed applications.

curl https://api.miosa.ai/api/v1/computers/{id}/apps 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Clone a Computer

POST /api/v1/computers/{id}/clone

Creates a new computer from the current state of an existing one. The source computer must be running; the clone starts in provisioning and progresses to running.

Response - 201 Created

Full computer object for the new clone with its own ID.

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/clone 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Resize a Computer

POST /api/v1/computers/{id}/resize

Changes the vCPU and memory allocation. The computer must be stopped first.

Request Body

Response - 200 OK

Updated computer object with new size, vcpus, and memory_mb.

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/resize 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"size": "medium"}'

Move a Computer

POST /api/v1/computers/{id}/move

Migrates a computer to a different region. The computer must be stopped. Live migration is not supported; the computer will be moved offline.

Request Body

Response - 200 OK

Updated computer object with new region.

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/move 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"region": "us-east-ny"}'

Get Metrics

GET /api/v1/computers/{id}/metrics

Returns time-series CPU, RAM, and credit-burn metrics. Useful for dashboards and auto-stop logic.

Query Parameters

Response - 200 OK

{
  "cpu_percent": [
    {"ts": "2026-05-17T10:00:00Z", "value": 12.4},
    {"ts": "2026-05-17T10:01:00Z", "value": 8.1}
  ],
  "memory_percent": [
    {"ts": "2026-05-17T10:00:00Z", "value": 45.2}
  ],
  "credits_per_hour": 3
}

curl "https://api.miosa.ai/api/v1/computers/{id}/metrics?window=1h" 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Env Vars

Encrypted per-computer environment variables. Values are decrypted at boot and injected into the VM environment.

List

GET /api/v1/computers/{id}/env

curl https://api.miosa.ai/api/v1/computers/{id}/env 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Create

POST /api/v1/computers/{id}/env

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/env 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"name": "DATABASE_URL", "value": "postgres://user:pass@host/db"}'

Update

PATCH /api/v1/computers/{id}/env/{name}

Delete

DELETE /api/v1/computers/{id}/env/{name}

Returns 200 OK.

Port Exposure

Control per-port visibility for services running inside the computer.

List Ports

GET /api/v1/computers/{id}/ports

Expose a Port

POST /api/v1/computers/{id}/ports

Update Port Visibility

PATCH /api/v1/computers/{id}/ports/{port}

Remove Port

DELETE /api/v1/computers/{id}/ports/{port}

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/ports 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"port": 3000, "visibility": "public"}'

Common Errors

See also

• Desktop API - screenshot, click, type, scroll, drag, windows
• Files API - read, write, stat, mkdir, rename, copy, chmod, download
• Exec API - bash and Python execution
• Snapshots API - create, restore, and delete checkpoints
• Events (SSE) - computer lifecycle event stream
• Regions - available regions for computer placement