Workspaces API

Internal Application API

These are internal SPA routes (cookie/session authenticated, used by the Studio app), not a versioned public contract — they may change between releases. For external integrations, use the Public API.

Workspaces are the top-level billing entity in Studio. Each user has a primary workspace created at signup, and can create or be invited to secondary workspaces.

List Workspaces

List all workspaces the current user belongs to.

GET /api/workspaces

Response

[
  {
    "id": "uuid",
    "name": "My Workspace",
    "slug": "my-workspace",
    "type": "primary",
    "plan": "starter",
    "role": "owner",
    "github_installation_id": 12345
  }
]

---

Create Workspace

Create a new secondary workspace.

POST /api/workspaces

Request Body

Field	Type	Required	Description
name	string	Yes	Workspace display name
slug	string	Yes	URL slug (lowercase, alphanumeric, hyphens)

Response

{
  "id": "uuid",
  "name": "Team Workspace",
  "slug": "team-workspace",
  "type": "secondary"
}

---

Get Workspace

Get workspace details including billing information.

GET /api/workspaces/:workspaceId

Response

{
  "id": "uuid",
  "name": "My Workspace",
  "slug": "my-workspace",
  "type": "primary",
  "plan": "starter",
  "github_installation_id": 12345,
  "owner_id": "uuid"
}

Auth

Requires workspace membership.

---

Update Workspace

Update workspace name or settings.

PATCH /api/workspaces/:workspaceId

Request Body

Field	Type	Required	Description
name	string	No	New workspace name

Auth

Requires workspace owner or admin role.

---

Delete Workspace

Delete a workspace and all its projects.

DELETE /api/workspaces/:workspaceId

Auth

Requires workspace owner role. Primary workspaces cannot be deleted (delete the user account instead).

---

Transfer Ownership

Transfer workspace ownership to another member.

POST /api/workspaces/:workspaceId/transfer-owner

Request Body

Field	Type	Required	Description
newOwnerId	string	Yes	User ID of the new owner

Auth

Requires current workspace owner role.

---

Members

List Members

GET /api/workspaces/:workspaceId/members

Response

[
  {
    "id": "uuid",
    "user_id": "uuid",
    "role": "owner",
    "invited_email": "[email protected]",
    "accepted_at": "2026-01-01T00:00:00Z",
    "display_name": "Jane Doe",
    "avatar_url": "https://..."
  }
]

Invite Member

POST /api/workspaces/:workspaceId/members

Field	Type	Required	Description
email	string	Yes	Email address to invite
role	'admin' | 'member'	Yes	Workspace role

Auth

Requires workspace owner or admin role.

Update Member Role

PATCH /api/workspaces/:workspaceId/members/:memberId

Field	Type	Required	Description
role	'admin' | 'member'	Yes	New role

Remove Member

DELETE /api/workspaces/:workspaceId/members/:memberId

Resend Invitation

POST /api/workspaces/:workspaceId/members/:memberId/resend

---

AI Keys (BYOA)

Manage Bring Your Own API key credentials per workspace.

List AI Keys

GET /api/workspaces/:workspaceId/ai-keys

Response

[
  {
    "id": "uuid",
    "provider": "anthropic",
    "key_hint": "sk-ant-...7x2q",
    "created_at": "2026-01-01T00:00:00Z"
  }
]

Add/Update AI Key

POST /api/workspaces/:workspaceId/ai-keys

Field	Type	Required	Description
provider	string	Yes	AI provider name (e.g., anthropic)
apiKey	string	Yes	API key (encrypted at rest)

Delete AI Key

DELETE /api/workspaces/:workspaceId/ai-keys/:keyId

Enterprise Feature

AI key management routes through the enterprise bridge. If ee/ is not loaded, these endpoints return 403.

Related Pages

• Roles & Permissions -- workspace role definitions
• Projects API -- project management within workspaces