--- title: "Database Query" method: POST path: "/v1/tools/database-query" tags: ["Tools"] --- # Database Query `POST /v1/tools/database-query` Run a natural language query against connected SQL databases. ## Request body - DatabaseQueryBody — Request body for database query using the tool. - `query` string, required — The natural language query to run against connected databases. - `artifacts` union[], required — List of SQL database artifacts to query against. At least one artifact of type 'sql_database' is required. - union - FileArtifact — Input for base64 encoded files. - `type` 'file' — Input type discriminator - `value` string, required — Base64 encoded file content - UriArtifact — Input for remote URIs. - `type` 'uri' — Input type discriminator - `value` string, required — URI to download from - TextArtifact — Input for plain text content. - `type` 'text' — Input type discriminator - `value` string, required — Plain text content - IngestedArtifact — Input for already ingested content. - `type` 'ingested_artifact' — Input type discriminator - `context_filter` ContextFilter, required — Filter by collection, artifacts and metadata in the ingested context. The main filter is the collection the context is part of. All artifacts ids are ensured to be part of the context. If any of the ids is not usable in the context (i.e. doesn't exist), the related task will fail. The metadata filter will look for all context matching the metadata, if any, and add it to the context. The filter is a dictionary of key-value pairs. The key is the metadata key, and the value is the metadata value. If both artifacts and metadata filters are provided, the result will be the intersection of the two filters. - `collection` string — The name of the collection to filter on. - `artifacts` string[], nullable — Artifacts ids to filter on. - `metadata_filter` object[], nullable — Metadata filter to apply on the context. - SqlDatabaseArtifact — Input for SQL database content. - `type` 'sql_database' — Input type discriminator - `connection_string` string, required — SQL database connection string - `schemas` string[], nullable — List of specific schemas to include, if None includes all non-system schemas - `ssl` boolean — Whether to use SSL for the database connection - `enable_tables` boolean — Whether to include tables in the inspection - `enable_views` boolean — Whether to include views in the inspection - `enable_functions` boolean — Whether to include functions in the inspection - `enable_procedures` boolean — Whether to include stored procedures in the inspection - `description` string — Optional description of the database - SkillArtifact — Input for skill activation using SkillFilter. - `type` 'skill' — Input type discriminator - `skill_filter` SkillFilter, required — Collection-scoped filter used to resolve active skills and versions. - `collection` string, required — Tenant collection boundary used to recover skills. - `skill_or_version_ids` string[], nullable — Optional whitelist of identifiers inside collection. Each item may be a skill id (resolved to latest version) or a skill version id. ## Response `200` Database query completed successfully. - ToolResponse — Response returned from tool-based operations. - `content` union[], required — List of content blocks generated by the tool. Blocks can include plain text, citations, source attributions, or images. - union - TextBlock — Plain-text content block. - `type` 'text', required — type field. - `start_timestamp` string, date-time, nullable — start timestamp field. - `stop_timestamp` string, date-time, nullable — stop timestamp field. - `_meta` object — meta field. - `cache_control` CacheControlEphemeral — CacheControlEphemeral schema. - `type` 'ephemeral', required — type field. - `ttl` '5m' | '1h' — ttl field. - `text` string — Text payload for this block. - `citations` ZylonCitation[], nullable — citations field. - `id` string, nullable — Unique identifier for the citation - `index` integer, nullable — Index of the citation in the document - `artifact_id` string, nullable — Identifier of the artifact associated with the citation - `source_id` string, nullable — Identifier of the source document from which the citation is derived - ImageBlock — Anthropic-compatible image content block. - `type` 'image', required — type field. - `start_timestamp` string, date-time, nullable — start timestamp field. - `stop_timestamp` string, date-time, nullable — stop timestamp field. - `_meta` object — meta field. - `cache_control` CacheControlEphemeral — CacheControlEphemeral schema. - `type` 'ephemeral', required — type field. - `ttl` '5m' | '1h' — ttl field. - `source` union, required — Anthropic image source payload - Base64ImageSource — Anthropic base64 image source payload. - `type` 'base64', required — type field. - `data` string, byte, required — Base64-encoded image bytes - `media_type` 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp', required — media type field. - URLSource — Shared URL source payload (accepts url/uri input). - `type` 'url', required — type field. - `url` string, required — Publicly reachable URL - AudioBlock — Anthropic-compatible audio content block. - `type` 'audio', required — type field. - `start_timestamp` string, date-time, nullable — start timestamp field. - `stop_timestamp` string, date-time, nullable — stop timestamp field. - `_meta` object — meta field. - `cache_control` CacheControlEphemeral — CacheControlEphemeral schema. - `type` 'ephemeral', required — type field. - `ttl` '5m' | '1h' — ttl field. - `source` union, required — Audio source payload - Base64AudioSource — Anthropic-style base64 audio source payload. - `type` 'base64', required — type field. - `data` string, required — Base64-encoded audio bytes - `media_type` string, required — Audio MIME type, e.g. 'audio/mpeg' - URLSource — Shared URL source payload (accepts url/uri input). - `type` 'url', required — type field. - `url` string, required — Publicly reachable URL - BinaryBlock — Arbitrary binary payload (PDF, ZIP, …) encoded as base64. - `type` 'binary', required — type field. - `start_timestamp` string, date-time, nullable — start timestamp field. - `stop_timestamp` string, date-time, nullable — stop timestamp field. - `_meta` object — meta field. - `filename` string, nullable — filename field. - `source` union, required — Binary source payload - Base64BinarySource — Base64 source payload for arbitrary binary data. - `type` 'base64', required — type field. - `data` string, required — Base64-encoded binary data - `media_type` string, required — MIME type, e.g. 'application/pdf' - URIBinarySource — URI source payload for arbitrary binary data. - `type` 'url', required — type field. - `uri` string, required — Publicly reachable URI - LocalResourceBlock — Reference to a local file produced by code execution. - `type` 'local_resource', required — type field. - `start_timestamp` string, date-time, nullable — start timestamp field. - `stop_timestamp` string, date-time, nullable — stop timestamp field. - `_meta` object — meta field. - `file_path` string, required — Absolute path to the file inside the execution environment - `file_id` string, nullable — Base64url-encoded storage file ID used to download the file via the files API - `name` string, required — Human-readable file name (stem, without extension) - `mime_type` string, required — MIME type of the file - ResourceLinkBlock — Reference to an external resource by URI (not embedded). - `type` 'resource_link', required — type field. - `start_timestamp` string, date-time, nullable — start timestamp field. - `stop_timestamp` string, date-time, nullable — stop timestamp field. - `_meta` object — meta field. - `uri` string, required — URI of the external resource - `name` string, required — Human-readable resource name - `description` string, nullable — description field. - `mime_type` string, nullable — mime type field. - ResourceBlock — Embedded resource with metadata. - `type` 'resource', required — type field. - `start_timestamp` string, date-time, nullable — start timestamp field. - `stop_timestamp` string, date-time, nullable — stop timestamp field. - `_meta` object — meta field. - `resource` Resource, required — Resource schema. - `uri` string, required — uri field. - `name` string, required — name field. - `description` string, nullable — description field. - `mime_type` string, nullable — mime type field. - SourceBlock — Document chunks surfaced as RAG context attribution. - `type` 'source', required — type field. - `start_timestamp` string, date-time, nullable — start timestamp field. - `stop_timestamp` string, date-time, nullable — stop timestamp field. - `_meta` object — meta field. - `sources` union[], required — Document chunks used as context for this response - union - Chunk — Represents a chunk of text content from an ingested document. - … - Website — Represents a website URL source. - … - ThinkingBlock — Extended thinking block containing the model's reasoning process. - `type` 'thinking', required — type field. - `start_timestamp` string, date-time, nullable — start timestamp field. - `stop_timestamp` string, date-time, nullable — stop timestamp field. - `_meta` object — meta field. - `cache_control` CacheControlEphemeral — CacheControlEphemeral schema. - `type` 'ephemeral', required — type field. - `ttl` '5m' | '1h' — ttl field. - `thinking` string — Thinking payload - `signature` string, required — Anthropic reasoning signature required for extended thinking compatibility - `citations` ZylonCitation[], nullable — citations field. - `id` string, nullable — Unique identifier for the citation - `index` integer, nullable — Index of the citation in the document - `artifact_id` string, nullable — Identifier of the artifact associated with the citation - `source_id` string, nullable — Identifier of the source document from which the citation is derived - RedactedThinkingBlock — Redacted thinking block returned when thinking content is encrypted. - `type` 'redacted_thinking', required — type field. - `start_timestamp` string, date-time, nullable — start timestamp field. - `stop_timestamp` string, date-time, nullable — stop timestamp field. - `_meta` object — meta field. - `cache_control` CacheControlEphemeral — CacheControlEphemeral schema. - `type` 'ephemeral', required — type field. - `ttl` '5m' | '1h' — ttl field. - `data` string, required — Encrypted thinking payload - ToolUseBlock — Represents a model-initiated tool call. - `type` 'tool_use', required — type field. - `start_timestamp` string, date-time, nullable — start timestamp field. - `stop_timestamp` string, date-time, nullable — stop timestamp field. - `_meta` object — meta field. - `cache_control` CacheControlEphemeral — CacheControlEphemeral schema. - `type` 'ephemeral', required — type field. - `ttl` '5m' | '1h' — ttl field. - `id` string, required — Unique identifier for this tool use - `name` string, required — Name of the tool being called - `input` object, required — Input payload for the tool call - `caller` union — caller field. - DirectCaller — DirectCaller schema. - `type` 'direct', required — type field. - ServerToolCaller — ServerToolCaller schema. - `tool_id` string, required — Server tool identifier. - `type` 'code_execution_20250825', required — Caller type discriminator. - ServerToolCaller20260120 — ServerToolCaller20260120 schema. - `tool_id` string, required — Server tool identifier. - `type` 'code_execution_20260120', required — Caller type discriminator. - ServerToolUseBlock — Represents a server-side (built-in) tool call initiated by the model. - `type` 'server_tool_use', required — type field. - `start_timestamp` string, date-time, nullable — start timestamp field. - `stop_timestamp` string, date-time, nullable — stop timestamp field. - `_meta` object — meta field. - `cache_control` CacheControlEphemeral — CacheControlEphemeral schema. - `type` 'ephemeral', required — type field. - `ttl` '5m' | '1h' — ttl field. - `id` string, required — Unique identifier for this server tool use - `name` 'web_search' | 'web_fetch' | 'code_execution' | 'bash_code_execution' | 'text_editor_code_execution' | 'tool_search_tool_regex' | 'tool_search_tool_bm25', required — Name of the server tool being called - `input` object, required — Input payload for the server tool call - `caller` union — caller field. - DirectCaller — DirectCaller schema. - `type` 'direct', required — type field. - ServerToolCaller — ServerToolCaller schema. - `tool_id` string, required — Server tool identifier. - `type` 'code_execution_20250825', required — Caller type discriminator. - ServerToolCaller20260120 — ServerToolCaller20260120 schema. - `tool_id` string, required — Server tool identifier. - `type` 'code_execution_20260120', required — Caller type discriminator. - ContainerUploadBlock — References a file that was uploaded to an Anthropic container. - `type` 'container_upload', required — type field. - `start_timestamp` string, date-time, nullable — start timestamp field. - `stop_timestamp` string, date-time, nullable — stop timestamp field. - `_meta` object — meta field. - `cache_control` CacheControlEphemeral — CacheControlEphemeral schema. - `type` 'ephemeral', required — type field. - `ttl` '5m' | '1h' — ttl field. - `file_id` string, required — Container file identifier - DocumentBlock — Anthropic document block (used for document-grounded generation). - `type` 'document', required — type field. - `start_timestamp` string, date-time, nullable — start timestamp field. - `stop_timestamp` string, date-time, nullable — stop timestamp field. - `_meta` object — meta field. - `cache_control` CacheControlEphemeral — CacheControlEphemeral schema. - `type` 'ephemeral', required — type field. - `ttl` '5m' | '1h' — ttl field. - `source` union, required — Document source payload - Base64Source — Base64Source schema. - `type` 'base64' — type field. - `data` string, byte, required — data field. - `media_type` string, required — media type field. - PlainTextSource — PlainTextSource schema. - `type` 'text' — type field. - `data` string, required — data field. - `media_type` 'text/plain', required — media type field. - ContentSource — ContentSource schema. - `type` 'content' — type field. - `content` union, required — content field. - … - URLDocumentSource — URLDocumentSource schema. - `type` 'url' — type field. - `url` string, required — url field. - `title` string, nullable — title field. - `context` string, nullable — context field. - `citations` ZylonCitation[], nullable — citations field. - `id` string, nullable — Unique identifier for the citation - `index` integer, nullable — Index of the citation in the document - `artifact_id` string, nullable — Identifier of the artifact associated with the citation - `source_id` string, nullable — Identifier of the source document from which the citation is derived - SearchResultBlock — Anthropic search result block. - `type` 'search_result', required — type field. - `start_timestamp` string, date-time, nullable — start timestamp field. - `stop_timestamp` string, date-time, nullable — stop timestamp field. - `_meta` object — meta field. - `cache_control` CacheControlEphemeral — CacheControlEphemeral schema. - `type` 'ephemeral', required — type field. - `ttl` '5m' | '1h' — ttl field. - `source` string, required — Search result source payload - `title` string, required — Search result title - `content` TextBlock[], required — Search result content - `type` 'text', required — type field. - `start_timestamp` string, date-time, nullable — start timestamp field. - `stop_timestamp` string, date-time, nullable — stop timestamp field. - `_meta` object — meta field. - `cache_control` CacheControlEphemeral — CacheControlEphemeral schema. - `type` 'ephemeral', required — type field. - `ttl` '5m' | '1h' — ttl field. - `text` string — Text payload for this block. - `citations` ZylonCitation[], nullable — citations field. - `id` string, nullable — Unique identifier for the citation - `index` integer, nullable — Index of the citation in the document - `artifact_id` string, nullable — Identifier of the artifact associated with the citation - `source_id` string, nullable — Identifier of the source document from which the citation is derived - `citations` ZylonCitation[], nullable — citations field. - `id` string, nullable — Unique identifier for the citation - `index` integer, nullable — Index of the citation in the document - `artifact_id` string, nullable — Identifier of the artifact associated with the citation - `source_id` string, nullable — Identifier of the source document from which the citation is derived - MidConvSystemBlock — System instructions injected at a specific point mid-conversation. - `type` 'mid_conv_system', required — type field. - `start_timestamp` string, date-time, nullable — start timestamp field. - `stop_timestamp` string, date-time, nullable — stop timestamp field. - `_meta` object — meta field. - `cache_control` CacheControlEphemeral — CacheControlEphemeral schema. - `type` 'ephemeral', required — type field. - `ttl` '5m' | '1h' — ttl field. - `content` TextBlock[], required — System instruction text blocks. - `type` 'text', required — type field. - `start_timestamp` string, date-time, nullable — start timestamp field. - `stop_timestamp` string, date-time, nullable — stop timestamp field. - `_meta` object — meta field. - `cache_control` CacheControlEphemeral — CacheControlEphemeral schema. - `type` 'ephemeral', required — type field. - `ttl` '5m' | '1h' — ttl field. - `text` string — Text payload for this block. - `citations` ZylonCitation[], nullable — citations field. - `id` string, nullable — Unique identifier for the citation - `index` integer, nullable — Index of the citation in the document - `artifact_id` string, nullable — Identifier of the artifact associated with the citation - `source_id` string, nullable — Identifier of the source document from which the citation is derived - TLDRBlock — Condensed summary block. - `type` 'tldr', required — type field. - `start_timestamp` string, date-time, nullable — start timestamp field. - `stop_timestamp` string, date-time, nullable — stop timestamp field. - `_meta` object — meta field. - `content` union[] — content field. - union - TextBlock — Plain-text content block. - … - ImageBlock — Anthropic-compatible image content block. - … - AudioBlock — Anthropic-compatible audio content block. - … - BinaryBlock — Arbitrary binary payload (PDF, ZIP, …) encoded as base64. - … - LocalResourceBlock — Reference to a local file produced by code execution. - … - ResourceLinkBlock — Reference to an external resource by URI (not embedded). - … - ResourceBlock — Embedded resource with metadata. - … - SourceBlock — Document chunks surfaced as RAG context attribution. - … - ThinkingBlock — Extended thinking block containing the model's reasoning process. - … - RedactedThinkingBlock — Redacted thinking block returned when thinking content is encrypted. - … - ToolUseBlock — Represents a model-initiated tool call. - … - ServerToolUseBlock — Represents a server-side (built-in) tool call initiated by the model. - … - ContainerUploadBlock — References a file that was uploaded to an Anthropic container. - … - DocumentBlock — Anthropic document block (used for document-grounded generation). - … - SearchResultBlock — Anthropic search result block. - … - MidConvSystemBlock — System instructions injected at a specific point mid-conversation. - … - `tldr_side` 'left' | 'right' — tldr side field. - `is_error` boolean — True if the tool encountered an error during execution. ## Other responses - `401` — Unauthorized - `422` — Validation Error - Invalid request parameters ## Changes - **2026-07-06** `594fa71dfb90` — 6 breaking, 12 info - the response property `content/items/anyOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source/oneOf[subschema #2: PlainTextSource]/type` became optional for the status `200` - the response property `content/items/anyOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source/oneOf[subschema #3: ContentSource]/type` became optional for the status `200` - the response property `content/items/anyOf[subschema #16: TLDRBlock -> subschema #17: TLDRBlock]/content/items/anyOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source/oneOf[subschema #2: PlainTextSource]/type` became optional for the status `200` - the response property `content/items/anyOf[subschema #16: TLDRBlock -> subschema #17: TLDRBlock]/content/items/anyOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source/oneOf[subschema #3: ContentSource]/type` became optional for the status `200` - …14 more - **2026-06-03** `7914e6f947be` — 2 info - added `#/components/schemas/MidConvSystemBlock` to the `content/items/` response property `anyOf` list for the response status `200` - added `#/components/schemas/MidConvSystemBlock` to the `content/items/anyOf[subschema #15: TLDRBlock -> subschema #16: TLDRBlock]/content/items/` response property `anyOf` list for the response status `200` - **2026-06-02** `c711b911f68e` — 1 info - endpoint added [Change history](https://skmtc.dev/zylon-ai/apis/private-gpt-api/changes/v1/tools/database-query/post.md) --- [API](https://skmtc.dev/zylon-ai/apis/private-gpt-api.md) · [All operations](https://skmtc.dev/zylon-ai/apis/private-gpt-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/zylon-ai/private-gpt-api/revisions/4e828cf153c4/schema)