Bases

The plan limits at 80% or more that touch the base: its records and the workspace's other limits (creators and owners)

GET /api/bases/{baseId}/usage-warnings

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

Parameters

Responses

• 200 Success
  • workspaceId string (uuid) required
  • plan object required
    • id string required
    • name string required
  • warnings array of object required
    • metric "recordsPerBase" | "attachmentBytesPerWorkspace" | "automationRunsPerMonth" | "apiCallsPerMonth" | "editorsPerWorkspace" | "aiCreditsPerMonth" required
    • level "near" | "full" required
    • used integer required
    • limit integer required
    • base object | null required
      • id string (uuid) required
      • name string required
    • resetsOn string (date) | null 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 bases of a workspace the caller can see (a base-only collaborator sees only theirs)

GET /api/workspaces/{workspaceId}/bases

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

Parameters

Responses

• 200 Success
  • bases array of object required
    • id string (uuid) required
    • workspaceId string (uuid) required
    • name string required
    • description string | null required
    • icon string | null required
    • color string | null required
    • role "owner" | "creator" | "editor" | "commenter" | "read_only" 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 base (owners and creators)

POST /api/workspaces/{workspaceId}/bases

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

Parameters

Request body

• name string required
• description string
• icon string
• color string

Responses

• 201 Success
  • id string (uuid) required
  • workspaceId string (uuid) required
  • name string required
  • description string | null required
  • icon string | null required
  • color string | null required
  • role "owner" | "creator" | "editor" | "commenter" | "read_only" 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)

Read a base

GET /api/bases/{baseId}

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

Parameters

Responses

• 200 Success
  • id string (uuid) required
  • workspaceId string (uuid) required
  • name string required
  • description string | null required
  • icon string | null required
  • color string | null required
  • role "owner" | "creator" | "editor" | "commenter" | "read_only" 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)

Update a base

PATCH /api/bases/{baseId}

Access: base:update on the base (see ACTIONS for the minimum role); personal access tokens need schema.bases:write.

Parameters

Request body

• name string
• description string | null
• icon string | null
• color string | null

Responses

• 200 Success
  • id string (uuid) required
  • workspaceId string (uuid) required
  • name string required
  • description string | null required
  • icon string | null required
  • color string | null required
  • role "owner" | "creator" | "editor" | "commenter" | "read_only" 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)

Move a base to the trash

DELETE /api/bases/{baseId}

Access: base:delete on the base (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)

Duplicate a base into this or another workspace, with or without its records, in the background

POST /api/bases/{baseId}/duplicate

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

Parameters

Request body

• name string
• workspaceId string (uuid)
• withRecords boolean

Responses

• 201 Success
  • id string (uuid) required
  • baseId string (uuid) required
  • workspaceId string (uuid) required
  • withRecords boolean required
  • status "running" | "done" | "failed" required
  • progress object required
    • records integer required
    • totalRecords integer required
  • base object | null required
    • id string (uuid) required
    • workspaceId string (uuid) required
    • name string required
    • description string | null required
    • icon string | null required
    • color string | null required
    • role "owner" | "creator" | "editor" | "commenter" | "read_only" required
    • createdAt string (date-time) required
    • updatedAt string (date-time) required
  • error string | null required
  • createdAt string required
  • finishedAt 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)

A base duplicate's progress (only who started it)

GET /api/bases/{baseId}/duplicates/{duplicateId}

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

Parameters

Responses

• 200 Success
  • id string (uuid) required
  • baseId string (uuid) required
  • workspaceId string (uuid) required
  • withRecords boolean required
  • status "running" | "done" | "failed" required
  • progress object required
    • records integer required
    • totalRecords integer required
  • base object | null required
    • id string (uuid) required
    • workspaceId string (uuid) required
    • name string required
    • description string | null required
    • icon string | null required
    • color string | null required
    • role "owner" | "creator" | "editor" | "commenter" | "read_only" required
    • createdAt string (date-time) required
    • updatedAt string (date-time) required
  • error string | null required
  • createdAt string required
  • finishedAt 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)

Ask the AI assistant for a change plan (creators): new tables, fields, formulas, views and automations for the base. The model gets the base's schema, and a few records only with includeRecords. Nothing is changed

POST /api/bases/{baseId}/assistant/plan

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

Parameters

Request body

• prompt string required
• includeRecords boolean

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)

Apply a change plan the user confirmed (creators), in one transaction through the same checks as the API

POST /api/bases/{baseId}/assistant/apply

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

Parameters

Request body

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

Responses

• 200 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)