{"openapi":"3.1.1","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Admetrics Analytics API — all supported versions","version":"2026.7.9","description":"Source-owned aggregate OpenAPI document for the preferred /api/20260709 contract, the deprecated /v1 compatibility contract, and shared MCP/OAuth discovery endpoints.","license":{"name":"Proprietary"}},"servers":[{"url":"/","description":"Current service origin"}],"tags":[{"name":"Service"},{"name":"Specification"},{"name":"Catalog"},{"name":"Freshness"},{"name":"Questions"},{"name":"Queries"},{"name":"MCP"},{"name":"OAuth"},{"name":"Legacy v1"},{"name":"Legacy aliases"}],"x-admetrics-source":"admetrics-analytics-service","x-admetrics-generated-from":"src/openapi.ts","x-admetrics-scope":"all","x-admetrics-api-versions":[{"id":"20260709","status":"current","base_path":"/api/20260709","openapi":"/api/20260709/openapi.json"},{"id":"v1","status":"deprecated","base_path":"/v1","openapi":"/v1/openapi.json","successor":"/api/20260709"}],"x-admetrics-advertised-mcp-tools":[{"name":"compile_analytics_question","title":"Compile analytics question","description":"Use this to turn a natural-language Admetrics analytics question into a validated structured analytics query without executing it. The natural-language compiler usually gives better results than hand-written structured queries because it handles dates, clients, catalog IDs, validation, and repair. Each natural-language question call supports one continuous date range and does not support direct comparison/change wording such as vs, compare, baseline, YoY, MoM, change, increase, drop, or spike. For comparisons, make one atomic call per period, or query one continuous range grouped by date/week/month and compute the comparison yourself. For multi-month trends, pass a continuous date range such as 2026-03-01 to 2026-05-31 and request grouping by month, month and channel, campaign, or another dimension as needed. If you used search_analytics_catalog and know exact fields, pass them as metric_ids/dimension_ids/sort_id here. Pass dimension_filters when exact indexed dimension values must constrain the query. Phrase requests as raw rows/totals for the intended date range and grouping fields only; corrective or comparison wording will be rejected or can add unintended field tokens.","inputSchema":{"type":"object","required":["question"],"properties":{"question":{"type":"string"},"client_id":{"type":["string","number"]},"client_ids":{"type":"array","items":{"type":["string","number"]}},"metric_ids":{"type":"array","items":{"type":"string"},"description":"Exact public metric IDs from search_analytics_catalog. Legacy canonical shopify.* metric IDs are accepted, but responses return public IDs."},"dimension_ids":{"type":"array","items":{"type":"string"},"description":"Exact dimension IDs from search_analytics_catalog. When provided, these are preserved exactly and validated instead of being inferred from ranking."},"dimension_filters":{"type":"array","maxItems":10,"items":{"type":"object","required":["dimension_id","value"],"properties":{"dimension_id":{"type":"string","description":"Exact indexed dimension ID from search_analytics_catalog, such as traffic_source or campaign_name."},"value":{"type":"string","description":"Dimension value to verify against the selected client's platform index before validation or execution."},"operator":{"type":"string","enum":["eq","contains"],"default":"eq","description":"eq requires an exact case-insensitive indexed value; contains requires an indexed substring match."}},"additionalProperties":false},"description":"Validated dimension-value filters. Use exact indexed dimension IDs and values discovered through search_dimension_values; values are client-scoped and index-verified before platform validation. Explicit entries override inferred filters for the same dimension."},"sort_id":{"type":"string","description":"Exact public metric ID or dimension ID to sort by. Prefer a public metric ID from search_analytics_catalog for ranked reports."},"sort_direction":{"type":"string","enum":["asc","desc"],"description":"Sort direction for sort_id. Defaults to desc for ranked reports."},"attribution_model":{"type":"string","description":"Exact attribution model to apply to every selected metric unless metric_params overrides it for a metric. The value must exist in the live catalog and be supported by every applied metric."},"attribution_window":{"type":["string","number"],"description":"Exact attribution window to apply to every selected metric unless metric_params overrides it for a metric. Numeric values are normalized to platform strings; max/lifetime maps to max."},"metric_params":{"type":"object","additionalProperties":{"type":"object","properties":{"attribution_model":{"type":"string","description":"Exact attribution model for this selected metric, such as first_touch, last_touch, last_touch_non_direct, linear, or prisma."},"attribution_window":{"type":["string","number"],"description":"Exact attribution window for this selected metric. Numbers are normalized to strings; max/lifetime maps to max."},"horizon_days":{"type":["number","string"],"description":"Exact customer-lifetime horizon for this selected metric, such as 30, 60, 90, 120, or 0 for max. Only use for metrics whose catalog params include horizon_days."}},"additionalProperties":false},"description":"Per-selected-metric params keyed by public metric ID, including attribution_model, attribution_window, and horizon_days. This does not select metrics; keys must match inferred metric_ids or explicitly supplied metric_ids."},"date_context":{"type":"string","description":"YYYY-MM-DD base date for relative date phrases."},"limit":{"type":"number"},"format":{"type":"string","enum":["records","rows","columnar","txt","text","csv","xlsx","dataframe","arrow","json"]},"response_detail":{"type":"string","enum":["compact","full"],"description":"Controls MCP response size. compact is the default and returns validation, intent, query summary, and result data without raw validation/candidate internals. full returns the complete service object for debugging."}}}},{"name":"run_analytics_question","title":"Run analytics question","description":"Primary and preferred tool for analytics answers. Use this for Admetrics metrics, breakdowns, charts, totals, rankings, or filtered results from a natural-language question. This path usually gives better results than a hand-written structured query because it applies deterministic parsing, catalog lookup, validation, asynchronous execution, and result fetching. Each natural-language question call supports one continuous date range and does not support direct comparison/change wording such as vs, compare, baseline, YoY, MoM, change, increase, drop, or spike. For comparisons, make one atomic call per period, or query one continuous range grouped by date/week/month and compute the comparison yourself. For multi-month trends, pass a continuous date range such as 2026-03-01 to 2026-05-31 and request grouping by month, month and channel, campaign, or another dimension as needed. If catalog search found exact fields, pass metric_ids/dimension_ids/sort_id here. Pass dimension_filters when exact indexed dimension values must constrain the query. Phrase requests as raw rows/totals for the intended date range and grouping fields only; corrective or comparison wording will be rejected or can add unintended field tokens.","inputSchema":{"type":"object","required":["question"],"properties":{"question":{"type":"string"},"client_id":{"type":["string","number"]},"client_ids":{"type":"array","items":{"type":["string","number"]}},"metric_ids":{"type":"array","items":{"type":"string"},"description":"Exact public metric IDs from search_analytics_catalog. Legacy canonical shopify.* metric IDs are accepted, but responses return public IDs."},"dimension_ids":{"type":"array","items":{"type":"string"},"description":"Exact dimension IDs from search_analytics_catalog. When provided, these are preserved exactly and validated instead of being inferred from ranking."},"dimension_filters":{"type":"array","maxItems":10,"items":{"type":"object","required":["dimension_id","value"],"properties":{"dimension_id":{"type":"string","description":"Exact indexed dimension ID from search_analytics_catalog, such as traffic_source or campaign_name."},"value":{"type":"string","description":"Dimension value to verify against the selected client's platform index before validation or execution."},"operator":{"type":"string","enum":["eq","contains"],"default":"eq","description":"eq requires an exact case-insensitive indexed value; contains requires an indexed substring match."}},"additionalProperties":false},"description":"Validated dimension-value filters. Use exact indexed dimension IDs and values discovered through search_dimension_values; values are client-scoped and index-verified before platform validation. Explicit entries override inferred filters for the same dimension."},"sort_id":{"type":"string","description":"Exact public metric ID or dimension ID to sort by. Prefer a public metric ID from search_analytics_catalog for ranked reports."},"sort_direction":{"type":"string","enum":["asc","desc"],"description":"Sort direction for sort_id. Defaults to desc for ranked reports."},"attribution_model":{"type":"string","description":"Exact attribution model to apply to every selected metric unless metric_params overrides it for a metric. The value must exist in the live catalog and be supported by every applied metric."},"attribution_window":{"type":["string","number"],"description":"Exact attribution window to apply to every selected metric unless metric_params overrides it for a metric. Numeric values are normalized to platform strings; max/lifetime maps to max."},"metric_params":{"type":"object","additionalProperties":{"type":"object","properties":{"attribution_model":{"type":"string","description":"Exact attribution model for this selected metric, such as first_touch, last_touch, last_touch_non_direct, linear, or prisma."},"attribution_window":{"type":["string","number"],"description":"Exact attribution window for this selected metric. Numbers are normalized to strings; max/lifetime maps to max."},"horizon_days":{"type":["number","string"],"description":"Exact customer-lifetime horizon for this selected metric, such as 30, 60, 90, 120, or 0 for max. Only use for metrics whose catalog params include horizon_days."}},"additionalProperties":false},"description":"Per-selected-metric params keyed by public metric ID, including attribution_model, attribution_window, and horizon_days. This does not select metrics; keys must match inferred metric_ids or explicitly supplied metric_ids."},"date_context":{"type":"string"},"limit":{"type":"number"},"format":{"type":"string","enum":["records","rows","columnar","txt","text","csv","xlsx","dataframe","arrow","json"]},"wait_for_result":{"type":"boolean","description":"When true, poll asynchronous status and fetch the result before returning. Defaults to true for run tools."},"timeout_ms":{"type":"number","description":"Maximum time to wait for async completion. Defaults to 120000."},"poll_interval_ms":{"type":"number","description":"Polling interval after initial enqueue. Defaults to 1000."},"result_format":{"type":"string","enum":["records","rows","columnar","txt","text","csv","xlsx","dataframe","arrow","json"],"description":"Analytics output format. text maps to txt, json maps to records."},"response_detail":{"type":"string","enum":["compact","full"],"description":"Controls MCP response size. compact is the default and returns validation, intent, query summary, and result data without raw validation/candidate internals. full returns the complete service object for debugging."}}}},{"name":"run_structured_analytics_query","title":"Run structured analytics query","description":"Low-level escape hatch. Use this only when you already have a non-empty structured analytics query returned by compile_analytics_question or explicitly provided by the user. This path skips the natural-language compiler and usually gives worse results for analytics questions. Public metric IDs are translated before platform validation. For catalog-derived exact fields, use run_analytics_question with metric_ids/dimension_ids.","inputSchema":{"type":"object","required":["analytics_query","query_source"],"properties":{"analytics_query":{"type":"object","description":"Required non-empty structured analytics query using public metric IDs. Do not pass an empty object."},"query_source":{"type":"string","enum":["compiled_question","user_provided_query"],"description":"Required provenance for this structured query."},"format":{"type":"string","enum":["records","rows","columnar","txt","text","csv","xlsx","dataframe","arrow","json"]},"wait_for_result":{"type":"boolean","description":"When true, poll asynchronous status and fetch the result before returning. Defaults to true for run tools."},"timeout_ms":{"type":"number","description":"Maximum time to wait for async completion. Defaults to 120000."},"poll_interval_ms":{"type":"number","description":"Polling interval after initial enqueue. Defaults to 1000."},"result_format":{"type":"string","enum":["records","rows","columnar","txt","text","csv","xlsx","dataframe","arrow","json"],"description":"Analytics output format. text maps to txt, json maps to records."},"response_detail":{"type":"string","enum":["compact","full"],"description":"Controls MCP response size. compact is the default and returns validation, intent, query summary, and result data without raw validation/candidate internals. full returns the complete service object for debugging."}}}},{"name":"list_available_clients","title":"List available clients","description":"Read-only list of active clients available to the caller's access token. Use this when you need client IDs or names; prefer it over fetching the full catalog when metrics and dimensions are not needed.","inputSchema":{"type":"object","properties":{"query":{"type":"string","description":"Optional text filter matched against client ID, display name, external name, parent client ID, child client IDs, and stack name."},"stack_name":{"type":"string","description":"Optional analytics stack to fetch clients from. Defaults to the service default stack."},"limit":{"type":"number","description":"Maximum clients to return. Defaults to 100 and is capped at 500."},"offset":{"type":"number","description":"Pagination offset. Use next_offset from the previous result to continue."}},"additionalProperties":false}},{"name":"get_client_data_freshness","title":"Get client data freshness","description":"Call this before answering analytics questions that cover today (the current day) or yesterday, and whenever data lag could affect interpretation. It returns the last successful regular DBT attribution update and last successful regular vendor pull for one client available to the caller token. It does not run analytics.","inputSchema":{"type":"object","required":["client_id"],"properties":{"client_id":{"type":["string","number"],"description":"Exact client ID. The caller token must grant access to this client."}},"additionalProperties":false}},{"name":"search_analytics_catalog","title":"Search analytics catalog","description":"Discovery-only tool for finding Admetrics public metric IDs, dimensions, clients, or dimension values. If value_query is present, it searches exact dimension values through platform indexes; pass dimension when known, or include field context in question so indexed dimensions can be inferred. If the user asks for an interactive picker, catalog picker UI, or picker-based exact ID selection, call open_analytics_catalog_picker instead of this direct search tool. After discovery, call run_analytics_question with the original analytics request and pass exact metric_ids/dimension_ids/sort_id when you know them. Value hits do not automatically create filters; pass selected values through dimension_filters.","inputSchema":{"type":"object","properties":{"question":{"type":"string"},"queries":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"dimension":{"type":"string","description":"Exact dimension ID to search for values, such as campaign_name or adset_name. If omitted, indexed dimensions are inferred from question/value_query."},"value_query":{"type":"string","description":"Text to search inside dimension values. Uses case-insensitive contains matching."},"client_ids":{"type":"array","items":{"type":["string","number"]},"description":"Optional client IDs used to scope index value lookup."},"value_limit":{"type":"number","description":"Maximum values to return per searched dimension. Defaults to 20 and is capped at 50."},"dimension_limit":{"type":"number","description":"Maximum inferred indexed dimensions to search when dimension is omitted. Defaults to 3 and is capped at 5."},"limit":{"type":"number"}},"additionalProperties":false},"description":"Optional batch of independent catalog searches. Prefer a single top-level question unless the caller needs separate metric/client/value lookups."},"dimension":{"type":"string","description":"Exact dimension ID to search for values, such as campaign_name or adset_name. If omitted, indexed dimensions are inferred from question/value_query."},"value_query":{"type":"string","description":"Text to search inside dimension values. Uses case-insensitive contains matching."},"client_ids":{"type":"array","items":{"type":["string","number"]},"description":"Optional client IDs used to scope index value lookup."},"value_limit":{"type":"number","description":"Maximum values to return per searched dimension. Defaults to 20 and is capped at 50."},"dimension_limit":{"type":"number","description":"Maximum inferred indexed dimensions to search when dimension is omitted. Defaults to 3 and is capped at 5."},"limit":{"type":"number"}},"additionalProperties":false}},{"name":"search_dimension_values","title":"Search dimension values","description":"Discovery-only tool for finding exact analytics dimension values such as campaign names, ad set names, products, channels, or event names. Use this when the issue is value discoverability or naming. Pass dimension when known; otherwise include field context in question so indexed dimensions can be inferred. Value hits do not automatically constrain compile/run calls; pass selected values through dimension_filters.","inputSchema":{"type":"object","properties":{"question":{"type":"string"},"queries":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"dimension":{"type":"string","description":"Exact dimension ID to search for values, such as campaign_name or adset_name. If omitted, indexed dimensions are inferred from question/value_query."},"value_query":{"type":"string","description":"Text to search inside dimension values. Uses case-insensitive contains matching."},"client_ids":{"type":"array","items":{"type":["string","number"]},"description":"Optional client IDs used to scope index value lookup."},"value_limit":{"type":"number","description":"Maximum values to return per searched dimension. Defaults to 20 and is capped at 50."},"dimension_limit":{"type":"number","description":"Maximum inferred indexed dimensions to search when dimension is omitted. Defaults to 3 and is capped at 5."},"limit":{"type":"number"}},"additionalProperties":false},"description":"Optional batch of independent dimension-value searches. Prefer a single top-level value_query unless separate lookups are needed."},"dimension":{"type":"string","description":"Exact dimension ID to search for values, such as campaign_name or adset_name. If omitted, indexed dimensions are inferred from question/value_query."},"value_query":{"type":"string","description":"Text to search inside dimension values. Uses case-insensitive contains matching."},"client_ids":{"type":"array","items":{"type":["string","number"]},"description":"Optional client IDs used to scope index value lookup."},"value_limit":{"type":"number","description":"Maximum values to return per searched dimension. Defaults to 20 and is capped at 50."},"dimension_limit":{"type":"number","description":"Maximum inferred indexed dimensions to search when dimension is omitted. Defaults to 3 and is capped at 5."},"limit":{"type":"number"}},"additionalProperties":false}},{"name":"explain_analytics_query","title":"Explain analytics query","description":"Use this when you need to explain analytics query-planning metadata from query_info.access_times, validation output, or query results.","inputSchema":{"type":"object","properties":{"query_info":{"type":"object"},"validation":{"type":"object"},"query_result":{"type":"object"}}}},{"name":"open_analytics_catalog_picker","title":"Open analytics catalog picker","description":"Use this when the user needs an interactive picker to choose exact public metric IDs, dimension IDs, client IDs, or sort IDs before compiling an analytics question. It opens a read-only MCP Apps UI and does not execute queries.","inputSchema":{"type":"object","properties":{"question":{"type":"string","description":"Natural-language analytics question to seed catalog search and compile preview."},"dimension":{"type":"string","description":"Exact dimension ID to search for indexed values. Search-only; not passed to compile arguments unless selected as a dimension_id."},"value_query":{"type":"string","description":"Text to search inside indexed dimension values. Search-only and does not create query filters."},"client_ids":{"type":"array","items":{"type":["string","number"]}},"metric_ids":{"type":"array","items":{"type":"string"}},"dimension_ids":{"type":"array","items":{"type":"string"}},"attribution_model":{"type":"string"},"attribution_window":{"type":["string","number"]},"metric_params":{"type":"object","additionalProperties":{"type":"object","properties":{"attribution_model":{"type":"string"},"attribution_window":{"type":["string","number"]}},"additionalProperties":false}},"sort_id":{"type":"string"},"sort_direction":{"type":"string","enum":["asc","desc"]},"date_context":{"type":"string","description":"YYYY-MM-DD base date for relative date phrases."},"limit":{"type":"number"},"value_limit":{"type":"number"},"dimension_limit":{"type":"number"},"format":{"type":"string","enum":["records","rows","columnar","txt","text","csv","xlsx","dataframe","arrow","json"]}}},"outputSchema":{"type":"object","required":["app","question","stack_name","selected","candidates","compile_arguments"],"properties":{"app":{"type":"string"},"question":{"type":"string"},"stack_name":{"type":"string"},"dimension":{"type":"string"},"value_query":{"type":"string"},"selected":{"type":"object","required":["metric_ids","dimension_ids","client_ids"],"properties":{"metric_ids":{"type":"array","items":{"type":"string"}},"dimension_ids":{"type":"array","items":{"type":"string"}},"client_ids":{"type":"array","items":{"type":"string"}},"sort_id":{"type":"string"},"sort_direction":{"type":"string","enum":["asc","desc"]}}},"candidates":{"type":"object","required":["rows"],"properties":{"rows":{"type":"array","items":{"type":"object","required":["id","kind","label","score","reasons","selected"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["metric","dimension","client","value"]},"label":{"type":"string"},"description":{"type":"string"},"score":{"type":"number"},"reasons":{"type":"array","items":{"type":"string"}},"selected":{"type":"boolean"},"field_id":{"type":"string"},"value":{},"dimension":{"type":"string"}}}},"index_error":{"type":"object"},"index_errors":{"type":"array","items":{"type":"object"}}}},"compile_arguments":{"type":"object","required":["question"],"properties":{"question":{"type":"string"},"client_ids":{"type":"array","items":{"type":"string"}},"metric_ids":{"type":"array","items":{"type":"string"}},"dimension_ids":{"type":"array","items":{"type":"string"}},"attribution_model":{"type":"string"},"attribution_window":{"type":["string","number"]},"metric_params":{"type":"object","additionalProperties":{"type":"object","properties":{"attribution_model":{"type":"string"},"attribution_window":{"type":["string","number"]}},"additionalProperties":false}},"sort_id":{"type":"string"},"sort_direction":{"type":"string","enum":["asc","desc"]},"date_context":{"type":"string"},"limit":{"type":"number"},"format":{"type":"string","enum":["records","rows","columnar","txt","text","csv","xlsx","dataframe","arrow","json"]}}}}}}],"x-internal-routes-omitted":["/v1/session*","/v1/logs*","/v1/traces*","browser QA routes"],"paths":{"/health":{"get":{"operationId":"getHealth","summary":"Check service health","tags":["Service"],"security":[],"responses":{"200":{"description":"Service version and data-access configuration state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/mcp":{"post":{"operationId":"callMcp","summary":"Send a Streamable HTTP MCP request","description":"Primary MCP transport for tools/list, tools/call, and optional MCP Apps resources. Use MCP-Protocol-Version and Mcp-Session-Id headers as required by the MCP client.","tags":["MCP"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpJsonRpcRequest"}}}},"responses":{"200":{"description":"MCP JSON-RPC response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpJsonRpcResponse"}}}},"202":{"description":"MCP notification accepted without a JSON-RPC response body."},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"operationId":"discoverMcpAuthentication","summary":"Discover MCP authentication requirements","description":"Returns an OAuth challenge when OAuth is configured. HTTP+SSE transport is intentionally unsupported.","tags":["MCP"],"security":[],"responses":{"401":{"description":"OAuth authentication challenge.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"405":{"description":"GET transport is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"operationId":"rejectMcpDelete","summary":"Report unsupported MCP session deletion","tags":["MCP"],"security":[{"bearerAuth":[]}],"responses":{"405":{"description":"Session deletion is not supported by this stateless transport.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/.well-known/oauth-protected-resource":{"get":{"operationId":"getOAuthProtectedResourceMetadata","summary":"Get OAuth protected-resource metadata","tags":["OAuth"],"security":[],"responses":{"200":{"description":"OAuth protected-resource metadata for the MCP resource server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthProtectedResourceMetadata"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/.well-known/oauth-protected-resource/mcp":{"get":{"operationId":"getMcpOAuthProtectedResourceMetadata","summary":"Get MCP OAuth protected-resource metadata","tags":["OAuth"],"security":[],"responses":{"200":{"description":"OAuth protected-resource metadata scoped to the MCP endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthProtectedResourceMetadata"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/openapi.json":{"get":{"operationId":"getAggregateOpenApi","summary":"Get the aggregate OpenAPI document","description":"Includes the preferred dated contract, the deprecated v1 compatibility contract, and shared MCP/OAuth paths.","tags":["Specification"],"security":[],"responses":{"200":{"description":"Aggregate OpenAPI 3.1.1 document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiDocument"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/20260709/openapi.json":{"get":{"operationId":"getOpenApi20260709","summary":"Get the 20260709 OpenAPI document","tags":["Specification"],"security":[],"responses":{"200":{"description":"OpenAPI 3.1.1 document for /api/20260709.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiDocument"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/20260709":{"get":{"operationId":"getApi20260709Index","summary":"Get the preferred API resource index","tags":["Service"],"security":[],"responses":{"200":{"description":"Version metadata and links to preferred resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiIndexResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/20260709/catalog":{"get":{"operationId":"getCatalog20260709","summary":"Get the normalized analytics catalog","description":"Catalog visibility and active clients are scoped to the caller token.","tags":["Catalog"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"stack_name","in":"query","required":false,"description":"Optional analytics stack. Defaults to the service default stack when client metadata does not resolve one.","schema":{"type":"string"}}],"responses":{"200":{"description":"Normalized metrics, dimensions, clients, and attribution metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/20260709/clients":{"get":{"operationId":"listClients20260709","summary":"List token-scoped active clients","tags":["Catalog"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"stack_name","in":"query","required":false,"description":"Optional analytics stack. Defaults to the service default stack when client metadata does not resolve one.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Case-insensitive text filter over client IDs, names, parent/child IDs, and stack name.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum clients to return. Defaults to 100 and is capped at 500.","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","in":"query","required":false,"description":"Pagination offset. Continue with next_offset from the preceding response.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Paginated client IDs and names available to the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientListResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/20260709/clients/{client_id}/freshness":{"get":{"operationId":"getClientDataFreshness20260709","summary":"Get client data freshness","description":"Returns the latest successful regular DBT attribution update and regular vendor pull for one token-authorized client. Backfills are excluded so repair work cannot make scheduled production data appear fresh. Call this before interpreting analytics that cover today or yesterday.","tags":["Freshness"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"description":"Exact numeric client ID available to the caller token.","schema":{"type":"string","pattern":"^[0-9]+$"}}],"responses":{"200":{"description":"Token-scoped DBT and vendor freshness checkpoints.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientDataFreshnessResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller token does not grant access to the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/20260709/catalog/search":{"post":{"operationId":"searchCatalog20260709","summary":"Search metrics, dimensions, clients, and indexed values","tags":["Catalog"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSearchRequest"}}}},"responses":{"200":{"description":"Ranked catalog candidates and optional indexed dimension values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSearchResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/20260709/questions/compile":{"post":{"operationId":"compileQuestion20260709","summary":"Compile and validate a natural-language analytics question","tags":["Questions"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NaturalLanguageQuestionRequest"}}}},"responses":{"200":{"description":"Resolved intent, structured analytics query, validation, and catalog candidates.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentCompileResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/20260709/questions/enqueue":{"post":{"operationId":"enqueueQuestion20260709","summary":"Compile, validate, and enqueue an analytics question","tags":["Questions"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NaturalLanguageQuestionRequest"}}}},"responses":{"200":{"description":"Compile result plus asynchronous execution state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentQuestionResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/20260709/questions/run":{"post":{"operationId":"runQuestion20260709","summary":"Compile, validate, run, and fetch an analytics result","tags":["Questions"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NaturalLanguageQuestionRequest"}}}},"responses":{"200":{"description":"Compile result plus asynchronous execution and result data when completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentQuestionResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/20260709/queries/run":{"post":{"operationId":"runStructuredQuery20260709","summary":"Validate and run a structured analytics query","tags":["Queries"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentStructuredQueryRunRequest"}}}},"responses":{"200":{"description":"Validation plus asynchronous execution and result data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentStructuredQueryRunResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/20260709/queries/explain":{"post":{"operationId":"explainQuery20260709","summary":"Explain query-planning metadata","tags":["Queries"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExplainQueryRequest"}}}},"responses":{"200":{"description":"Normalized query-planning explanation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExplainQueryResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/20260709/mcp/tools":{"get":{"operationId":"listMcpTools20260709","summary":"Inspect advertised MCP tools over REST","tags":["MCP"],"security":[],"responses":{"200":{"description":"MCP tool names, descriptions, annotations, and JSON schemas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpToolsResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/20260709/mcp/tools/call":{"post":{"operationId":"callMcpTool20260709","summary":"Call an advertised MCP tool over REST","tags":["MCP"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentMcpToolCallRequest"}}}},"responses":{"200":{"description":"Selected tool result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpToolCallResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/openapi.json":{"get":{"operationId":"getOpenApiV1","summary":"Get the legacy v1 OpenAPI document","description":"The v1 contract is deprecated; migrate to /api/20260709.","tags":["Specification","Legacy v1"],"security":[],"deprecated":true,"x-replaced-by":"/api/20260709/openapi.json","responses":{"200":{"description":"OpenAPI 3.1.1 document for the legacy v1 compatibility contract.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiDocument"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog":{"get":{"operationId":"getCatalogV1","summary":"Get the legacy normalized catalog","description":"Deprecated compatibility endpoint. Migrate to /api/20260709/catalog.","tags":["Catalog","Legacy v1"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"stack_name","in":"query","required":false,"description":"Optional analytics stack. Defaults to the service default stack when client metadata does not resolve one.","schema":{"type":"string"}}],"deprecated":true,"x-replaced-by":"/api/20260709/catalog","responses":{"200":{"description":"Legacy normalized catalog response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/clients":{"get":{"operationId":"listClientsV1","summary":"List token-scoped clients through v1","description":"Deprecated compatibility endpoint. Migrate to /api/20260709/clients.","tags":["Catalog","Legacy v1"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"stack_name","in":"query","required":false,"description":"Optional analytics stack. Defaults to the service default stack when client metadata does not resolve one.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Case-insensitive text filter over client IDs, names, parent/child IDs, and stack name.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum clients to return. Defaults to 100 and is capped at 500.","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","in":"query","required":false,"description":"Pagination offset. Continue with next_offset from the preceding response.","schema":{"type":"integer","minimum":0,"default":0}}],"deprecated":true,"x-replaced-by":"/api/20260709/clients","responses":{"200":{"description":"Legacy paginated client list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientListResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/mcp/tools":{"get":{"operationId":"listMcpToolsV1","summary":"Inspect MCP tools through v1","description":"Deprecated REST bridge. Migrate to /api/20260709/mcp/tools or protocol-level tools/list on /mcp.","tags":["MCP","Legacy v1"],"security":[],"deprecated":true,"x-replaced-by":"/api/20260709/mcp/tools","responses":{"200":{"description":"MCP tool definitions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpToolsResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/search":{"post":{"operationId":"searchCatalogV1","summary":"Search the catalog through v1","description":"Deprecated compatibility endpoint. Migrate to /api/20260709/catalog/search.","tags":["Catalog","Legacy v1"],"security":[{"bearerAuth":[]}],"deprecated":true,"x-replaced-by":"/api/20260709/catalog/search","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSearchRequest"}}}},"responses":{"200":{"description":"Legacy catalog search response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSearchResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/questions/compile":{"post":{"operationId":"compileQuestionV1","summary":"Compile a question through v1","description":"Deprecated compatibility endpoint. Migrate to /api/20260709/questions/compile.","tags":["Questions","Legacy v1"],"security":[{"bearerAuth":[]}],"deprecated":true,"x-replaced-by":"/api/20260709/questions/compile","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NaturalLanguageQuestionRequest"}}}},"responses":{"200":{"description":"Legacy compile response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyCompileResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/questions/enqueue":{"post":{"operationId":"enqueueQuestionV1","summary":"Enqueue a question through v1","description":"Deprecated compatibility endpoint. Migrate to /api/20260709/questions/enqueue.","tags":["Questions","Legacy v1"],"security":[{"bearerAuth":[]}],"deprecated":true,"x-replaced-by":"/api/20260709/questions/enqueue","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NaturalLanguageQuestionRequest"}}}},"responses":{"200":{"description":"Legacy enqueue response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyQuestionResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/questions/run":{"post":{"operationId":"runQuestionV1","summary":"Run a question through v1","description":"Deprecated compatibility endpoint. Migrate to /api/20260709/questions/run.","tags":["Questions","Legacy v1"],"security":[{"bearerAuth":[]}],"deprecated":true,"x-replaced-by":"/api/20260709/questions/run","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NaturalLanguageQuestionRequest"}}}},"responses":{"200":{"description":"Legacy run response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyQuestionResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/korrelat-queries/run":{"post":{"operationId":"runStructuredQueryV1","summary":"Run a structured query through v1","description":"Deprecated compatibility endpoint. Migrate to /api/20260709/queries/run.","tags":["Queries","Legacy v1"],"security":[{"bearerAuth":[]}],"deprecated":true,"x-replaced-by":"/api/20260709/queries/run","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyStructuredQueryRunRequest"}}}},"responses":{"200":{"description":"Legacy structured-query run response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyStructuredQueryRunResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/explain":{"post":{"operationId":"explainQueryV1","summary":"Explain query metadata through v1","description":"Deprecated compatibility endpoint. Migrate to /api/20260709/queries/explain.","tags":["Queries","Legacy v1"],"security":[{"bearerAuth":[]}],"deprecated":true,"x-replaced-by":"/api/20260709/queries/explain","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExplainQueryRequest"}}}},"responses":{"200":{"description":"Legacy explanation response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExplainQueryResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/mcp/tools/call":{"post":{"operationId":"callMcpToolV1","summary":"Call an MCP tool through v1","description":"Deprecated compatibility endpoint. Migrate to /api/20260709/mcp/tools/call.","tags":["MCP","Legacy v1"],"security":[{"bearerAuth":[]}],"deprecated":true,"x-replaced-by":"/api/20260709/mcp/tools/call","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyMcpToolCallRequest"}}}},"responses":{"200":{"description":"Selected MCP tool result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpToolCallResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/compile":{"post":{"operationId":"compileQuestionV1Alias","summary":"Compile a question through the short v1 alias","description":"Deprecated compatibility endpoint. Migrate to /api/20260709/questions/compile.","tags":["Legacy aliases"],"security":[{"bearerAuth":[]}],"deprecated":true,"x-replaced-by":"/api/20260709/questions/compile","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NaturalLanguageQuestionRequest"}}}},"responses":{"200":{"description":"Legacy compile response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyCompileResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/query":{"post":{"operationId":"enqueueQuestionV1Alias","summary":"Enqueue a question through the short v1 alias","description":"Deprecated compatibility endpoint. Migrate to /api/20260709/questions/enqueue.","tags":["Legacy aliases"],"security":[{"bearerAuth":[]}],"deprecated":true,"x-replaced-by":"/api/20260709/questions/enqueue","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NaturalLanguageQuestionRequest"}}}},"responses":{"200":{"description":"Legacy enqueue response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyQuestionResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/run":{"post":{"operationId":"runQuestionV1Alias","summary":"Run a question through the short v1 alias","description":"Deprecated compatibility endpoint. Migrate to /api/20260709/questions/run.","tags":["Legacy aliases"],"security":[{"bearerAuth":[]}],"deprecated":true,"x-replaced-by":"/api/20260709/questions/run","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NaturalLanguageQuestionRequest"}}}},"responses":{"200":{"description":"Legacy run response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyQuestionResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/query/raw":{"post":{"operationId":"runStructuredQueryV1Alias","summary":"Run a structured query through the short v1 alias","description":"Deprecated compatibility endpoint. Migrate to /api/20260709/queries/run.","tags":["Legacy aliases"],"security":[{"bearerAuth":[]}],"deprecated":true,"x-replaced-by":"/api/20260709/queries/run","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyStructuredQueryRunRequest"}}}},"responses":{"200":{"description":"Legacy structured-query run response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyStructuredQueryRunResponse"}}}},"400":{"description":"The request is malformed or locally invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A caller access token is required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource, version, or upstream object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The analytics platform rejected the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT or OAuth access token","description":"Caller-scoped analytics access token. Never embed literal tokens in documentation or source control."}},"schemas":{"OpenApiDocument":{"type":"object","required":["openapi","info","paths"],"additionalProperties":true},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"detail":{"type":"string"},"status":{"type":"integer"},"api_version":{"type":"string"},"requested_version":{"type":"string"},"supported_versions":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"OutputFormat":{"type":"string","description":"Result format. json aliases records; text aliases txt.","enum":["records","rows","columnar","csv","txt","xlsx","dataframe","arrow","json","text"]},"AnalyticsQuery":{"type":"object","minProperties":1,"description":"A non-empty structured analytics query. Exact metric and dimension IDs should come from catalog discovery.","properties":{"info":{"type":"object","additionalProperties":true},"options":{"type":"object","additionalProperties":true},"shape":{"type":"object","properties":{"format":{"$ref":"#/components/schemas/OutputFormat"}},"additionalProperties":true},"select":{"type":"object","properties":{"metrics":{"type":"array","items":{"type":"object","additionalProperties":true}},"dimensions":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"filters":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"AttributionMetricParams":{"type":"object","properties":{"attribution_model":{"type":"string"},"attribution_window":{"type":["string","number"]},"horizon_days":{"type":["string","number"]}},"additionalProperties":false},"DimensionFilterInput":{"type":"object","required":["dimension_id","value"],"properties":{"dimension_id":{"type":"string","description":"Exact indexed dimension ID returned by catalog search."},"value":{"type":"string","minLength":1,"maxLength":120,"description":"Client-scoped dimension value verified through the platform index before validation or execution."},"operator":{"type":"string","enum":["eq","contains"],"default":"eq"}},"additionalProperties":false},"NaturalLanguageQuestionRequest":{"type":"object","required":["question"],"properties":{"question":{"type":"string","minLength":1,"description":"One atomic analytics question covering one continuous date range."},"client_id":{"type":["string","number"]},"client_ids":{"type":"array","items":{"type":["string","number"]}},"metric_ids":{"type":"array","items":{"type":"string"}},"dimension_ids":{"type":"array","items":{"type":"string"}},"dimension_filters":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/DimensionFilterInput"}},"attribution_model":{"type":"string"},"attribution_window":{"type":["string","number"]},"metric_params":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/AttributionMetricParams"}},"sort_id":{"type":"string"},"sort_direction":{"type":"string","enum":["asc","desc"]},"stack_name":{"type":"string"},"date_context":{"type":"string","format":"date"},"limit":{"type":"integer","minimum":1},"format":{"$ref":"#/components/schemas/OutputFormat"},"result_format":{"$ref":"#/components/schemas/OutputFormat"},"wait_for_result":{"type":"boolean"},"timeout_ms":{"type":"integer","minimum":1,"default":120000},"poll_interval_ms":{"type":"integer","minimum":1,"default":1000},"response_detail":{"type":"string","enum":["compact","full"]}},"additionalProperties":false},"CatalogSearchRequest":{"type":"object","properties":{"question":{"type":"string"},"stack_name":{"type":"string"},"dimension":{"type":"string"},"value_query":{"type":"string"},"client_ids":{"type":"array","items":{"type":["string","number"]}},"limit":{"type":"integer","minimum":1},"value_limit":{"type":"integer","minimum":1,"maximum":50,"default":20},"dimension_limit":{"type":"integer","minimum":1,"maximum":5,"default":3}},"additionalProperties":false},"ExplainQueryRequest":{"type":"object","properties":{"query_info":{"type":"object","additionalProperties":true},"validation":{"type":"object","additionalProperties":true},"query_result":{"type":"object","additionalProperties":true}},"additionalProperties":true},"ValidationError":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"}},"additionalProperties":true},"Intent":{"type":"object","required":["stack_name","client_ids","metrics","dimensions","filters","sort","limit","format"],"properties":{"stack_name":{"type":"string"},"client_ids":{"type":"array","items":{"type":"string"}},"metrics":{"type":"array","items":{"type":"object","additionalProperties":true}},"dimensions":{"type":"array","items":{"type":"object","additionalProperties":true}},"filters":{"type":"array","items":{"type":"object","additionalProperties":true}},"date_range":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"source":{"type":"string"}},"additionalProperties":true},"sort":{"type":"array","items":{"type":"object","additionalProperties":true}},"limit":{"type":"integer"},"format":{"$ref":"#/components/schemas/OutputFormat"}},"additionalProperties":true},"Candidates":{"type":"object","required":["metrics","dimensions"],"properties":{"metrics":{"type":"array","items":{"type":"object","additionalProperties":true}},"dimensions":{"type":"array","items":{"type":"object","additionalProperties":true}},"clients":{"type":"array","items":{"type":"object","additionalProperties":true}},"dimension_values":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"ResultTablePreview":{"type":"object","required":["source","columns","rows","row_count","preview_row_count","truncated"],"properties":{"source":{"type":"string","enum":["arrow"]},"columns":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"type":"object","additionalProperties":true}},"row_count":{"type":"integer"},"preview_row_count":{"type":"integer"},"truncated":{"type":"boolean"}},"additionalProperties":false},"ResultPayload":{"type":"object","required":["content_type","byte_length"],"properties":{"content_type":{"type":"string"},"format":{"$ref":"#/components/schemas/OutputFormat"},"data":{},"text":{"type":"string"},"base64":{"type":"string","contentEncoding":"base64"},"table_preview":{"$ref":"#/components/schemas/ResultTablePreview"},"byte_length":{"type":"integer","minimum":0}},"additionalProperties":true},"AsyncExecution":{"type":"object","required":["queued"],"properties":{"queued":{"type":"object","additionalProperties":true},"status":{},"result":{"$ref":"#/components/schemas/ResultPayload"},"timed_out":{"type":"boolean"},"error":{"$ref":"#/components/schemas/ValidationError"}},"additionalProperties":true},"CatalogField":{"type":"object","required":["id","kind","aliases","hidden","internal","params"],"properties":{"id":{"type":"string"},"canonical_id":{"type":"string"},"public_id":{"type":"string"},"kind":{"type":"string","enum":["metric","dimension"]},"name":{"type":"string"},"description":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"hidden":{"type":"boolean"},"internal":{"type":"boolean"},"index":{"type":"boolean"},"params":{"type":"object","additionalProperties":true}},"additionalProperties":true},"ClientListItem":{"type":"object","required":["id","client_id","child_client_ids"],"properties":{"id":{"type":"string"},"client_id":{"type":"string"},"display_name":{"type":"string"},"external_name":{"type":"string"},"stack_name":{"type":"string"},"parent_client_id":{"type":"string"},"child_client_ids":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"ClientListResponse":{"type":"object","required":["stack_name","client_count","returned_count","offset","limit","next_offset","clients"],"properties":{"stack_name":{"type":"string"},"client_count":{"type":"integer"},"returned_count":{"type":"integer"},"offset":{"type":"integer"},"limit":{"type":"integer"},"next_offset":{"type":["integer","null"]},"clients":{"type":"array","items":{"$ref":"#/components/schemas/ClientListItem"}}},"additionalProperties":false},"CatalogResponse":{"type":"object","required":["stack_name","fetched_at","metric_count","dimension_count","client_count","metrics","dimensions","clients"],"properties":{"stack_name":{"type":"string"},"fetched_at":{"type":"string","format":"date-time"},"metric_count":{"type":"integer"},"dimension_count":{"type":"integer"},"client_count":{"type":"integer"},"attribution_models":{"type":"array","items":{"type":"string"}},"attribution_windows":{"type":"array","items":{"type":"string"}},"metrics":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CatalogField"}},"dimensions":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CatalogField"}},"clients":{"type":"object","additionalProperties":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"CatalogSearchResponse":{"type":"object","required":["stack_name","candidates"],"properties":{"stack_name":{"type":"string"},"candidates":{"$ref":"#/components/schemas/Candidates"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"}},"index_error":{"$ref":"#/components/schemas/ValidationError"},"index_errors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"}},"searched_dimensions":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"ExplainQueryResponse":{"type":"object","additionalProperties":true},"McpToolDefinition":{"type":"object","required":["name","description","inputSchema"],"properties":{"name":{"type":"string","enum":["compile_analytics_question","run_analytics_question","run_structured_analytics_query","list_available_clients","get_client_data_freshness","search_analytics_catalog","search_dimension_values","explain_analytics_query","open_analytics_catalog_picker"]},"title":{"type":"string"},"description":{"type":"string"},"annotations":{"type":"object","additionalProperties":true},"inputSchema":{"type":"object","additionalProperties":true},"outputSchema":{"type":"object","additionalProperties":true},"securitySchemes":{"type":"array","items":{"type":"object","additionalProperties":true}},"_meta":{"type":"object","additionalProperties":true}},"additionalProperties":true},"McpToolsResponse":{"type":"object","required":["tools"],"properties":{"tools":{"type":"array","items":{"$ref":"#/components/schemas/McpToolDefinition"}}},"additionalProperties":false},"McpToolCallResponse":{"description":"The selected MCP tool result. Individual result shapes are defined by MCP tool discovery when an outputSchema is advertised.","oneOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"McpJsonRpcRequest":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"type":["string","number","null"]},"method":{"type":"string"},"params":{"type":"object","additionalProperties":true}},"additionalProperties":true},"McpJsonRpcResponse":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"type":["string","number","null"]},"result":{},"error":{"type":"object","additionalProperties":true}},"additionalProperties":true},"OAuthProtectedResourceMetadata":{"type":"object","required":["resource","authorization_servers"],"properties":{"resource":{"type":"string","format":"uri"},"authorization_servers":{"type":"array","items":{"type":"string","format":"uri"}},"scopes_supported":{"type":"array","items":{"type":"string"}},"bearer_methods_supported":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"HealthResponse":{"type":"object","required":["status","api_version","release_version","data_access_configured"],"properties":{"status":{"type":"string","enum":["ok"]},"api_version":{"type":"string"},"release_version":{"type":"string"},"data_access_configured":{"type":"boolean"}},"additionalProperties":false},"ApiIndexResponse":{"type":"object","required":["name","version","release_version","resources"],"properties":{"name":{"type":"string"},"version":{"type":"string","enum":["20260709"]},"release_version":{"type":"string","enum":["2026.7.9"]},"resources":{"type":"object","required":["openapi","catalog","clients","client_freshness","compile_question","enqueue_question","run_question","run_structured_query","explain_query","mcp_tools"],"additionalProperties":{"type":"string"}}},"additionalProperties":false},"FreshnessCheckpoint":{"type":"object","required":["last_success_at"],"properties":{"last_success_at":{"type":["string","null"],"format":"date-time","description":"UTC completion time of the most recent successful regular run, or null when no run exists."}},"additionalProperties":false},"VendorFreshnessCheckpoint":{"type":"object","required":["last_success_at","vendors"],"properties":{"last_success_at":{"type":["string","null"],"format":"date-time","description":"UTC completion time of the most recent successful regular vendor pull, or null when no pull exists."},"vendors":{"type":"array","items":{"type":"string"},"description":"Vendor names tied at the latest successful completion time."}},"additionalProperties":false},"ClientDataFreshnessResponse":{"type":"object","required":["client_id","observed_at","dbt","vendor_pull"],"properties":{"client_id":{"type":"string"},"observed_at":{"type":"string","format":"date-time"},"dbt":{"$ref":"#/components/schemas/FreshnessCheckpoint"},"vendor_pull":{"$ref":"#/components/schemas/VendorFreshnessCheckpoint"}},"additionalProperties":false},"CurrentValidationResult":{"type":"object","required":["valid","errors","source"],"properties":{"valid":{"type":"boolean"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"}},"source":{"type":"string","enum":["local","platform"]},"raw":{}},"additionalProperties":true},"CurrentCompileResponse":{"type":"object","required":["intent","validation","candidates"],"properties":{"intent":{"$ref":"#/components/schemas/Intent"},"analytics_query":{"$ref":"#/components/schemas/AnalyticsQuery"},"validation":{"$ref":"#/components/schemas/CurrentValidationResult"},"needs_clarification":{"type":"array","items":{"type":"string"}},"candidates":{"$ref":"#/components/schemas/Candidates"}},"additionalProperties":true},"CurrentQuestionResponse":{"allOf":[{"$ref":"#/components/schemas/CurrentCompileResponse"},{"type":"object","properties":{"execution":{"$ref":"#/components/schemas/AsyncExecution"}},"additionalProperties":true}]},"CurrentStructuredQueryRunRequest":{"type":"object","required":["analytics_query","query_source"],"properties":{"analytics_query":{"$ref":"#/components/schemas/AnalyticsQuery"},"query_source":{"type":"string","enum":["compiled_question","user_provided_query"]},"format":{"$ref":"#/components/schemas/OutputFormat"},"result_format":{"$ref":"#/components/schemas/OutputFormat"},"wait_for_result":{"type":"boolean","default":true},"timeout_ms":{"type":"integer","minimum":1,"default":120000},"poll_interval_ms":{"type":"integer","minimum":1,"default":1000},"response_detail":{"type":"string","enum":["compact","full"]}},"additionalProperties":false},"CurrentStructuredQueryRunResponse":{"type":"object","required":["validation"],"properties":{"analytics_query":{"$ref":"#/components/schemas/AnalyticsQuery"},"validation":{"$ref":"#/components/schemas/CurrentValidationResult"},"execution":{"$ref":"#/components/schemas/AsyncExecution"}},"additionalProperties":true},"CurrentMcpToolCallRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["compile_analytics_question","run_analytics_question","run_structured_analytics_query","list_available_clients","get_client_data_freshness","search_analytics_catalog","search_dimension_values","explain_analytics_query","open_analytics_catalog_picker"]},"arguments":{"type":"object","additionalProperties":true}},"additionalProperties":false},"LegacyValidationResult":{"type":"object","required":["valid","errors","source"],"properties":{"valid":{"type":"boolean"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"}},"source":{"type":"string","enum":["local","korrelat"]},"raw":{}},"additionalProperties":true},"LegacyCompileResponse":{"type":"object","required":["intent","validation","candidates"],"properties":{"intent":{"$ref":"#/components/schemas/Intent"},"korrelat_query":{"$ref":"#/components/schemas/AnalyticsQuery"},"validation":{"$ref":"#/components/schemas/LegacyValidationResult"},"needs_clarification":{"type":"array","items":{"type":"string"}},"candidates":{"$ref":"#/components/schemas/Candidates"}},"additionalProperties":true},"LegacyQuestionResponse":{"allOf":[{"$ref":"#/components/schemas/LegacyCompileResponse"},{"type":"object","properties":{"execution":{"$ref":"#/components/schemas/AsyncExecution"}},"additionalProperties":true}]},"LegacyStructuredQueryRunRequest":{"type":"object","required":["korrelat_query"],"properties":{"korrelat_query":{"$ref":"#/components/schemas/AnalyticsQuery"},"query_source":{"type":"string","enum":["compile_korrelat_question","user_provided_korrelat_json"]},"format":{"$ref":"#/components/schemas/OutputFormat"},"result_format":{"$ref":"#/components/schemas/OutputFormat"},"wait_for_result":{"type":"boolean","default":true},"timeout_ms":{"type":"integer","minimum":1,"default":120000},"poll_interval_ms":{"type":"integer","minimum":1,"default":1000},"response_detail":{"type":"string","enum":["compact","full"]}},"additionalProperties":false},"LegacyStructuredQueryRunResponse":{"type":"object","required":["validation"],"properties":{"korrelat_query":{"$ref":"#/components/schemas/AnalyticsQuery"},"validation":{"$ref":"#/components/schemas/LegacyValidationResult"},"execution":{"$ref":"#/components/schemas/AsyncExecution"}},"additionalProperties":true},"LegacyMcpToolCallRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["compile_analytics_question","run_analytics_question","run_structured_analytics_query","list_available_clients","get_client_data_freshness","search_analytics_catalog","search_dimension_values","explain_analytics_query","open_analytics_catalog_picker","compile_korrelat_question","run_korrelat_question","run_korrelat_json_query","list_korrelat_clients","search_korrelat_catalog","search_korrelat_dimension_values","explain_korrelat_query","open_korrelat_catalog_picker","compile_korrelat_query","execute_korrelat_query","run_korrelat_query"],"description":"The legacy REST bridge accepts current advertised names and hidden compatibility aliases."},"arguments":{"type":"object","additionalProperties":true}},"additionalProperties":false}}}}