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/workspacesResponse
Each element is the full workspace row plus the caller's membership and the active payment account (null when there is none). The caller's role is workspace_members[0].role; there is no top-level role field.
[
{
"id": "uuid",
"name": "My Workspace",
"slug": "my-workspace",
"type": "primary",
"plan": "starter",
"owner_id": "uuid",
"github_installation_id": 12345,
"workspace_members": [{ "role": "owner" }],
"payment_account": {
"provider": "polar",
"subscription_status": "active",
"current_period_end": "2026-02-01T00:00:00Z",
"cancel_at_period_end": false
}
}
]payment_account also carries credit_unit, customer_id, subscription_id, trial_ends_at, grace_period_ends_at, and plan.
Create Workspace
Create a new secondary workspace.
POST /api/workspacesRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Workspace display name |
slug | string | Yes | URL slug. The server normalizes it (lowercase, alphanumeric and hyphens) rather than rejecting other input |
Both fields are required (400 otherwise). A slug that is already taken returns 409. New workspaces start on the free plan.
Response
{
"id": "uuid",
"name": "Team Workspace",
"slug": "team-workspace",
"type": "secondary"
}Get Workspace
Get workspace details including members and billing information.
GET /api/workspaces/:workspaceIdResponse
The full workspace row, plus a workspace_members array (each member with profile fields) and the active payment_account (or null).
{
"id": "uuid",
"name": "My Workspace",
"slug": "my-workspace",
"type": "primary",
"plan": "starter",
"github_installation_id": 12345,
"owner_id": "uuid",
"workspace_members": [],
"payment_account": null
}Auth
Requires workspace membership.
Update Workspace
Update the workspace name and/or slug.
PATCH /api/workspaces/:workspaceIdRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | New workspace name (trimmed) |
slug | string | No | New slug, normalized like on create; at least 2 characters after normalization |
Auth
Requires workspace owner or admin role.
Error Codes
| Status | Condition |
|---|---|
400 | No fields provided, or slug shorter than 2 characters |
403 | Caller is not an owner or admin |
409 | Slug already taken |
Delete Workspace
Delete a workspace and all its projects.
DELETE /api/workspaces/:workspaceIdRequest Body
Optional JSON body with cleanup flags. Both default to false and are best-effort: a failure is logged and the deletion still proceeds.
| Field | Type | Description |
|---|---|---|
uninstallGithubApp | boolean | Also revoke the workspace's GitHub App installation (only when no other workspace shares it) |
cancelSubscription | boolean | Also cancel the workspace's active subscription with the payment provider |
Response
{ "deleted": true }Auth
Requires workspace owner role. Primary workspaces cannot be deleted (400; delete the user account instead). Non-owners get 403.
Transfer Ownership
Transfer workspace ownership to another member.
POST /api/workspaces/:workspaceId/transfer-ownerRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
memberId | string | Yes | ID of the target workspace_members row (not the user ID) |
Response
{ "transferred": true }Auth
Requires current workspace owner role. The target member must currently have the admin role (400 otherwise), and primary workspaces cannot be transferred (400). An unknown memberId returns 404.
Members
List Members
GET /api/workspaces/:workspaceId/membersRequires workspace owner or admin role (plain members get 403).
Response
[
{
"id": "uuid",
"user_id": "uuid",
"role": "owner",
"invited_email": "owner@example.com",
"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 |
Requires workspace owner or admin role. Returns the new member row. A 403 is returned when the plan's team.members seat limit is reached.
Update Member Role
PATCH /api/workspaces/:workspaceId/members/:memberId| Field | Type | Required | Description |
|---|---|---|---|
role | 'admin' | 'member' | Yes | New role |
Only the workspace owner may change roles, and the owner's own role cannot be changed (400).
Remove Member
DELETE /api/workspaces/:workspaceId/members/:memberIdRequires workspace owner or admin role. The owner cannot be removed (400). Returns { "deleted": true }.
Resend Invitation
POST /api/workspaces/:workspaceId/members/:memberId/resendRe-sends the invitation email for a member who has not accepted yet. Returns { "resent": true }.
| Status | Condition |
|---|---|
400 | The member already accepted, or has no invitation email |
404 | Member not found |
429 | More than 3 resends for this member within an hour |
502 | The email could not be sent |
AI Keys (BYOA)
Manage Bring Your Own API key credentials. Keys are stored per user within the workspace: each call lists, replaces, or deletes the calling user's own key, not other members'.
List AI Keys
GET /api/workspaces/:workspaceId/ai-keysResponse
[
{
"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 | 'anthropic' | Yes | AI provider; only anthropic is accepted (400 otherwise) |
apiKey | string | Yes | API key (encrypted at rest) |
Delete AI Key
DELETE /api/workspaces/:workspaceId/ai-keys/:keyIdAny workspace member may call these routes. Deleting returns { "deleted": true }.
Plan and edition gate
AI key management routes through the enterprise bridge and requires the ai.byoa plan feature. If ee/ is not loaded, or the workspace's plan lacks the feature, these endpoints return 403.
MCP Cloud Keys
Manage MCP Cloud API keys (crn_mcp_ Bearer keys) that grant programmatic access to the remote MCP endpoint. The plaintext key is shown once at creation and never stored -- the server only keeps a SHA-256 hash plus the prefix.
List MCP Cloud Keys
GET /api/workspaces/:workspaceId/mcp-cloud-keysOptionally narrow to one project with ?projectId=.
Response
{
"keys": [
{
"id": "uuid",
"name": "Production key",
"key_prefix": "crn_mcp_ab12",
"project_id": "uuid",
"allowed_tools": ["list_models", "get_content"],
"media_enabled": false,
"rate_limit_per_minute": 60,
"monthly_call_limit": null,
"last_used_at": "2026-01-01T00:00:00Z",
"created_at": "2026-01-01T00:00:00Z",
"calls_this_month": 42
}
]
}Plaintext keys are never returned here. An empty allowed_tools array means all tools are permitted. (The row also carries created_by and revoked_at, though revoked keys are filtered out of this list.)
Auth
Requires workspace membership (owner, admin, or member).
Create MCP Cloud Key
POST /api/workspaces/:workspaceId/mcp-cloud-keysRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Project the key is scoped to |
name | string | Yes | Display name |
allowedTools | string[] | No | Whitelist of MCP tool names (empty = all tools). Unknown names are rejected. |
mediaEnabled | boolean | No | Allow media tools (default false) |
rateLimitPerMinute | number | No | 1-600 requests per minute (default 60) |
monthlyCallLimit | number | null | No | Monthly call cap (null = unlimited) |
Response
{
"id": "uuid",
"key": "crn_mcp_ab12...full-plaintext",
"keyPrefix": "crn_mcp_ab12",
"name": "Production key",
"projectId": "uuid",
"allowedTools": [],
"mediaEnabled": false,
"rateLimitPerMinute": 60,
"monthlyCallLimit": null,
"createdAt": "2026-01-01T00:00:00Z"
}WARNING
The plaintext key is returned exactly once. Store it securely -- the server only keeps its hash.
Auth
Requires workspace owner or admin role. Gated by the api.mcp_cloud plan feature and the api.mcp_keys plan limit.
Error Codes
| Status | Condition |
|---|---|
400 | Missing name/projectId, unknown tool in allowedTools, rateLimitPerMinute out of range, or invalid monthlyCallLimit |
403 | Plan does not include api.mcp_cloud, or the api.mcp_keys key limit is reached |
404 | Workspace or project not found |
Revoke MCP Cloud Key
DELETE /api/workspaces/:workspaceId/mcp-cloud-keys/:keyIdSets revoked_at; the key is immediately rejected by the MCP endpoint. The row is retained for audit.
Response
{ "revoked": true }Auth
Requires workspace owner or admin role.
Connected Apps
Active OAuth grants for the remote MCP connector surface -- the client applications (e.g. Claude) a user has connected to this workspace. See the Connected Apps guide for the end-user flow.
Managed deployments only
These endpoints back the remote-MCP OAuth server, which only runs on the managed auth pair. On the self-hosted (Supabase) pair, GET returns { "enabled": false, "endpoint": null, "grants": [] } and DELETE returns 404.
List Connected Apps
GET /api/workspaces/:workspaceId/connected-appsOwners and admins see every grant in the workspace; members see only their own.
Response
{
"enabled": true,
"endpoint": "https://studio.contentrain.io/api/mcp/remote",
"grants": [
{
"grantId": "uuid",
"clientHost": "claude.ai",
"clientName": "Claude",
"logoUri": "https://...",
"projectId": "uuid",
"projectRepo": "org/my-website",
"scopes": ["content:read", "content:write", "project:metadata"],
"createdAt": "2026-01-01T00:00:00Z",
"lastUsedAt": "2026-01-02T00:00:00Z",
"callsThisMonth": 128,
"mine": true
}
]
}mine indicates whether the grant belongs to the requesting user.
Auth
Requires workspace membership (owner, admin, or member).
Revoke Connected App
DELETE /api/workspaces/:workspaceId/connected-apps/:grantIdRevokes the grant, kills the refresh-token family, and deletes live access tokens. The connected client's next refresh fails with invalid_grant and re-runs the auth flow.
Response
{ "revoked": true }Auth
Owners and admins may revoke any grant; members may revoke only their own (otherwise 403). Returns 404 on the non-managed pair or when the grant does not exist.
Usage & Overage
Get Usage
Return metered usage for the workspace's current billing period. The AI, API, and MCP meters follow the billing period (anchored to the subscription when there is one); form submissions, comments, and CDN bandwidth reset on the 1st of the month.
GET /api/workspaces/:workspaceId/usageResponse
{
"billingPeriod": "2026-07",
"period": { "startsAt": "2026-07-01T00:00:00Z", "resetsAt": "2026-08-01T00:00:00Z", "source": "calendar" },
"canManage": true,
"byoaRequests": 0,
"categories": [
{
"key": "ai_messages",
"limitKey": "ai.messages_per_month",
"name": "AI Credits",
"current": 1234,
"limit": 1600,
"overageEnabled": false,
"overageUnits": 0,
"overageUnitPrice": 0,
"overageAmount": 0,
"unit": "credits",
"percentage": 77,
"overageSellable": true,
"overageLock": null,
"overageCeiling": null,
"resetsAt": "2026-08-01T00:00:00Z",
"periodKey": "2026-07",
"resetBasis": "calendar"
}
],
"totalOverageAmount": 0,
"projectedOverageAmount": 0
}Categories are returned in this order: ai_messages, form_submissions, comments, cdn_bandwidth, media_storage, api_messages, mcp_calls. AI and API usage is counted in credits (one credit = $0.01 of model spend). A limit of -1 means unlimited. A meter that could not be read is returned with unavailable: true instead of a zero.
Simple Format
The CLI-friendly format keys each category by camelCase name. Each value is a { current, limit, percentage } object:
GET /api/workspaces/:workspaceId/usage?format=simple{
"aiMessages": { "current": 1234, "limit": 1600, "percentage": 77 },
"formSubmissions": { "current": 12, "limit": 1000, "percentage": 1 },
"cdnBandwidthGb": { "current": 0.5, "limit": 50, "percentage": 1 },
"mediaStorageGb": { "current": 0.2, "limit": 10, "percentage": 2 },
"apiMessages": { "current": 0, "limit": 1000, "percentage": 0 },
"mcpCalls": { "current": 8, "limit": 10000, "percentage": 0 }
}The simple map also includes a comments entry. An unreadable meter is returned as { "current": null, "limit": <n>, "percentage": null, "unavailable": true }.
Auth
Requires workspace membership. owner and admin get the full picture (canManage: true, overage prices and amounts); plain members get the meters only (canManage: false, overage fields zeroed). Non-members get 403.
Get Overage Settings
Return overage preferences, plan limits, and per-category overage pricing.
GET /api/workspaces/:workspaceId/overage-settingsResponse
{
"overageSettings": { "ai_messages": true },
"categories": [
{
"limitKey": "ai.messages_per_month",
"settingsKey": "ai_messages",
"unit": "per credit",
"unitPrice": 0.025,
"planLimit": 1600,
"enabled": true,
"sellable": true,
"lock": null
}
],
"canEnableOverage": true
}sellable: false marks a hard cap with no overage. lock is set when the toggle cannot be turned on yet (trial, yearly plan, or a subscription without the matching price) and enabled is then false. canEnableOverage is true only when the workspace has a saved payment method, an active subscription (trialing / active / past_due), and a non-free plan.
Auth
Requires workspace owner or admin role.
Update Overage Settings
Toggle overage billing per category. Submitted keys are merged with existing settings.
PATCH /api/workspaces/:workspaceId/overage-settingsRequest Body
Any subset of the boolean category toggles:
| Field | Type | Description |
|---|---|---|
ai_messages | boolean | Enable overage for AI credits |
api_messages | boolean | Enable overage for API credits |
cdn_bandwidth | boolean | Enable overage for CDN origin transfer ($0.15/GB, up to 10× the plan). Has no effect unless the subscription carries the metered CDN price |
form_submissions | boolean | Enable overage for form submissions |
media_storage | boolean | Enable overage for media storage ($0.25/GB-month, up to 10× the plan). Has no effect unless the subscription carries the metered storage price |
mcp_calls | boolean | Enable overage for MCP Cloud calls |
Response
{ "overageSettings": { "ai_messages": true, "cdn_bandwidth": false } }Auth
Requires workspace owner or admin role.
Error Codes
| Status | Condition |
|---|---|
400 | Unknown settings key, non-boolean value, or no fields provided |
402 | No active paid subscription (or no saved payment method) |
403 | Not a workspace owner/admin, or the free plan |
409 | The toggle is locked (data.code is overage_locked, with data.reason and data.until: trial, yearly plan, subscription without the price) or the category is not sold (overage_not_available). Turning a locked toggle off is always allowed |
See the Billing guide for how overage pricing is applied.
Billing
Billing actions live under /api/billing/ (they are not scoped under /api/workspaces/ in the path) but take workspaceId in the request body. They route to the active payment provider (Polar by default, Stripe as fallback).
Create Checkout Session
Create a hosted checkout session to subscribe a workspace to a paid plan.
POST /api/billing/checkoutRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
workspaceId | string | Yes | Target workspace |
plan | 'starter' | 'pro' | Yes | Plan to subscribe to |
returnTo | string | No | Internal path to send the customer back to after checkout (default: the workspace settings page) |
Response
{ "url": "https://checkout.provider.com/..." }Redirect the browser to url. A free trial is granted only if the workspace has never consumed one.
Auth
Requires workspace owner or admin role. Rate limited to 1 request per 30 seconds per workspace.
Error Codes
| Status | Condition |
|---|---|
400 | Missing workspaceId/plan, or invalid plan |
403 | Not a workspace owner/admin |
409 | Workspace already has an active subscription |
429 | Rate limit exceeded |
502 / 503 | Payment provider unavailable |
Create Portal Session
Create a customer portal session so the user can manage their subscription (payment method, cancel, plan change).
POST /api/billing/portalRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
workspaceId | string | Yes | Target workspace |
Response
{ "url": "https://billing.provider.com/..." }Auth
Requires workspace owner or admin role.
Error Codes
| Status | Condition |
|---|---|
400 | Missing workspaceId, or the workspace has no payment customer yet |
403 | Not a workspace owner/admin |
502 / 503 | Payment provider unavailable |
Related Pages
- Roles & Permissions -- workspace role definitions
- Projects API -- project management within workspaces