Workspaces API

Workspaces group resources inside an organization. In a white-label platform, a workspace usually represents one downstream customer or client, such as Acme Corp inside the Lumen organization. Projects live inside workspaces, and sandboxes, computers, deployments, databases, storage buckets, volumes, functions, jobs, and domains belong to projects.

Base path: /api/v1/workspaces

Quick Start

import { Miosa } from '@miosa/sdk';

const client = new Miosa(); // reads MIOSA_API_KEY

// Create a workspace for a downstream customer
const ws = await client.workspaces.create({
  name: 'Acme Corp',
  slug: 'acme-corp',
  externalWorkspaceId: 'acct_123',
});

// Create a computer inside a project in that workspace
const computer = await client.computers.create({
  name: 'workspace-builder',
  template_type: 'miosa-desktop',
  workspaceId: ws.id,
  projectSlug: 'lead-magnet',
  projectName: 'Lead Magnet',
});

// List computers in the workspace
const { data } = await client.workspaces.listComputers(ws.id);

# curl equivalent
curl -X POST https://api.miosa.ai/api/v1/workspaces \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "slug": "acme-corp", "external_workspace_id": "acct_123"}'

Endpoints

List Workspaces

GET /api/v1/workspaces

Returns all workspaces belonging to the authenticated tenant.

Response - 200 OK

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "...",
      "name": "default",
      "slug": "default",
      "external_workspace_id": null,
      "description": null,
      "metadata": {},
      "is_default": true,
      "computer_count": 3,
      "created_at": "2026-04-11T00:00:00Z",
      "updated_at": "2026-04-11T00:00:00Z"
    }
  ],
  "total": 1
}

curl https://api.miosa.ai/api/v1/workspaces \
  -H "Authorization: Bearer $MIOSA_API_KEY"

Create a Workspace

POST /api/v1/workspaces

Request Body

Response - 201 Created

Full workspace object (same shape as list items above).

Errors

curl -X POST https://api.miosa.ai/api/v1/workspaces \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme-corp",
    "external_workspace_id": "acct_123",
    "description": "Client workspace for Acme Corp"
  }'

Get a Workspace

GET /api/v1/workspaces/{id}

Path Parameters

Response - 200 OK

Full workspace object.

Errors

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

Update a Workspace

PATCH /api/v1/workspaces/{id}

Update mutable workspace fields. Prefer treating the slug as stable once resources and URLs exist.

Request Body

Response - 200 OK

Updated workspace object.

Errors

curl -X PATCH https://api.miosa.ai/api/v1/workspaces/{id} \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "production-us-east"}'

Delete a Workspace

DELETE /api/v1/workspaces/{id}

Deletes an empty workspace. Fails if the workspace contains computers or projects.

Response - 200 OK

{ "deleted": true }

Errors

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

Update Workspace Settings

PUT /api/v1/workspaces/{id}/settings

Applies resource limits and default preferences for the workspace. These limits cap what any computer inside the workspace can do. Tenant-level limits still apply as a ceiling.

Request Body

Nothing is destroyed and nothing resumes by itself. The setting is named spend_cap_action, not action.

Response - 200 OK

{
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "settings": {
    "max_computers": 10,
    "max_computer_size": "large",
    "default_computer_size": "small",
    "default_auto_stop_seconds": 3600,
    "allowed_template_types": []
  },
  "updated_at": "2026-05-17T10:00:00Z"
}

Domains

Workspaces do not own a preview domain. Preview domains are an organization setting, and per-deployment custom domains are attached to the deployment:

• Custom Domains API - the organization preview domain and deployment/computer custom domains.

Errors

curl -X PUT https://api.miosa.ai/api/v1/workspaces/{id}/settings \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "max_computers": 10,
    "max_computer_size": "large",
    "default_auto_stop_seconds": 3600
  }'

List Computers in a Workspace

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

Response - 200 OK

{
  "data": [
    {
      "id": "...",
      "name": "runner-1",
      "status": "running",
      "size": "small",
      "template_type": "miosa-desktop",
      "created_at": "2026-04-11T00:00:00Z"
    }
  ],
  "total": 1
}

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

List Projects in a Workspace

GET /api/v1/workspaces/{id}/projects

Returns the projects owned by a workspace. Use this for client dashboards before listing the sandboxes, computers, deployments, and databases inside a project.

Response - 200 OK

{
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "tenant_id": "...",
      "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
      "external_workspace_id": "acct_123",
      "external_project_id": "project_789",
      "name": "Lead Magnet",
      "slug": "lead-magnet",
      "description": null,
      "metadata": {},
      "created_at": "2026-05-18T10:00:00Z",
      "updated_at": "2026-05-18T10:00:00Z"
    }
  ],
  "total": 1
}

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

Get Workspace Stats

GET /api/v1/workspaces/{id}/stats

Returns a snapshot of computer counts grouped by status and the aggregate resource footprint for the workspace.

Response - 200 OK

{
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "computers": {
    "total": 5,
    "by_status": {
      "running": 3,
      "stopped": 2,
      "provisioning": 0,
      "error": 0
    }
  },
  "resources": {
    "total_vcpus": 7,
    "total_memory_mb": 28672,
    "total_disk_gb": 160
  },
  "settings": {
    "max_computers": 10,
    "max_computer_size": "large",
    "default_auto_stop_seconds": 3600
  }
}

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

Get Workspace Usage

GET /api/v1/workspaces/{id}/usage

Returns time-series credit consumption and compute-hour totals for the workspace over a given window. Use this for per-workspace cost attribution dashboards.

Query Parameters

Response - 200 OK

{
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "window": "7d",
  "granularity": "day",
  "total_credits_used": 1284,
  "total_compute_hours": 42.5,
  "series": [
    {
      "ts": "2026-05-10T00:00:00Z",
      "credits_used": 198,
      "compute_hours": 6.6
    },
    {
      "ts": "2026-05-11T00:00:00Z",
      "credits_used": 211,
      "compute_hours": 7.0
    }
  ]
}

Errors

curl "https://api.miosa.ai/api/v1/workspaces/{id}/usage?window=7d&granularity=day" \
  -H "Authorization: Bearer $MIOSA_API_KEY"

Common Recipes

Move all computers to a new workspace

Computers do not yet support a move operation on workspace assignment via PATCH /computers/{id}. Use the POST /computers/{id}/move endpoint instead:

curl -X POST https://api.miosa.ai/api/v1/computers/{computer_id}/move \
  -H "Authorization: Bearer $MIOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workspace_id": "target-workspace-id"}'

Enumerate all workspaces and their sizes

const { data: workspaces } = await client.workspaces.list();
for (const ws of workspaces) {
  console.log(`${ws.name}: ${ws.computerCount} computers`);
}

Default workspace ID lookup

If you need the default workspace ID programmatically:

const { data } = await client.workspaces.list();
const defaultWs = data.find(ws => ws.isDefault);
console.log(defaultWs.id);

Common Errors

See also

• Computers API - computers are scoped to workspaces
• Projects API - projects live inside workspaces
• Error Codes - VALIDATION_FAILED and general errors