> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/api-reference/readme/platform/workspace-data-queries.md).

# Workspace Data Queries

## List workspace data queries

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"src__routes__workspace_data_queries__list_workspace_data_queries__Response":{"properties":{"items":{"items":{"$ref":"#/components/schemas/src__routes__workspace_data_queries__list_workspace_data_queries__Response__Item"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"Response"},"src__routes__workspace_data_queries__list_workspace_data_queries__Response__Item":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"sql_template":{"type":"string","title":"Sql Template"},"parameter_count":{"type":"integer","title":"Parameter Count"},"timeout_ms":{"type":"integer","title":"Timeout Ms"},"last_invoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Invoked At"},"deployed_at":{"type":"string","format":"date-time","title":"Deployed At"},"deployed_by":{"type":"string","format":"uuid","title":"Deployed By"}},"type":"object","required":["id","name","description","sql_template","parameter_count","timeout_ms","deployed_at","deployed_by"],"title":"Item"}}},"paths":{"/v1/{workspace_id}/data_queries":{"get":{"tags":["Workspace Data Queries"],"summary":"List workspace data queries","description":"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.","operationId":"list-workspace-data-queries","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"sort_by","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Sort axes, applied left-to-right. ``+field`` ascending, ``-field``\ndescending. Defaults to ``[(\"deployed_at\", -1)]`` (newest first).","default":[],"title":"Sort By"},"description":"Sort axes, applied left-to-right. ``+field`` ascending, ``-field``\ndescending. Defaults to ``[(\"deployed_at\", -1)]`` (newest first)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"exclusiveMinimum":0,"description":"Maximum number of queries to return per page.","default":50,"title":"Limit"},"description":"Maximum number of queries to return per page."},{"name":"continuation_token","in":"query","required":false,"schema":{"description":"Opaque continuation token from a prior response. Treat as a\nblack box — the server decodes it.","title":"Continuation Token"},"description":"Opaque continuation token from a prior response. Treat as a\nblack box — the server decodes it."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__routes__workspace_data_queries__list_workspace_data_queries__Response"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"422":{"description":"Query parameter failed validation or continuation_token is unparseable."}}}}}}
```

## POST /v1/{workspace\_id}/data\_queries

> Create Workspace Data Query

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"src__routes__workspace_data_queries__create_workspace_data_query__Request":{"properties":{"name":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Name"},"description":{"type":"string","maxLength":2048,"minLength":1,"title":"Description"},"sql_template":{"type":"string","maxLength":8192,"minLength":1,"title":"Sql Template"},"parameters":{"items":{"$ref":"#/components/schemas/src__routes__workspace_data_queries__create_workspace_data_query__Request__Parameter"},"type":"array","maxItems":32,"title":"Parameters"},"timeout_ms":{"type":"integer","maximum":30000,"minimum":100,"title":"Timeout Ms","default":5000}},"additionalProperties":false,"type":"object","required":["name","description","sql_template"],"title":"Request","description":"Create body — the authored shape of a new workspace data query.\n\nThe SQL template + parameters parity check + multi-statement /\nsession-state-command refusal runs inside :meth:`_validate_template`\nso a bad payload surfaces as a Pydantic 422 with the standard wire\nshape — no try/except in the handler."},"src__routes__workspace_data_queries__create_workspace_data_query__Request__Parameter":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Name"},"type":{"type":"string","enum":["string","integer","number","boolean"],"title":"Type"},"description":{"type":"string","maxLength":512,"minLength":1,"title":"Description"},"default":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"title":"Default"}},"additionalProperties":false,"type":"object","required":["name","type","description"],"title":"Parameter","description":"Strict write-side validator for one declared parameter."},"WorkspaceDataQueryItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"sql_template":{"type":"string","title":"Sql Template"},"parameters":{"items":{"$ref":"#/components/schemas/StoredParameter"},"type":"array","title":"Parameters"},"timeout_ms":{"type":"integer","title":"Timeout Ms"},"last_invoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Invoked At"},"deployed_at":{"type":"string","format":"date-time","title":"Deployed At"},"deployed_by":{"type":"string","format":"uuid","title":"Deployed By"}},"type":"object","required":["id","name","description","sql_template","parameters","timeout_ms","deployed_at","deployed_by"],"title":"WorkspaceDataQueryItem","description":"Wire shape for the response of every read + create/update handler.\n\n``id`` (UUID) is the stable handle — every URL except list takes it.\n``name`` is the workspace-visible label (UNIQUE per workspace) and is\nstill what the LLM tool registry keys on (``wsq_<name>``), but it is\nnot the route identifier.\n\n``input_schema`` is deliberately NOT exposed — it is fully derivable\nfrom ``parameters[]``. UI consumers can build the JSON Schema view\nlocally if they need it."},"StoredParameter":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","enum":["string","integer","number","boolean"],"title":"Type"},"description":{"type":"string","title":"Description"},"default":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"title":"Default"}},"additionalProperties":false,"type":"object","required":["name","type","description"],"title":"StoredParameter","description":"One typed input parameter to a workspace data query — trusted shape.\n\nRead-path model: the DB's CHECK constraints already enforced ``name``\nregex and ``type`` enum on write, and the deploy endpoint's strict\n:class:`Parameter` validators enforced ``description`` length and\ntypo-rejection at the inbound network edge. After that, every\nconstruction of this model (DB read projection, executor binding,\nagent-engine spec, outbound response) is trusted — no 422 surface.\n\n``default is None`` is the canonical \"required\" signal: the executor\nraises if a caller omits a required argument, otherwise substitutes\nthe stored default."}}},"paths":{"/v1/{workspace_id}/data_queries":{"post":{"tags":["Workspace Data Queries"],"summary":"Create Workspace Data Query","operationId":"create-workspace-data-query","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__routes__workspace_data_queries__create_workspace_data_query__Request"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceDataQueryItem"}}}},"409":{"description":"A workspace data query with the given name already exists"},"422":{"description":"Validation or precondition failure"}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## GET /v1/{workspace\_id}/data\_queries/{query\_id}

> Get Workspace Data Query

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"WorkspaceDataQueryItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"sql_template":{"type":"string","title":"Sql Template"},"parameters":{"items":{"$ref":"#/components/schemas/StoredParameter"},"type":"array","title":"Parameters"},"timeout_ms":{"type":"integer","title":"Timeout Ms"},"last_invoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Invoked At"},"deployed_at":{"type":"string","format":"date-time","title":"Deployed At"},"deployed_by":{"type":"string","format":"uuid","title":"Deployed By"}},"type":"object","required":["id","name","description","sql_template","parameters","timeout_ms","deployed_at","deployed_by"],"title":"WorkspaceDataQueryItem","description":"Wire shape for the response of every read + create/update handler.\n\n``id`` (UUID) is the stable handle — every URL except list takes it.\n``name`` is the workspace-visible label (UNIQUE per workspace) and is\nstill what the LLM tool registry keys on (``wsq_<name>``), but it is\nnot the route identifier.\n\n``input_schema`` is deliberately NOT exposed — it is fully derivable\nfrom ``parameters[]``. UI consumers can build the JSON Schema view\nlocally if they need it."},"StoredParameter":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","enum":["string","integer","number","boolean"],"title":"Type"},"description":{"type":"string","title":"Description"},"default":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"title":"Default"}},"additionalProperties":false,"type":"object","required":["name","type","description"],"title":"StoredParameter","description":"One typed input parameter to a workspace data query — trusted shape.\n\nRead-path model: the DB's CHECK constraints already enforced ``name``\nregex and ``type`` enum on write, and the deploy endpoint's strict\n:class:`Parameter` validators enforced ``description`` length and\ntypo-rejection at the inbound network edge. After that, every\nconstruction of this model (DB read projection, executor binding,\nagent-engine spec, outbound response) is trusted — no 422 surface.\n\n``default is None`` is the canonical \"required\" signal: the executor\nraises if a caller omits a required argument, otherwise substitutes\nthe stored default."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/data_queries/{query_id}":{"get":{"tags":["Workspace Data Queries"],"summary":"Get Workspace Data Query","operationId":"get-workspace-data-query","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"query_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Query Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceDataQueryItem"}}}},"404":{"description":"Workspace data query not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## DELETE /v1/{workspace\_id}/data\_queries/{query\_id}

> Delete Workspace Data Query

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/data_queries/{query_id}":{"delete":{"tags":["Workspace Data Queries"],"summary":"Delete Workspace Data Query","operationId":"delete-workspace-data-query","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"query_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Query Id"}}],"responses":{"204":{"description":"Successful Response"},"404":{"description":"Workspace data query not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## PATCH /v1/{workspace\_id}/data\_queries/{query\_id}

> Update Workspace Data Query

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"src__routes__workspace_data_queries__update_workspace_data_query__Request":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$"},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":2048,"minLength":1},{"type":"null"}],"title":"Description"},"sql_template":{"anyOf":[{"type":"string","maxLength":8192,"minLength":1},{"type":"null"}],"title":"Sql Template"},"parameters":{"anyOf":[{"items":{"$ref":"#/components/schemas/src__routes__workspace_data_queries__update_workspace_data_query__Request__Parameter"},"type":"array","maxItems":32},{"type":"null"}],"title":"Parameters"},"timeout_ms":{"anyOf":[{"type":"integer","maximum":30000,"minimum":100},{"type":"null"}],"title":"Timeout Ms"}},"additionalProperties":false,"type":"object","title":"Request","description":"PATCH body — every field optional. Present ⇒ overwrite; absent ⇒ keep."},"src__routes__workspace_data_queries__update_workspace_data_query__Request__Parameter":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Name"},"type":{"type":"string","enum":["string","integer","number","boolean"],"title":"Type"},"description":{"type":"string","maxLength":512,"minLength":1,"title":"Description"},"default":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"title":"Default"}},"additionalProperties":false,"type":"object","required":["name","type","description"],"title":"Parameter","description":"Strict write-side validator for one declared parameter."},"WorkspaceDataQueryItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"sql_template":{"type":"string","title":"Sql Template"},"parameters":{"items":{"$ref":"#/components/schemas/StoredParameter"},"type":"array","title":"Parameters"},"timeout_ms":{"type":"integer","title":"Timeout Ms"},"last_invoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Invoked At"},"deployed_at":{"type":"string","format":"date-time","title":"Deployed At"},"deployed_by":{"type":"string","format":"uuid","title":"Deployed By"}},"type":"object","required":["id","name","description","sql_template","parameters","timeout_ms","deployed_at","deployed_by"],"title":"WorkspaceDataQueryItem","description":"Wire shape for the response of every read + create/update handler.\n\n``id`` (UUID) is the stable handle — every URL except list takes it.\n``name`` is the workspace-visible label (UNIQUE per workspace) and is\nstill what the LLM tool registry keys on (``wsq_<name>``), but it is\nnot the route identifier.\n\n``input_schema`` is deliberately NOT exposed — it is fully derivable\nfrom ``parameters[]``. UI consumers can build the JSON Schema view\nlocally if they need it."},"StoredParameter":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","enum":["string","integer","number","boolean"],"title":"Type"},"description":{"type":"string","title":"Description"},"default":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"title":"Default"}},"additionalProperties":false,"type":"object","required":["name","type","description"],"title":"StoredParameter","description":"One typed input parameter to a workspace data query — trusted shape.\n\nRead-path model: the DB's CHECK constraints already enforced ``name``\nregex and ``type`` enum on write, and the deploy endpoint's strict\n:class:`Parameter` validators enforced ``description`` length and\ntypo-rejection at the inbound network edge. After that, every\nconstruction of this model (DB read projection, executor binding,\nagent-engine spec, outbound response) is trusted — no 422 surface.\n\n``default is None`` is the canonical \"required\" signal: the executor\nraises if a caller omits a required argument, otherwise substitutes\nthe stored default."}}},"paths":{"/v1/{workspace_id}/data_queries/{query_id}":{"patch":{"tags":["Workspace Data Queries"],"summary":"Update Workspace Data Query","operationId":"update-workspace-data-query","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"query_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Query Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__routes__workspace_data_queries__update_workspace_data_query__Request"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceDataQueryItem"}}}},"404":{"description":"Workspace data query not found"},"409":{"description":"A workspace data query with the given name already exists"},"422":{"description":"Validation failure"}}}}}}
```

## POST /v1/{workspace\_id}/data\_queries/{query\_id}/invoke

> Invoke Workspace Data Query

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"src__routes__workspace_data_queries__invoke_workspace_data_query__Request":{"properties":{"input":{"additionalProperties":true,"type":"object","title":"Input","description":"Caller arguments matching the declared parameters."}},"type":"object","title":"Request"},"src__routes__workspace_data_queries__invoke_workspace_data_query__Response":{"properties":{"result":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Result"},"duration_ms":{"type":"number","title":"Duration Ms","default":0},"row_count":{"type":"integer","title":"Row Count","default":0}},"type":"object","title":"Response"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/data_queries/{query_id}/invoke":{"post":{"tags":["Workspace Data Queries"],"summary":"Invoke Workspace Data Query","operationId":"invoke-workspace-data-query","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"query_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Query Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__routes__workspace_data_queries__invoke_workspace_data_query__Request"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__routes__workspace_data_queries__invoke_workspace_data_query__Response"}}}},"404":{"description":"Workspace data query not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"503":{"description":"Execution failed"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amigo.ai/api-reference/readme/platform/workspace-data-queries.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.