Workspace 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-01-01T00:00:00.000Z",
      "deployed_at": "2026-01-01T00:00:00.000Z",
      "deployed_by": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "has_more": true,
  "continuation_token": null
}

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: 301

{
  "name": "text",
  "description": "text",
  "sql_template": "text",
  "parameters": [
    {
      "name": "text",
      "type": "string",
      "description": "text",
      "default": "text",
      "authorization_binding": {
        "source": "text",
        "resource_type": "text",
        "access": "read",
        "encoding": "csv"
      },
      "authorization_binding_test_value": "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",
      "authorization_binding": {
        "source": "text",
        "resource_type": "text",
        "access": "read",
        "encoding": "csv"
      },
      "authorization_binding_test_value": "text"
    }
  ],
  "timeout_ms": 1,
  "last_invoked_at": "2026-01-01T00:00:00.000Z",
  "deployed_at": "2026-01-01T00:00:00.000Z",
  "deployed_by": "123e4567-e89b-12d3-a456-426614174000"
}

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.

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

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",
      "authorization_binding": {
        "source": "text",
        "resource_type": "text",
        "access": "read",
        "encoding": "csv"
      },
      "authorization_binding_test_value": "text"
    }
  ],
  "timeout_ms": 1,
  "last_invoked_at": "2026-01-01T00:00:00.000Z",
  "deployed_at": "2026-01-01T00:00:00.000Z",
  "deployed_by": "123e4567-e89b-12d3-a456-426614174000"
}

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

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.

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

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: 298

{
  "name": "text",
  "description": "text",
  "sql_template": "text",
  "parameters": [
    {
      "name": "text",
      "type": "string",
      "description": "text",
      "default": "text",
      "authorization_binding": {
        "source": "text",
        "resource_type": "text",
        "access": "read",
        "encoding": "csv"
      },
      "authorization_binding_test_value": "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",
      "authorization_binding": {
        "source": "text",
        "resource_type": "text",
        "access": "read",
        "encoding": "csv"
      },
      "authorization_binding_test_value": "text"
    }
  ],
  "timeout_ms": 1,
  "last_invoked_at": "2026-01-01T00:00:00.000Z",
  "deployed_at": "2026-01-01T00:00:00.000Z",
  "deployed_by": "123e4567-e89b-12d3-a456-426614174000"
}

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
}