Workspaces

The caller's workspaces, with their role in each (null where they collaborate on some bases only)

GET /api/workspaces

Access: any signed-in user, for their own data; personal access tokens need schema.bases:read.

Responses

• 200 Success
  • workspaces array of object required
    • id string (uuid) required
    • name string required
    • role "owner" | "creator" | "editor" | "commenter" | "read_only" | null required
    • createdAt string (date-time) required
    • updatedAt string (date-time) required
• 401 Not signed in
• 429 Too many requests: a rate limit was reached (see Retry-After)

Create a workspace (the caller becomes its owner)

POST /api/workspaces

Access: any signed-in user, for their own data; signed-in session only (no personal access tokens).

Request body

• name string required

Responses

• 201 Success
  • id string (uuid) required
  • name string required
  • role "owner" | "creator" | "editor" | "commenter" | "read_only" | null required
  • createdAt string (date-time) required
  • updatedAt string (date-time) required
• 401 Not signed in
• 422 The request failed validation
• 429 Too many requests: a rate limit was reached (see Retry-After)

Read a workspace

GET /api/workspaces/{workspaceId}

Access: workspace:read on the workspace (see ACTIONS for the minimum role); personal access tokens need schema.bases:read.

Parameters

Responses

• 200 Success
  • id string (uuid) required
  • name string required
  • role "owner" | "creator" | "editor" | "commenter" | "read_only" | null required
  • createdAt string (date-time) required
  • updatedAt string (date-time) required
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 429 Too many requests: a rate limit was reached (see Retry-After)

Rename a workspace (owners)

PATCH /api/workspaces/{workspaceId}

Access: workspace:update on the workspace (see ACTIONS for the minimum role); signed-in session only (no personal access tokens).

Parameters

Request body

• name string

Responses

• 200 Success
  • id string (uuid) required
  • name string required
  • role "owner" | "creator" | "editor" | "commenter" | "read_only" | null required
  • createdAt string (date-time) required
  • updatedAt string (date-time) required
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 422 The request failed validation
• 429 Too many requests: a rate limit was reached (see Retry-After)

Delete a workspace (owners; soft delete, everyone loses access at once)

DELETE /api/workspaces/{workspaceId}

Access: workspace:delete on the workspace (see ACTIONS for the minimum role); signed-in session only (no personal access tokens).

Parameters

Responses

• 204 Success, no content
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 429 Too many requests: a rate limit was reached (see Retry-After)

The workspace's plan, its limits and what it uses: records per base, attachment bytes, this month's automation runs and API calls, billable editors (members)

GET /api/workspaces/{workspaceId}/usage

Access: workspace:read on the workspace (see ACTIONS for the minimum role); personal access tokens need schema.bases:read.

Parameters

Responses

• 200 Success
  • workspaceId string (uuid) required
  • plan object required
    • id string required
    • name string required
  • period object required
    • start string (date) required
    • end string (date) required
  • bases array of object required
    • baseId string (uuid) required
    • name string required
    • records integer required
    • limit integer | null required
  • attachmentBytes object required
    • used integer required
    • limit integer | null required
  • automationRuns object required
    • used integer required
    • limit integer | null required
  • apiCalls object required
    • used integer required
    • limit integer | null required
  • editors object required
    • used integer required
    • limit integer | null required
  • aiCredits object | null required
    • used integer required
    • limit integer | null required
  • revisionHistoryDays integer | null required
  • features object required
    • removeBranding boolean required
    • personalViews boolean required
    • lockedViews boolean required
    • editPermissions boolean required
    • sso boolean required
    • scim boolean required
    • auditLogExport boolean required
    • adminConsole boolean required
    • dataResidency boolean required
  • upgradeUrl string | null required
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 429 Too many requests: a rate limit was reached (see Retry-After)

The workspace's subscription and the plans its owners can buy (owners; nothing to buy without billing)

GET /api/workspaces/{workspaceId}/billing

Access: workspace:manage_billing on the workspace (see ACTIONS for the minimum role); signed-in session only (no personal access tokens).

Parameters

Responses

• 200 Success
  • workspaceId string (uuid) required
  • enabled boolean required
  • plan object required
    • id string required
    • name string required
  • subscription object | null required
    • plan string required
    • interval "month" | "year" required
    • status "incomplete" | "incomplete_expired" | "trialing" | "active" | "past_due" | "canceled" | "unpaid" required
    • entitled boolean required
    • cancelAtPeriodEnd boolean required
    • currentPeriodEnd string | null required
    • seats integer | null required
    • graceEndsAt string | null required
  • offers array of object required
    • plan string required
    • name string required
    • intervals array of "month" | "year" required
    • price object | null required
      • amount number | null required
      • annual number | null required
      • currency string required
      • per string required
  • portal boolean required
  • editors integer required
  • manage boolean required
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 429 Too many requests: a rate limit was reached (see Retry-After)

Start a checkout for a plan at the billing provider (owners). The plan changes only when the provider's signed event arrives; a workspace with a subscription changes or cancels it in the portal

POST /api/workspaces/{workspaceId}/billing/checkout

Access: workspace:manage_billing on the workspace (see ACTIONS for the minimum role); signed-in session only (no personal access tokens).

Parameters

Request body

• plan string required
• interval "month" | "year" required

Responses

• 200 Success
  • url string (uri) required
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 422 The request failed validation
• 429 Too many requests: a rate limit was reached (see Retry-After)

Open the billing provider's customer portal: change plan, cancel, invoices (owners of a workspace with a subscription)

POST /api/workspaces/{workspaceId}/billing/portal

