Workspace Data Queries

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.

The agent runtime registers each query as a tool named wsq_<name>, 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

Create Workspace Data Query

post

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

Create body — the authored shape of a new workspace data query.

The SQL template + parameters parity check + multi-statement / session-state-command refusal runs inside :meth:_validate_template so a bad payload surfaces as a Pydantic 422 with the standard wire shape — no try/except in the handler.

namestring · min: 1 · max: 128RequiredPattern: ^[a-z][a-z0-9_]*$

descriptionstring · min: 1 · max: 2048Required

sql_templatestring · min: 1 · max: 8192Required

timeout_msinteger · min: 100 · max: 30000OptionalDefault: 5000

Responses

201

Successful Response

application/json

Wire shape for the response of every read + create/update handler.

id (UUID) is the stable handle — every URL except list takes it. name is the workspace-visible label (UNIQUE per workspace) and is still what the LLM tool registry keys on (wsq_<name>), but it is not the route identifier.

input_schema is deliberately NOT exposed — it is fully derivable from parameters[]. UI consumers can build the JSON Schema view locally if they need it.

idstring · uuidRequired

namestringRequired

descriptionstringRequired

sql_templatestringRequired

timeout_msintegerRequired

last_invoked_atstring · date-time · nullableOptional

deployed_atstring · date-timeRequired

deployed_bystring · uuidRequired

409

A workspace data query with the given name already exists

422

Validation or precondition failure

post/v1/{workspace_id}/data_queries

POST /v1/{workspace_id}/data_queries HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 161

{
  "name": "text",
  "description": "text",
  "sql_template": "text",
  "parameters": [
    {
      "name": "text",
      "type": "string",
      "description": "text",
      "default": "text"
    }
  ],
  "timeout_ms": 5000
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "sql_template": "text",
  "parameters": [
    {
      "name": "text",
      "type": "string",
      "description": "text",
      "default": "text"
    }
  ],
  "timeout_ms": 1,
  "last_invoked_at": "2026-07-10T22:27:15.239Z",
  "deployed_at": "2026-07-10T22:27:15.239Z",
  "deployed_by": "123e4567-e89b-12d3-a456-426614174000"
}

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).

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"
}

Update a Data Query

Update Workspace Data Query

patch

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

query_idstring · uuidRequired

Body

PATCH body — every field optional. Present ⇒ overwrite; absent ⇒ keep.

namestring · min: 1 · max: 128 · nullableOptionalPattern: ^[a-z][a-z0-9_]*$

descriptionstring · min: 1 · max: 2048 · nullableOptional

sql_templatestring · min: 1 · max: 8192 · nullableOptional

timeout_msinteger · min: 100 · max: 30000 · nullableOptional

Responses

200

Successful Response

application/json

Wire shape for the response of every read + create/update handler.

input_schema is deliberately NOT exposed — it is fully derivable from parameters[]. UI consumers can build the JSON Schema view locally if they need it.

idstring · uuidRequired

namestringRequired

descriptionstringRequired

sql_templatestringRequired

timeout_msintegerRequired

last_invoked_atstring · date-time · nullableOptional

deployed_atstring · date-timeRequired

deployed_bystring · uuidRequired

404

Workspace data query not found

409

A workspace data query with the given name already exists

422

Validation failure

patch/v1/{workspace_id}/data_queries/{query_id}

