Workspace Lakebase

Fork sandbox databases, execute SQL queries, and manage reusable query tools for workspace data exploration.

Workspace Lakebase provides data exploration capabilities for your workspace. You can create sandbox database forks for safe experimentation, execute SQL queries against your workspace data, and define reusable query tools that the reasoning engine can call during conversations.

Forks

A fork is a sandbox copy of your workspace's data layer. Forks let you experiment with queries, create tables, and modify data without affecting production. Each fork has a configurable time-to-live (1 to 30 days) and is automatically cleaned up after expiration.

Create a Fork

POST /v1/{workspace_id}/fork

Creates a new sandbox fork for the workspace. Only one fork can exist per workspace at a time.

Request body:

Field	Type	Required	Description
ttl_days	integer	No	Time-to-live in days (1-30, default 7)

Response: 201 Created

Field	Type	Description
endpoint	string	Connection endpoint for the fork
ttl_days	integer	Configured time-to-live
status	string	Fork status: pending, ready, or deleting

Permissions: workspace.update

Get Fork Status

GET /v1/{workspace_id}/fork

Returns the current fork status for the workspace, or null if no fork exists.

Response: 200 OK

Returns a fork object (same shape as create response) or null.

Permissions: workspace.view

Delete a Fork

DELETE /v1/{workspace_id}/fork

Destroys the workspace fork and releases all associated resources.

Response: 204 No Content

Permissions: workspace.update

Query Execution

Execute SQL queries directly against your workspace's data layer. Queries are validated before execution to prevent unsafe operations.

Execute a Query

POST /v1/{workspace_id}/lakebase/query

Executes a SQL query against the workspace data layer. Queries are subject to validation rules and a 30-second execution timeout. Results are capped at 1,000 rows.

Request body:

Field	Type	Required	Description
sql	string	Yes	SQL statement to execute (max 50,000 characters)

Response: 200 OK

Field	Type	Description
columns	array of strings	Column names (present for queries that return rows)
rows	array of objects	Result rows as key-value pairs (present for queries that return rows)
row_count	integer	Number of rows returned or affected

Validation rules:

• Multi-statement SQL (semicolons) is not allowed

• Privilege escalation operations are blocked

• DDL operations (CREATE, ALTER, DROP, TRUNCATE) are not allowed on the shared data layer

• Write operations (INSERT, UPDATE, DELETE) on the shared data layer are restricted to the custom schema

Permissions: workspace.update

Query Tools

Query tools are reusable, parameterized SQL queries that the reasoning engine can call during conversations. They let non-engineers define data retrieval patterns that agents use to answer questions.

Create a Query Tool

POST /v1/{workspace_id}/query-tools

Request body:

Field	Type	Required	Description
name	string	Yes	Tool name
description	string	No	Human-readable description
parameters	object	No	Parameter schema for the query
query	string	Yes	SQL query template (max 50,000 characters)
target	string	No	Query target (default: lakebase)

Response: 201 Created

Returns the created tool object.

Permissions: skill.create

List Query Tools

GET /v1/{workspace_id}/query-tools

Returns a paginated list of query tools for the workspace, ordered by name.

Response: 200 OK

Returns a paginated response containing tool objects.

Permissions: skill.view

Update a Query Tool

PATCH /v1/{workspace_id}/query-tools/{tool_id}

Request body (all fields optional):

Field	Type	Description
name	string	Updated tool name
description	string	Updated description
parameters	object	Updated parameter schema
query	string	Updated SQL query
enabled	boolean	Enable or disable the tool

Response: 200 OK

Returns the updated tool object.

Permissions: skill.update

Delete a Query Tool

DELETE /v1/{workspace_id}/query-tools/{tool_id}

Response: 204 No Content

Permissions: skill.delete

Test a Query Tool

POST /v1/{workspace_id}/query-tools/{tool_id}/test

Executes a query tool with sample parameters to verify it works correctly. Only declared parameters are accepted - undeclared parameters are rejected.

Request body:

Field	Type	Required	Description
parameters	object	No	Sample parameter values to bind

Response: 200 OK

Returns query results (same shape as query execution response).

Permissions: skill.update

Tool Object

Field	Type	Description
id	string	Unique tool identifier
workspace_id	string	Workspace the tool belongs to
name	string	Tool name
description	string	Human-readable description
parameters	object	Parameter schema
query	string	SQL query template
target	string	Query target (lakebase)
enabled	boolean	Whether the tool is active
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last update timestamp

Rate Limits

All endpoints are rate-limited. Read operations (GET) and write operations (POST, PATCH, DELETE) have separate rate limit pools.