Access: workspace:manage_billing on the workspace (see ACTIONS for the minimum role); signed-in session only (no personal access tokens).

Parameters

Responses

• 200 Success
  • url string (uri) required
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 429 Too many requests: a rate limit was reached (see Retry-After)

Change the workspace's subscription at the billing provider (owners): another plan or interval (prorated), or cancel at the end of the period or take that back. Applied when the provider's signed event arrives

PATCH /api/workspaces/{workspaceId}/billing/subscription

Access: workspace:manage_billing on the workspace (see ACTIONS for the minimum role); signed-in session only (no personal access tokens).

Parameters

Request body

object

Responses

• 204 Success, no content
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 422 The request failed validation
• 429 Too many requests: a rate limit was reached (see Retry-After)

Whether AI features are on in the workspace (members): a provider from the workspace's own key or the instance's. Off: the app hides them

GET /api/workspaces/{workspaceId}/ai

Access: workspace:read on the workspace (see ACTIONS for the minimum role); personal access tokens need schema.bases:read.

Parameters

Responses

• 200 Success
  • workspaceId string required
  • available boolean required
  • source "workspace" | "instance" | null required
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 429 Too many requests: a rate limit was reached (see Retry-After)

The workspace's AI provider settings (owners): the instance's model, the workspace's base URL and model, whether a key is stored (never the key)

GET /api/workspaces/{workspaceId}/ai/settings

Access: workspace:manage_ai on the workspace (see ACTIONS for the minimum role); signed-in session only (no personal access tokens).

Parameters

Responses

• 200 Success
  • workspaceId string required
  • source "workspace" | "instance" | null required
  • instance object required
    • available boolean required
    • model string | null required
    • credits object | null
      • used integer required
      • limit integer required
      • resetsOn string (date) required
  • workspace object | null required
    • baseUrl string required
    • model string required
    • hasKey boolean required
    • updatedAt string required
  • allowedHosts array of string | null required
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 429 Too many requests: a rate limit was reached (see Retry-After)

Bring your own key (owners): an OpenAI-compatible endpoint, model and API key for the workspace's AI features. The key is write-only and encrypted at rest; omit it to keep the stored one

PUT /api/workspaces/{workspaceId}/ai/settings

Access: workspace:manage_ai on the workspace (see ACTIONS for the minimum role); signed-in session only (no personal access tokens).

Parameters

Request body

• baseUrl string (uri) | null
• model string required
• apiKey string

Responses

• 200 Success
  • workspaceId string required
  • source "workspace" | "instance" | null required
  • instance object required
    • available boolean required
    • model string | null required
    • credits object | null
      • used integer required
      • limit integer required
      • resetsOn string (date) required
  • workspace object | null required
    • baseUrl string required
    • model string required
    • hasKey boolean required
    • updatedAt string required
  • allowedHosts array of string | null required
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 422 The request failed validation
• 429 Too many requests: a rate limit was reached (see Retry-After)

Remove the workspace's own AI key (owners): AI features fall back to the instance's provider, or turn off

DELETE /api/workspaces/{workspaceId}/ai/settings

Access: workspace:manage_ai on the workspace (see ACTIONS for the minimum role); signed-in session only (no personal access tokens).

Parameters

Responses

• 200 Success
  • workspaceId string required
  • source "workspace" | "instance" | null required
  • instance object required
    • available boolean required
    • model string | null required
    • credits object | null
      • used integer required
      • limit integer required
      • resetsOn string (date) required
  • workspace object | null required
    • baseUrl string required
    • model string required
    • hasKey boolean required
    • updatedAt string required
  • allowedHosts array of string | null required
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 429 Too many requests: a rate limit was reached (see Retry-After)

Send one small structured request to the workspace's AI provider (owners) and report whether it answered

POST /api/workspaces/{workspaceId}/ai/settings/test

Access: workspace:manage_ai on the workspace (see ACTIONS for the minimum role); signed-in session only (no personal access tokens).

Parameters

Responses

• 200 Success
  • ok boolean required
  • source "workspace" | "instance" required
  • model string required
  • error string | null required
  • usage object | null required
    • inputTokens integer required
    • outputTokens integer required
    • totalTokens integer required
  • latencyMs integer required
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 429 Too many requests: a rate limit was reached (see Retry-After)

Describe a new base (creators): the AI assistant proposes its tables, fields, views and automations as a change plan. Nothing is created

POST /api/workspaces/{workspaceId}/assistant/plan

Access: base:create on the workspace (see ACTIONS for the minimum role); signed-in session only (no personal access tokens).

Parameters

Request body

• prompt string required

Responses

• 200 Success
  • plan object required
    • summary string required
    • baseName string | null required
    • operations array of object required
  • problems array of object required
    • operation integer required
    • field string | null required
    • kind "formula" | "reference" | "name" | "type" required
    • message string required
  • attempts integer required
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 422 The request failed validation
• 429 Too many requests: a rate limit was reached (see Retry-After)

Create a new base from a change plan the user confirmed (creators)

POST /api/workspaces/{workspaceId}/assistant/apply

Access: base:create on the workspace (see ACTIONS for the minimum role); signed-in session only (no personal access tokens).

Parameters

Request body

• name string required
• plan object required
  • summary string required
  • baseName string | null required
  • operations array of object required

Responses

• 201 Success
  • baseId string (uuid) required
  • tables integer required
  • fields integer required
  • views integer required
  • automations integer required
  • firstTableId string (uuid) | null required
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 422 The request failed validation
• 429 Too many requests: a rate limit was reached (see Retry-After)