PATCH /v1/{workspace_id}/data_queries/{query_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 158

{
  "name": "text",
  "description": "text",
  "sql_template": "text",
  "parameters": [
    {
      "name": "text",
      "type": "string",
      "description": "text",
      "default": "text"
    }
  ],
  "timeout_ms": 1
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "sql_template": "text",
  "parameters": [
    {
      "name": "text",
      "type": "string",
      "description": "text",
      "default": "text"
    }
  ],
  "timeout_ms": 1,
  "last_invoked_at": "2026-07-10T22:27:15.239Z",
  "deployed_at": "2026-07-10T22:27:15.239Z",
  "deployed_by": "123e4567-e89b-12d3-a456-426614174000"
}

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.

List Data Queries

List workspace data queries

get

List every registered query for a workspace. Sort via repeated sort_by query params; each entry is +field or -field (allowed field: deployed_at). Default: -deployed_at. Cursor opaque — round-trip continuation_token unchanged with the same sort_by. Requires Workspace.view permission.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Query parameters

sort_bystring[]Optional

Sort axes, applied left-to-right. +field ascending, -field descending. Defaults to [("deployed_at", -1)] (newest first).

Default: []

limitinteger · max: 200Optional

Maximum number of queries to return per page.

Default: 50

continuation_tokenanyOptional

Opaque continuation token from a prior response. Treat as a black box — the server decodes it.

Responses

200

Successful Response

application/json

has_morebooleanRequired

continuation_tokenanyOptional

401

Missing or invalid API key.

403

Insufficient permissions.

422

Query parameter failed validation or continuation_token is unparseable.

get/v1/{workspace_id}/data_queries

GET /v1/{workspace_id}/data_queries HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "sql_template": "text",
      "parameter_count": 1,
      "timeout_ms": 1,
      "last_invoked_at": "2026-07-10T22:27:15.239Z",
      "deployed_at": "2026-07-10T22:27:15.239Z",
      "deployed_by": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "has_more": true,
  "continuation_token": null
}

Returns the workspace's registered data queries, ordered newest first. Results are paginated: when has_more is true, pass the returned continuation_token on the next request to fetch the following page.

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",
      "parameter_count": 1,
      "timeout_ms": 5000,
      "last_invoked_at": null,
      "deployed_at": "2026-07-15T10:30:00+00:00",
      "deployed_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ],
  "has_more": false,
  "continuation_token": null
}

List items carry a parameter_count instead of the full parameters array. Fetch a single query by ID to get its parameter definitions.

Get a Data Query

Get Workspace Data Query

get

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

query_idstring · uuidRequired

Responses

200

Successful Response

application/json

Wire shape for the response of every read + create/update handler.

input_schema is deliberately NOT exposed — it is fully derivable from parameters[]. UI consumers can build the JSON Schema view locally if they need it.

idstring · uuidRequired

namestringRequired

descriptionstringRequired

sql_templatestringRequired

timeout_msintegerRequired

last_invoked_atstring · date-time · nullableOptional

deployed_atstring · date-timeRequired

deployed_bystring · uuidRequired

404

Workspace data query not found

422

Validation Error

application/json

get/v1/{workspace_id}/data_queries/{query_id}

GET /v1/{workspace_id}/data_queries/{query_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "sql_template": "text",
  "parameters": [
    {
      "name": "text",
      "type": "string",
      "description": "text",
      "default": "text"
    }
  ],
  "timeout_ms": 1,
  "last_invoked_at": "2026-07-10T22:27:15.239Z",
  "deployed_at": "2026-07-10T22:27:15.239Z",
  "deployed_by": "123e4567-e89b-12d3-a456-426614174000"
}

Returns a single data query by its query_id.

Delete a Data Query

Delete Workspace Data Query

delete

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

query_idstring · uuidRequired

Responses

204

Successful Response

No content

404

Workspace data query not found

422

Validation Error

application/json

delete/v1/{workspace_id}/data_queries/{query_id}

DELETE /v1/{workspace_id}/data_queries/{query_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

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.

Invoke a Data Query

Invoke Workspace Data Query

post

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

query_idstring · uuidRequired

Body

Responses

200

Successful Response

application/json

duration_msnumberOptionalDefault: 0

row_countintegerOptionalDefault: 0

404

Workspace data query not found

422

Validation Error

application/json

503

Execution failed

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

POST /v1/{workspace_id}/data_queries/{query_id}/invoke HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 48

{
  "input": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "result": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "duration_ms": 0,
  "row_count": 0
}

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

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
}

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.

PreviousPlatform Functions NextTool Testing

Last updated 8 days ago

Was this helpful?