Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Auto-update documentation for master (#76849)

github-automation-metabase68f276b5a199
diff --git a/docs/api.json b/docs/api.json
index 6037817d077..08ceb372ec0 100644
--- a/docs/api.json
+++ b/docs/api.json
@@ -3548,6 +3548,23 @@
},
"required" : [ "name", "base_type", "display_name" ]
},
+ "metabase.agent-api.api.construct-native-query-request" : {
+ "description" : "Request body for /v1/construct-native-query: a target database and a raw SQL string.",
+ "type" : "object",
+ "properties" : {
+ "database_id" : {
+ "description" : "value must be an integer greater than zero.",
+ "type" : "integer",
+ "minimum" : 1
+ },
+ "sql" : {
+ "type" : "string",
+ "minLength" : 1
+ }
+ },
+ "required" : [ "database_id", "sql" ],
+ "additionalProperties" : false
+ },
"metabase.agent-api.api.construct-query-request" : {
"description" : "Request body for /v2/construct-query and the fresh-query branch of /v2/query.\n A single `:query` key whose value is a JSON object matching\n [[metabase.lib.schema/external-query]] — the canonical portable MBQL 5 wire format. The\n query is fully self-describing: the database is derived from the first stage's\n `source-table:` or `source-card:`, all field references are portable FKs\n (`[<db-name>, <schema>, <table-name>, <column-name>]`), and there is no auxiliary\n `source_entity` / `referenced_entities` envelope. See\n `resources/metabot/prompts/tools/construct_notebook_query.md` for the full format reference\n (including operators, joins, expressions, multi-stage queries, and FK conventions).\n\n Closed map: any extra top-level keys (notably the legacy `source_entity` /\n `referenced_entities` envelope from before the repr migration) are rejected with a 400 so\n callers don't silently send fields the server ignores.\n\n The inner `:query` value is intentionally typed as a plain `:map` at this boundary rather\n than `::lib.schema/external-query`. Reasons:\n\n 1. Deep MBQL-shape validation runs inside the representations pipeline\n (`metabot.tools.construct/execute-representations-query` calls `repr/validate-query`\n after the repair pass), so the boundary check would be redundant.\n\n 2. The strict-tool manifest lint (`assert-optional-fields-nullable!`) walks every map\n reachable from the tool input schema. `::external-query` references `::query`, which\n carries several `:optional` keys (`:lib/metadata`, `:database`, `:settings`, …) that\n are not `[:maybe ...]` — for sound reasons unrelated to this endpoint. Recursing into\n them would force a wide schema change just to satisfy the lint at the agent boundary.",
"type" : "object",
@@ -14758,6 +14775,42 @@
"tags" : [ "/api/agent" ]
}
},
+ "/api/agent/v1/construct-native-query" : {
+ "post" : {
+ "operationId" : "post-api-agent-v1-construct-native-query",
+ "summary" : "POST /api/agent/v1/construct-native-query",
+ "description" : "Construct a native (raw SQL) query against a database.\n\n Wraps `sql` into a serialized native query and returns it base64-encoded — the same\n `{\"query\": <base64>}` shape as /v2/construct-query — so it can be saved as a question via\n /v1/question (the MCP layer swaps the base64 for a `query_handle`).\n\n This endpoint does NOT execute the SQL; to run native SQL ad hoc use /v1/execute-sql. The\n MBQL execution endpoints (/v1/execute, /v2/query) reject native queries by design, so a\n handle produced here is for saving, not for /v2/query execution.",
+ "parameters" : [ ],
+ "responses" : {
+ "2XX" : {
+ "description" : "Successful response",
+ "content" : {
+ "application/json" : {
+ "schema" : {
+ "$ref" : "#/components/schemas/metabase.agent-api.api.construct-query-response"
+ }
+ }
+ }
+ },
+ "4XX" : {
+ "description" : "Client error response"
+ },
+ "5XX" : {
+ "description" : "Server error response"
+ }
+ },
+ "requestBody" : {
+ "content" : {
+ "application/json" : {
+ "schema" : {
+ "$ref" : "#/components/schemas/metabase.agent-api.api.construct-native-query-request"
+ }
+ }
+ }
+ },
+ "tags" : [ "/api/agent" ]
+ }
+ },
"/api/agent/v1/dashboard" : {
"post" : {
"operationId" : "post-api-agent-v1-dashboard",
@@ -14948,7 +15001,7 @@
"post" : {
"operationId" : "post-api-agent-v1-question",
"summary" : "POST /api/agent/v1/question",
- "description" : "Save a previously constructed query as a named question (card).\n\n The `query` parameter accepts a `query_handle` (UUID) returned by `construct_query`,\n or a base64-encoded MBQL string. MCP callers should always use the handle.\n Optionally specify display type, description, collection, and visualization settings.\n If `collection_id` is omitted the question is saved to the caller's personal collection.\n Pass an explicit `null` to save it to the root collection.\n The response `collection_path` is the saved location.",
+ "description" : "Save a previously constructed query as a named question (card).\n\n The `query` parameter accepts a `query_handle` (UUID) returned by `construct_query` (MBQL) or\n `construct_native_query` (native SQL), or a base64-encoded query string. MCP callers should\n always use the handle.\n Optionally specify display type, description, collection, and visualization settings.\n If `collection_id` is omitted the question is saved to the caller's personal collection.\n Pass an explicit `null` to save it to the root collection.\n The response `collection_path` is the saved location.\n\n Saving a native (raw SQL) query requires native-query permission on the target database.",
"parameters" : [ ],
"responses" : {
"2XX" : {
@@ -14984,7 +15037,7 @@
"put" : {
"operationId" : "put-api-agent-v1-question-id",
"summary" : "PUT /api/agent/v1/question/{id}",
- "description" : "Update a saved question (card). Patch semantics - only fields that you pass are changed.\n\n Set `collection_id` to move the card to a different collection. Set `archived: true` to archive.\n Pass `query` (a query_handle from construct_query, or a base64 MBQL string) to replace the underlying query.",
+ "description" : "Update a saved question (card). Patch semantics - only fields that you pass are changed.\n\n Set `collection_id` to move the card to a different collection. Set `archived: true` to archive.\n Pass `query` (a query_handle from construct_query or construct_native_query, or a base64 query\n string) to replace the underlying query. Replacing it with a native (raw SQL) query requires\n native-query permission on the target database.",
"parameters" : [ {
"in" : "path",
"name" : "id",
@@ -15025,6 +15078,42 @@
"tags" : [ "/api/agent" ]
}
},
+ "/api/agent/v1/question/{id}/query" : {
+ "post" : {
+ "operationId" : "post-api-agent-v1-question-id-query",
+ "summary" : "POST /api/agent/v1/question/{id}/query",
+ "description" : "Run a saved question (card) and return its results.\n\n Executes the query stored on the card under the caller's permissions and returns rows +\n column metadata — the same response shape as /v1/execute.\n\n Parameterized questions are NOT supported: if the card declares parameters or input\n template tags (field filters / variables), this returns a 400. Run it in Metabase, or\n save a parameterless version.",
+ "parameters" : [ {
+ "in" : "path",
+ "name" : "id",
+ "required" : true,
+ "schema" : {
+ "type" : "integer",
+ "minimum" : 1
+ },
+ "description" : "value must be an integer greater than zero."
+ } ],
+ "responses" : {
+ "2XX" : {
+ "description" : "Successful response",
+ "content" : {
+ "application/json" : {
+ "schema" : {
+ "$ref" : "#/components/schemas/metabase.agent-api.api.execute-query-response"
+ }
+ }
+ }
+ },
+ "4XX" : {
+ "description" : "Client error response"
+ },
+ "5XX" : {
+ "description" : "Server error response"
+ }
+ },
+ "tags" : [ "/api/agent" ]
+ }
+ },
"/api/agent/v1/read-resource" : {
"post" : {
"operationId" : "post-api-agent-v1-read-resource",