Workspace Data Queries

Register, manage, and invoke parameterized SQL queries against workspace custom tables.

Workspace data queries let you register parameterized SQL templates that the agent can invoke as tools during conversations. Unlike platform functions (which execute against an external data warehouse), data queries run directly against the custom tables you have provisioned in your workspace.

Each query has a server-generated UUID (query_id) used as the route handle, plus a workspace-unique name that registers the agent tool wsq_<name>. Creating a query with a name that already exists returns 409 Conflict; update an existing query in place via PATCH on its query_id. The name itself is mutable via PATCH. The agent runtime registers each query as a tool, so the agent can call it mid-conversation to fetch data from your workspace's custom tables.

Prerequisites

Your workspace must have at least one custom table provisioned (via POST /v1/{workspace_id}/tables) before you can deploy a data query. The per-workspace database role is created when the first table is provisioned.

Endpoints

Method	Path	Description
POST	/v1/{workspace_id}/data_queries	Create a data query (returns 201)
GET	/v1/{workspace_id}/data_queries	List all registered data queries
GET	/v1/{workspace_id}/data_queries/{query_id}	Get a single data query by ID
PATCH	/v1/{workspace_id}/data_queries/{query_id}	Update a data query
DELETE	/v1/{workspace_id}/data_queries/{query_id}	Delete a data query (returns 204)
POST	/v1/{workspace_id}/data_queries/{query_id}/invoke	Execute a data query with arguments

query_id (a UUID returned by create) is the immutable route handle. name is a mutable, workspace-unique label that registers the agent tool wsq_<name>.

Permissions

• List / Get / Invoke: Requires Workspace.view permission.

• Create / Update / Delete: Requires Workspace.update permission.

Create a Data Query

POST /v1/{workspace_id}/data_queries

Creates a new data query and returns it with a server-generated query_id (201 Created). Creating a query whose name already exists in the workspace returns 409 Conflict. To change an existing query, use PATCH on its query_id (see Update a Data Query).

Request Body

Field	Type	Required	Description
name	string	Yes	Identifier for the query. Lowercase letters, digits, and underscores. Must start with a letter. Max 128 characters.
description	string	Yes	Human-readable description shown to the agent. Max 2048 characters.
sql_template	string	Yes	SQL template with :name placeholders for parameters. Max 8192 characters.
parameters	array	No	List of typed parameters. Max 32 items. Default: empty list.
timeout_ms	integer	No	Per-call timeout in milliseconds. Range: 100-30000. Default: 5000.

Parameter Object

Field	Type	Required	Description
name	string	Yes	Parameter name. Becomes the :name placeholder in the SQL template. Lowercase letters, digits, and underscores. Must start with a letter. Max 64 characters.
type	string	Yes	One of: string, integer, number, boolean.
description	string	Yes	Description of the parameter. Max 512 characters.
default	string | integer | number | boolean | null	No	Default value. When null or omitted, the parameter is required. Must match the declared type.

Deploy-Time Validation

The platform validates the query before storing it:

• SQL must parse as a single valid statement.

• Multi-statement SQL is rejected.

• Session-state commands are rejected.

• Every :name placeholder in the SQL must have a matching entry in parameters, and every declared parameter must appear as a placeholder in the SQL.

• Default values must match their declared type.

Example Request

{
  "name": "active_patients_by_location",
  "description": "Returns active patients at a given location, optionally filtered by status.",
  "sql_template": "SELECT patient_id, name, status FROM custom.patients WHERE location_id = :location_id AND (:status IS NULL OR status = :status) LIMIT :max_rows",
  "parameters": [
    {
      "name": "location_id",
      "type": "string",
      "description": "UUID of the location to filter by."
    },
    {
      "name": "status",
      "type": "string",
      "description": "Optional patient status filter.",
      "default": null
    },
    {
      "name": "max_rows",
      "type": "integer",
      "description": "Maximum number of rows to return.",
      "default": 50
    }
  ],
  "timeout_ms": 5000
}

Example Response

{
  "id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
  "name": "active_patients_by_location",
  "description": "Returns active patients at a given location, optionally filtered by status.",
  "sql_template": "SELECT patient_id, name, status FROM custom.patients WHERE location_id = :location_id AND (:status IS NULL OR status = :status) LIMIT :max_rows",
  "parameters": [
    {
      "name": "location_id",
      "type": "string",
      "description": "UUID of the location to filter by."
    },
    {
      "name": "status",
      "type": "string",
      "description": "Optional patient status filter.",
      "default": null
    },
    {
      "name": "max_rows",
      "type": "integer",
      "description": "Maximum number of rows to return.",
      "default": 50
    }
  ],
  "timeout_ms": 5000,
  "last_invoked_at": null,
  "deployed_at": "2026-07-15T10:30:00+00:00",
  "deployed_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Error Responses

Status	Description
409	A data query with this name already exists in the workspace
422	Validation failure (invalid SQL, placeholder mismatch, no custom tables provisioned)

Update a Data Query

PATCH /v1/{workspace_id}/data_queries/{query_id}

Partially updates an existing data query, addressed by its immutable query_id. Any subset of name, description, sql_template, parameters, and timeout_ms may be supplied; omitted fields are left unchanged. The name is mutable but must remain unique within the workspace. The same deploy-time validation applies to any updated SQL.

Error Responses

Status	Description
404	Data query not found
409	The new name collides with another data query in the workspace
422	Validation failure (invalid SQL, placeholder mismatch)

List Data Queries

GET /v1/{workspace_id}/data_queries

Returns all registered data queries for the workspace, ordered newest first.

Example Response

{
  "items": [
    {
      "id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
      "name": "active_patients_by_location",
      "description": "Returns active patients at a given location.",
      "sql_template": "SELECT patient_id, name FROM custom.patients WHERE location_id = :location_id",
      "parameters": [
        {
          "name": "location_id",
          "type": "string",
          "description": "UUID of the location."
        }
      ],
      "timeout_ms": 5000,
      "last_invoked_at": null,
      "deployed_at": "2026-07-15T10:30:00+00:00",
      "deployed_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ],
  "count": 1
}

Get a Data Query

GET /v1/{workspace_id}/data_queries/{query_id}

Returns a single data query by its query_id.

Error Responses

Status	Description
404	Data query not found

Delete a Data Query

DELETE /v1/{workspace_id}/data_queries/{query_id}

Removes a registered data query, addressed by its query_id. Deleting a query cascades to its parameter rows automatically. Returns 204 No Content on success.

Error Responses

Status	Description
404	Data query not found

Invoke a Data Query

POST /v1/{workspace_id}/data_queries/{query_id}/invoke

Executes a registered data query, addressed by its query_id, with the provided arguments.

Request Body

Field	Type	Required	Description
input	object	No	Arguments keyed by parameter name. Default: empty object.

Example Request

{
  "input": {
    "location_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "max_rows": 10
  }
}

Example Response

{
  "result": [
    {
      "patient_id": "abc-123",
      "name": "Jane Doe",
      "status": "active"
    }
  ],
  "duration_ms": 42.5,
  "row_count": 1
}

Error Responses

Status	Description
404	Data query not found
503	Execution failed (SQL error, timeout, missing required argument)

Response Fields

All read, create, and update responses include:

Field	Type	Description
id	string	Server-generated UUID; the immutable route handle
name	string	Workspace-unique query name; registers the wsq_<name> agent tool
description	string	Human-readable description
sql_template	string	SQL template with :name placeholders
parameters	array	List of parameter objects
timeout_ms	integer	Per-call timeout in milliseconds
last_invoked_at	string | null	ISO 8601 timestamp of last successful invocation
deployed_at	string | null	ISO 8601 timestamp of last deploy
deployed_by	string | null	UUID of the API key that deployed

Agent Tool Registration

When a conversation session starts, the platform loads all data queries for the workspace and registers each one as a tool available to the agent. The tool name follows the pattern wsq_<name> (for example, a query named active_patients_by_location becomes the tool wsq_active_patients_by_location). The agent sees the query's description and input schema, and can call it like any other tool.

Data query tools run under the workspace's own tenant-scoped database role, so they can only access tables the workspace has provisioned. This is distinct from platform function tools (prefixed fn_), which execute against an external data warehouse.