{ "openapi": "3.1.0", "info": { "title": "Unity Intelligence API", "version": "c10c2e9175c3efcc", "summary": "Headless control of Unity reports: data models, queries, pages, visuals, filters, HTML pages, files and the assistant.", "description": "Authenticate with a personal API key: `Authorization: Bearer `. `workspace:read` keys call reads; `workspace:write` keys also change reports and run the assistant. Every operation also applies the caller's report access (x-unity-access). Identifiers in paths and bodies are the ones the API returns: report UUIDs, page UUIDs or numeric page IDs, visual UUIDs. Values stay exact: a column's valueEncoding in column_metadata says how its values are written in JSON. The agent tools (GET /api/reports/{report_id}/tools) give an AI client the assistant's own operations." }, "servers": [ { "url": "https://api.x4tech.org", "description": "Unity hosted service" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Reports", "description": "Create, list, rename and delete reports; read a report's workspace, catalog and instructions." }, { "name": "Pages", "description": "Create, rename, duplicate, delete and restore report pages and their canvas settings." }, { "name": "Native visuals", "description": "Inspect visual capabilities and state; preview, create, update, copy, move and delete visuals." }, { "name": "Visual data", "description": "Read saved visuals' data, several visuals per request." }, { "name": "Filters", "description": "Report, page and visual filters, your own values for them, and the values a filter can choose from." }, { "name": "Data model", "description": "The report-owned model: sources, entities, fields, measures, relationships and model queries." }, { "name": "Connections", "description": "Data source connections and their attachment to reports." }, { "name": "Schema discovery", "description": "Source schema discovery (compatibility)." }, { "name": "SQL", "description": "Run read-only report SQL and keep saved queries." }, { "name": "Long-running reads", "description": "Follow, collect and cancel data reads that outlive one request." }, { "name": "Assistant runs", "description": "Ask Unity's assistant to do work, follow its runs and events, and read runtime documentation." }, { "name": "Agent tools", "description": "Call the assistant's tools directly, with your own AI: the same contracts, permissions and receipts." }, { "name": "Model Context Protocol", "description": "Unity's tools and guides for MCP clients." }, { "name": "Conversations", "description": "Report chats: transcripts and messages." }, { "name": "Conversation streaming (compatibility)", "description": "The browser's streaming chat transport." }, { "name": "HTML pages", "description": "HTML report pages: source, registrations, data and queries." }, { "name": "Live viewing and editing presence", "description": "An HTML page's live feed, and the leases and presence of every page." }, { "name": "Reference files and assets", "description": "Files attached to a report and the images they contain." }, { "name": "File imports", "description": "Upload a CSV file as a queryable dataset." }, { "name": "Text boxes and shapes (compatibility)", "description": "Older text box and shape endpoints." }, { "name": "Chart preset routes (compatibility)", "description": "Older per-chart data and delete endpoints." }, { "name": "Data tables (compatibility)", "description": "Older data table endpoints." }, { "name": "Service", "description": "Health and the API description." } ], "paths": { "/api/agent/context-runs": { "get": { "operationId": "agent_runs_recent_runs_get", "summary": "List recent runs' context (administrators)", "tags": [ "Assistant runs" ], "x-unity-scope": "workspace:read", "x-unity-access": "platform", "x-unity-reach": [ "chat" ], "description": "Platform administrators: recent assistant runs with what entered their context.", "parameters": [ { "name": "reportId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 } }, { "name": "entry", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/agent/documentation": { "get": { "operationId": "agent_runs_read_documentation_get", "summary": "Read Unity's runtime documentation", "tags": [ "Assistant runs" ], "x-unity-scope": "workspace:read", "x-unity-access": "account", "x-unity-reach": [ "docs" ], "description": "The guides Unity's assistant reads, from the running deployment: how report SQL, the model, visuals, HTML pages, files and testing work. Give these to your own AI.", "parameters": [ { "name": "topic", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "index", "connections", "sql", "html-authoring", "html-templates", "testing", "files", "visual-editing", "tabular-visuals" ], "default": "index" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string", "description": "Content version." }, "topic": { "type": "string" }, "title": { "type": "string" }, "markdown": { "type": "string", "description": "The guide (topics)." }, "source": { "type": "string" }, "topics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } } }, "description": "With topic index." } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/agent/runs": { "post": { "operationId": "agent_runs_create_background_run_post", "summary": "Ask Unity's assistant", "tags": [ "Assistant runs" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_view", "x-unity-reach": [ "chat" ], "description": "Queues a run of Unity's own assistant in one of your conversations (POST /api/datachats/add creates one) and answers 202 at once. The assistant inspects, queries and, with Edit access, changes the report through its tools; with View access it only reads. One run per conversation at a time (409 returns the active run). Requires an active subscription.\n\nTo control Unity with your own AI instead, call the same tools directly: GET /api/reports/{report_id}/tools, or connect an MCP client to /mcp.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid" }, "dataChatId": { "type": "integer", "description": "The conversation's DataChatID." }, "user_input": { "type": "string", "maxLength": 50000, "description": "The request, up to 50,000 characters." }, "clientRequestId": { "type": "string", "maxLength": 64, "description": "Deduplicates a retried submission." }, "mode": { "type": "string", "enum": [ "data_chat" ], "default": "data_chat" }, "layoutContext": { "type": "object", "description": "Optional: pageId the user is on, selected visuals, referenceFiles [{id}] to attach report files (report Edit, Admin or Owner only; anyone else is refused 403)." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "dataUrl": { "type": "string" } } }, "description": "Optional images." } }, "required": [ "reportId", "dataChatId", "user_input" ] }, "example": { "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82", "dataChatId": 37, "user_input": "Summarize spending by category and add a bar chart to the Spending page.", "clientRequestId": "run-spending-summary-1" } } } }, "responses": { "202": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "$ref": "#/components/schemas/AgentRun" }, "created": { "type": "boolean", "description": "False when clientRequestId matched an earlier run." }, "timings": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/agent/runs/{run_id}": { "get": { "operationId": "agent_runs_get_run_status_get", "summary": "Read a run", "tags": [ "Assistant runs" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "chat" ], "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "$ref": "#/components/schemas/AgentRun" } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/agent/runs/{run_id}/context": { "get": { "operationId": "agent_runs_inspect_run_get", "summary": "Read a run's context (administrators)", "tags": [ "Assistant runs" ], "x-unity-scope": "workspace:read", "x-unity-access": "platform", "x-unity-reach": [ "chat" ], "description": "Platform administrators: one run's context receipts (export=json for a download).", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "export", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json" ] } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/agent/runs/{run_id}/context/content/{digest}": { "get": { "operationId": "agent_runs_inspect_content_get", "summary": "Read one context entry (administrators)", "tags": [ "Assistant runs" ], "x-unity-scope": "workspace:read", "x-unity-access": "platform", "x-unity-reach": [ "chat" ], "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "digest", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/agent/runs/{run_id}/events": { "get": { "operationId": "agent_runs_get_run_events_get", "summary": "Read a run's events", "tags": [ "Assistant runs" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "chat" ], "description": "view=conversation: the run and its conversation events after afterSequence (messages, tool activity, answers), plus a cursor for the next poll; works while queued. Without view: stored events and tool_calls (each tool's arguments and result) of an initialized run.", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "conversation" ] } }, { "name": "afterSequence", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Return events after this sequence (the last cursor)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "$ref": "#/components/schemas/AgentRun" }, "events": { "type": "array", "items": { "type": "object", "properties": { "seq": { "type": "integer" }, "type": { "type": "string" }, "payload": { "type": "object" }, "created_at": { "type": "string" } } } }, "cursor": { "type": "integer", "description": "With view=conversation." }, "tool_calls": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/agent/runs/{run_id}/stop": { "post": { "operationId": "agent_runs_stop_run_post", "summary": "Stop a run", "tags": [ "Assistant runs" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_view", "x-unity-reach": [ "chat" ], "description": "A queued run is cancelled at once; a running run stops its future work and a running read promptly. A write in progress finishes and keeps its receipt. Nothing is rolled back.", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "$ref": "#/components/schemas/AgentRun" } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/agent/runs/{run_id}/stream": { "get": { "operationId": "agent_runs_stream_conversation_get", "summary": "Stream a run's events", "tags": [ "Assistant runs" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "chat" ], "description": "Server-sent events for a run executing on the serving worker; resume with afterSequence or Last-Event-ID. data: {\"fallback\":true} means poll the events endpoint instead (another worker, a finished run, or stream capacity). A browser EventSource cannot send a bearer header.", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "afterSequence", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Success.", "content": { "text/event-stream": { "schema": { "type": "string", "description": "Server-sent events." } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/agent/transcribe": { "post": { "operationId": "agent_runs_transcribe_voice_post", "summary": "Transcribe a voice message", "tags": [ "Assistant runs" ], "x-unity-scope": "workspace:write", "x-unity-access": "account", "x-unity-reach": [ "chat" ], "description": "Multipart form: reportId and an audio file. Returns the text for a message.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid" }, "audio": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "413": { "$ref": "#/components/responses/E413" }, "415": { "$ref": "#/components/responses/E415" } } } }, "/api/agent/workspace": { "get": { "operationId": "agent_runs_get_workspace_state_get", "summary": "Read your conversations' state", "tags": [ "Assistant runs" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "chat" ], "description": "Your conversations in a report with their latest run state and unread counts.", "parameters": [ { "name": "reportId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "object", "properties": { "unread_count": { "type": "integer" }, "working_count": { "type": "integer" } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/barGraphs/update": { "put": { "operationId": "visuals_update_bargraph_put", "summary": "Update a bar chart", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/update.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/bargraphs/data": { "get": { "operationId": "visual_compat_data_bargraphs_get", "summary": "Read a chart preset's data", "tags": [ "Chart preset routes (compatibility)" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "model", "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/reports/{report_id}/visual-data.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/bargraphs/delete": { "delete": { "operationId": "visual_compat_delete_bargraphs_delete", "summary": "Delete a chart preset", "tags": [ "Chart preset routes (compatibility)" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/delete.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/connections": { "get": { "operationId": "connections_bp_list_own_connections_get", "summary": "List your connections", "tags": [ "Connections" ], "x-unity-scope": "workspace:read", "x-unity-access": "account", "x-unity-reach": [ "source" ], "description": "Connections the caller owns, whether or not a report uses them. Credentials are never returned.", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Connection ID." }, "ownerUserId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "serverType": { "type": "string" }, "authType": { "type": [ "string", "null" ] }, "serverName": { "type": "string", "description": "Empty for uploaded-file connections." }, "databaseName": { "type": [ "string", "null" ] }, "connectionType": { "type": [ "string", "null" ], "enum": [ "database", "api", "file" ] }, "fileType": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/connections/add": { "post": { "operationId": "connections_bp_add_connection_post", "summary": "Create a connection", "tags": [ "Connections" ], "x-unity-scope": "workspace:write", "x-unity-access": "account", "x-unity-reach": [ "source" ], "description": "The one create: saves a source connection owned by the caller, and attaches it to reportId when given. It does not connect (except an Analysis Services model, discovered as it is attached): test it (POST /api/connections/{connection_id}/test) or list its tables (POST /get-schema). Add the source to the report's data model to query it. In production, a server whose address is private (a private network, loopback, link-local or cloud metadata address) is refused when Unity connects.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Attach to this report (Edit access)." }, "serverType": { "type": "string", "enum": [ "SQLServer", "Snowflake", "Databricks", "AnalysisServices", "API" ], "description": "Source kind; fixed once created." }, "serverName": { "type": "string", "description": "Server or host (SQL Server: host[,port]; Snowflake: account; API: the provider, FRED, WORLDBANK or USCENSUS)." }, "databaseName": { "type": "string", "description": "Database, catalog, or Analysis Services model." }, "authType": { "type": "string", "enum": [ "UserPassAuth", "EntraPassword", "EntraServicePrincipal", "EntraBrowser", "EntraIntegrated", "EntraManagedIdentity", "WindowsAuth", "KeyPairAuth", "OAuthClientCredentials", "SnowflakeOAuth", "DatabricksEntraServicePrincipalSecret", "DatabricksEntraServicePrincipalCert", "DatabricksEntraUserSSO", "DatabricksEntraBrowser", "DatabricksOAuth", "AASInteractive", "AASServicePrincipalCertificate", "ApiKey" ], "description": "How Unity signs in. SQL Server: UserPassAuth (SQL login), EntraPassword, EntraServicePrincipal (username = client ID, password = secret), EntraBrowser. Snowflake: UserPassAuth, KeyPairAuth (privateKey), OAuthClientCredentials, SnowflakeOAuth. Databricks: DatabricksEntraServicePrincipalSecret (default), DatabricksEntraServicePrincipalCert, DatabricksEntraUserSSO (databricksAccessToken), DatabricksEntraBrowser, DatabricksOAuth. Analysis Services: AASInteractive, EntraServicePrincipal, AASServicePrincipalCertificate, EntraPassword. API providers: ApiKey. Browser methods (EntraBrowser, SnowflakeOAuth, DatabricksEntraBrowser, DatabricksOAuth, AASInteractive) sign each reader in through the browser application and cannot complete headlessly. Server-identity methods (WindowsAuth, EntraIntegrated, EntraManagedIdentity) need a platform administrator." }, "username": { "type": "string", "description": "Login." }, "clientId": { "type": "string", "description": "Client (application) ID of a service principal." }, "password": { "type": "string", "description": "Password, API key, client secret or access token. Stored encrypted; never returned." }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "connectionName": { "type": "string", "description": "Display name; generated from server and database when omitted, numbered when taken." }, "apiKey": { "type": "string", "description": "API providers: the provider's key." }, "account": { "type": "string", "description": "Snowflake account." }, "warehouse": { "type": "string", "description": "Snowflake warehouse." }, "schemaName": { "type": "string", "description": "Snowflake schema." }, "role": { "type": "string", "description": "Snowflake role." }, "privateKey": { "type": "string", "description": "Snowflake key-pair private key (PEM)." }, "privateKeyPassphrase": { "type": "string" }, "oauthClientId": { "type": "string" }, "oauthClientSecret": { "type": "string" }, "oauthTokenUrl": { "type": "string" }, "oauthScope": { "type": "string" }, "httpPath": { "type": "string", "description": "Databricks SQL warehouse HTTP path." }, "databricksSchema": { "type": "string", "description": "Databricks schema." }, "tenantId": { "type": "string", "description": "Microsoft Entra tenant." }, "databricksClientId": { "type": "string" }, "databricksClientSecret": { "type": "string" }, "databricksAccessToken": { "type": "string", "description": "Databricks personal access token." }, "analysisServicesOptions": { "type": "object", "description": "Analysis Services sign-in options (tenant, client, endpoint)." } }, "required": [ "serverType", "serverName" ] }, "example": { "serverType": "SQLServer", "serverName": "sql.example.com", "databaseName": "Sales", "authType": "UserPassAuth", "username": "unity_reader", "password": "********", "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82" } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "connection": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "serverType": { "type": "string" }, "serverName": { "type": "string" }, "databaseName": { "type": [ "string", "null" ] } } } } }, "example": { "status": "success", "message": "Connection created successfully", "connection": { "id": 31, "name": "SQLServer - sql.example.com - Sales", "serverType": "SQLServer", "serverName": "sql.example.com", "databaseName": "Sales" } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/connections/check-report-usage/{connection_id}": { "get": { "operationId": "connections_bp_check_connection_report_usage_get", "summary": "List reports using a connection", "tags": [ "Connections" ], "x-unity-scope": "workspace:read", "x-unity-access": "account", "x-unity-reach": [ "source" ], "description": "Reports the caller can open that use the connection; others are only counted. A report being deleted no longer uses it: deletingReports names those the caller can open.", "parameters": [ { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "affectedReports": { "type": "array", "items": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid" }, "reportName": { "type": "string" } } } }, "otherReportCount": { "type": "integer" }, "deletingReports": { "type": "array", "items": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid" }, "reportName": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/connections/delete/{connection_id}": { "delete": { "operationId": "connections_bp_delete_connection_delete", "summary": "Delete a connection", "tags": [ "Connections" ], "x-unity-scope": "workspace:write", "x-unity-access": "account", "x-unity-reach": [ "source" ], "description": "Deletes a connection the caller owns. While reports use it the answer is 409 connection_in_use naming them; confirm=true deletes it anyway and those reports show an error until an editor replaces the source. A connection an organization's report uses is never deleted this way (409 company_source_in_use, even with confirm): detach it from that report first.", "parameters": [ { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "confirm", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/connections/report/add": { "post": { "operationId": "connections_bp_add_connection_to_report_post", "summary": "Attach a connection to a report", "tags": [ "Connections" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "model", "source" ], "description": "Edit access to the report and access to the connection. Then add its outputs to the report's data model (PUT /api/reports/{report_id}/data-model/sources/{connection_id}).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "integer" } }, "required": [ "reportId", "connectionId" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/connections/report/remove": { "delete": { "operationId": "connections_bp_remove_connection_from_report_delete", "summary": "Detach a connection from a report", "tags": [ "Connections" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "model", "source" ], "description": "Removes the source and its model outputs from the report. Removing a field also removes the calculated fields, measures and relationships that use it. When anything reads what a write removes, or SQL names what it renames, the write is refused with code in_use (HTTP 409) and the readers (kind, title, id, pageId, page, effect); confirm=true makes it anyway, and the result lists what went with it (removedWith) and what now shows an error (breaks). Documentation topic connections has the full rules.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "integer" }, "confirm": { "type": "boolean", "description": "true makes the change after 409 in_use." } }, "required": [ "reportId", "connectionId" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/connections/report/{report_id}": { "get": { "operationId": "connections_bp_get_report_connections_get", "summary": "List a report's connections", "tags": [ "Connections" ], "x-unity-scope": "workspace:read", "x-unity-access": "view", "x-unity-reach": [ "source" ], "description": "Connections attached to the report, with each one's model state.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "connectionId": { "type": "integer" }, "name": { "type": "string" }, "serverType": { "type": "string" } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/connections/update/{connection_id}": { "put": { "operationId": "connections_bp_update_connection_put", "summary": "Update a connection", "tags": [ "Connections" ], "x-unity-scope": "workspace:write", "x-unity-access": "account", "x-unity-reach": [ "source" ], "description": "Changes the given settings of a connection the caller owns; omitted settings keep their values. serverType and connectionType cannot change. An uploaded file's connection only renames. An API key may change only connectionName: other settings and secrets change in Unity, signed in (403 otherwise); create a new connection instead.", "parameters": [ { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serverName": { "type": "string", "description": "Server or host (SQL Server: host[,port]; Snowflake: account; API: the provider, FRED, WORLDBANK or USCENSUS)." }, "databaseName": { "type": "string", "description": "Database, catalog, or Analysis Services model." }, "authType": { "type": "string", "enum": [ "UserPassAuth", "EntraPassword", "EntraServicePrincipal", "EntraBrowser", "EntraIntegrated", "EntraManagedIdentity", "WindowsAuth", "KeyPairAuth", "OAuthClientCredentials", "SnowflakeOAuth", "DatabricksEntraServicePrincipalSecret", "DatabricksEntraServicePrincipalCert", "DatabricksEntraUserSSO", "DatabricksEntraBrowser", "DatabricksOAuth", "AASInteractive", "AASServicePrincipalCertificate", "ApiKey" ], "description": "How Unity signs in. SQL Server: UserPassAuth (SQL login), EntraPassword, EntraServicePrincipal (username = client ID, password = secret), EntraBrowser. Snowflake: UserPassAuth, KeyPairAuth (privateKey), OAuthClientCredentials, SnowflakeOAuth. Databricks: DatabricksEntraServicePrincipalSecret (default), DatabricksEntraServicePrincipalCert, DatabricksEntraUserSSO (databricksAccessToken), DatabricksEntraBrowser, DatabricksOAuth. Analysis Services: AASInteractive, EntraServicePrincipal, AASServicePrincipalCertificate, EntraPassword. API providers: ApiKey. Browser methods (EntraBrowser, SnowflakeOAuth, DatabricksEntraBrowser, DatabricksOAuth, AASInteractive) sign each reader in through the browser application and cannot complete headlessly. Server-identity methods (WindowsAuth, EntraIntegrated, EntraManagedIdentity) need a platform administrator." }, "username": { "type": "string", "description": "Login." }, "clientId": { "type": "string", "description": "Client (application) ID of a service principal." }, "password": { "type": "string", "description": "Password, API key, client secret or access token. Stored encrypted; never returned." }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "connectionName": { "type": "string", "description": "Display name; generated from server and database when omitted, numbered when taken." }, "apiKey": { "type": "string", "description": "API providers: the provider's key." }, "account": { "type": "string", "description": "Snowflake account." }, "warehouse": { "type": "string", "description": "Snowflake warehouse." }, "schemaName": { "type": "string", "description": "Snowflake schema." }, "role": { "type": "string", "description": "Snowflake role." }, "privateKey": { "type": "string", "description": "Snowflake key-pair private key (PEM)." }, "privateKeyPassphrase": { "type": "string" }, "oauthClientId": { "type": "string" }, "oauthClientSecret": { "type": "string" }, "oauthTokenUrl": { "type": "string" }, "oauthScope": { "type": "string" }, "httpPath": { "type": "string", "description": "Databricks SQL warehouse HTTP path." }, "databricksSchema": { "type": "string", "description": "Databricks schema." }, "tenantId": { "type": "string", "description": "Microsoft Entra tenant." }, "databricksClientId": { "type": "string" }, "databricksClientSecret": { "type": "string" }, "databricksAccessToken": { "type": "string", "description": "Databricks personal access token." }, "analysisServicesOptions": { "type": "object", "description": "Analysis Services sign-in options (tenant, client, endpoint)." } } }, "example": { "connectionName": "Sales warehouse" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/connections/{connection_id}/credentials": { "get": { "operationId": "connections_bp_connection_credentials_get", "summary": "Read what a connection's credentials page asks for", "tags": [ "Connections" ], "x-unity-scope": "workspace:read", "x-unity-access": "account", "x-unity-reach": [ "source" ], "description": "For the connection's owner (anyone else: 404): where its credentials go (recipients: host, port, account, token endpoint, provider) and which its sign-in takes (fields: who signs in, the user name or client ID, then the secrets), never their values. credentials is set or missing, null when the sign-in takes none.", "parameters": [ { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connectionId": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": [ "string", "null" ] }, "authType": { "type": [ "string", "null" ] }, "databaseName": { "type": [ "string", "null" ] }, "credentials": { "type": [ "string", "null" ], "enum": [ "set", "missing" ] }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" } } } }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "multiline": { "type": "boolean" }, "secret": { "type": "boolean", "description": "false for the user name or client ID." }, "optional": { "type": "boolean" } } } }, "readerSignIn": { "type": "boolean", "description": "Each reader signs in with their own account." } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/connections/{connection_id}/test": { "post": { "operationId": "connections_bp_test_owned_connection_post", "summary": "Test a connection", "tags": [ "Connections" ], "x-unity-scope": "workspace:write", "x-unity-access": "account", "x-unity-reach": [ "source" ], "description": "For the connection's owner (anyone else: 404): connects with its saved settings and credentials and rediscovers its tables, as the TestConnection tool does. An API provider is checked as configured (recognized, its key present), without calling it.", "parameters": [ { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connectionId": { "type": "integer" }, "ok": { "type": "boolean" }, "checked": { "type": "string", "enum": [ "source", "configuration" ] }, "tables": { "type": "integer", "description": "Tables discovered." }, "model": { "type": "object", "description": "Analysis Services: the model's cube and counts." }, "needsCredentials": { "type": "boolean" }, "credentialsUrl": { "type": "string" }, "error": { "type": "string", "description": "The source's error, without credentials." }, "sourceAuth": { "type": "object", "description": "A reader must sign in." } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/dataCards/update": { "put": { "operationId": "visuals_update_data_card_put", "summary": "Update a data card", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/update.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/dataTables/update": { "put": { "operationId": "visuals_update_datatable_put", "summary": "Update a table", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/update.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/datacards/data": { "get": { "operationId": "visual_compat_data_datacards_get", "summary": "Read a chart preset's data", "tags": [ "Chart preset routes (compatibility)" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "model", "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/reports/{report_id}/visual-data.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/datacards/delete": { "delete": { "operationId": "visual_compat_delete_datacards_delete", "summary": "Delete a chart preset", "tags": [ "Chart preset routes (compatibility)" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/delete.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/datachat/delete": { "delete": { "operationId": "e2e_datachat_delete_datachat_delete", "summary": "Delete a conversation", "tags": [ "Conversation streaming (compatibility)" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_view", "x-unity-reach": [ "chat" ], "description": "Deletes your conversation and its history (202: cleanup continues). Refused while a run is active.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid" }, "id": { "type": "integer", "description": "DataChatID." } }, "required": [ "reportId", "id" ] } } } }, "responses": { "202": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "details": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/datachat/transcript": { "get": { "operationId": "datachats_get_transcript_get", "summary": "Read a conversation", "tags": [ "Conversations" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "chat" ], "description": "Your conversation's messages, the actions its runs took (with change receipts) and its timeline, in one read. Conversations are private to their creator (404 otherwise).", "parameters": [ { "name": "reportId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "dataChatId", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "sender": { "type": "string" }, "text": { "type": "string" }, "run_id": { "type": "string" }, "timestamp": { "type": "string" } } } }, "actions": { "type": "array", "items": { "type": "object", "description": "A tool action: tool, status and result receipt." } }, "projection": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/datachats": { "get": { "operationId": "visuals_get_data_chats_get", "summary": "List your conversations on a page", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "chat" ], "description": "Your own report chats on a page (conversations are private to their creator).", "parameters": [ { "name": "reportId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Report ID." }, { "name": "pageId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The page: its UUID or numeric ID." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "DataChatID": { "type": "integer" }, "Name": { "type": "string" }, "PageID": { "type": "integer" } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/datachats/add": { "post": { "operationId": "visuals_add_data_chat_post", "summary": "Create a conversation", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_view", "x-unity-reach": [ "chat" ], "description": "A new report chat for assistant runs (POST /api/agent/runs takes its DataChatID).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "activePage": { "type": "string", "description": "The page: its UUID or numeric ID." }, "name": { "type": "string", "maxLength": 100 }, "clientRequestId": { "type": "string", "maxLength": 64 } }, "required": [ "reportId", "activePage" ] }, "example": { "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82", "activePage": 890, "name": "API exploration" } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "DataChatID": { "type": "integer" }, "Name": { "type": "string" }, "PageID": { "type": "integer" }, "createdNow": { "type": "boolean", "description": "False when clientRequestId replayed an earlier creation." } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/datachats/update": { "put": { "operationId": "datachats_update_datachat_name_put", "summary": "Rename a conversation", "tags": [ "Conversations" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_view", "x-unity-reach": [ "chat" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid" }, "dataChatId": { "type": "integer" }, "newName": { "type": "string", "maxLength": 100 } }, "required": [ "reportId", "dataChatId", "newName" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/datatables/data": { "get": { "operationId": "data_table_e2e_get_datatable_data_get", "summary": "Read a table page", "tags": [ "Data tables (compatibility)" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "model", "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/reports/{report_id}/visual-data.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/datatables/delete": { "delete": { "operationId": "data_table_e2e_delete_datatable_delete", "summary": "Delete a table", "tags": [ "Data tables (compatibility)" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/delete.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/datatables/export": { "get": { "operationId": "data_table_e2e_export_datatable_data_get", "summary": "Export a table's rows", "tags": [ "Data tables (compatibility)" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "model", "pages" ], "description": "Every row of a saved table, under the filters as they apply to you and in your own sort (PUT /api/my-view), else its query's, for an export; the browser writes it as CSV. Large exports may continue as a read job (202).", "parameters": [ { "name": "reportId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Report ID." }, { "name": "pageId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The table's page: UUID or numeric ID." }, { "name": "dataTableId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The table's UUID or legacy numeric ID." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sql_data": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "array", "items": {} } }, "column_metadata": { "type": "array", "items": { "$ref": "#/components/schemas/ColumnMetadata" } } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/declarativeCharts/data": { "get": { "operationId": "visuals_get_declarative_chart_data_get", "summary": "Read a chart's data", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "model", "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/reports/{report_id}/visual-data.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/declarativeCharts/update": { "put": { "operationId": "visuals_update_declarative_chart_put", "summary": "Update a chart", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/update.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/declarativecharts/delete": { "delete": { "operationId": "visuals_delete_declarative_chart_delete", "summary": "Delete a chart", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/delete.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/file/datasets": { "post": { "operationId": "dataset_files_create_upload_post", "summary": "Start a CSV import", "tags": [ "File imports" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "model" ], "description": "Step 1 of 4. Returns a short-lived uploadUrl (Azure Blob, about 60 minutes): PUT the file's bytes there with the header x-ms-blob-type: BlockBlob. Then POST .../uploaded, choose column types with .../import, and poll the upload until status is ready. Edit access; active subscription. Three uploads in progress refuse another: the 400 names them (pendingUploads, each uploadId, fileName, reportId and reportName); the uploader may cancel any of them (DELETE .../datasets/{uploadId}).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid" }, "fileName": { "type": "string", "description": "A .csv name." }, "sizeBytes": { "type": "integer", "minimum": 1 }, "tableName": { "type": "string", "description": "Entity name; defaults to the file name." } }, "required": [ "reportId", "fileName", "sizeBytes" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "description": "Follow it until ready (or failed)." }, "fileName": { "type": "string" }, "tableName": { "type": "string" }, "rowCount": { "type": [ "integer", "null" ] }, "rowsProcessed": { "type": [ "integer", "null" ] }, "progress": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "connectionId": { "type": [ "integer", "null" ], "description": "Set when ready: the queryable file connection." }, "preview": { "type": [ "object", "null" ], "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" } } } }, "rows": { "type": "array", "items": { "type": "array", "items": {} } } } }, "firstSpellings": { "type": [ "object", "null" ], "additionalProperties": { "type": "object", "properties": { "spellings": { "type": "integer" }, "rows": { "type": "integer" } } }, "description": "Set when ready: per column, the later spellings stored as an earlier one (Unity's text rule treats them as equal) and the rows they were in." }, "message": { "type": [ "string", "null" ] }, "uploadUrl": { "type": "string" }, "maxBytes": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } }, "get": { "operationId": "dataset_files_report_uploads_get", "summary": "List a report's unfinished CSV imports", "tags": [ "File imports" ], "x-unity-scope": "workspace:read", "x-unity-access": "edit", "x-unity-reach": [ "model" ], "description": "Every upload of the report not yet ready, failed or cancelled, whoever started it, oldest first. mine: you started it, so you can follow and cancel it. Edit access.", "parameters": [ { "name": "reportId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploads": { "type": "array", "items": { "type": "object", "properties": { "uploadId": { "type": "string", "format": "uuid" }, "fileName": { "type": "string" }, "status": { "type": "string" }, "rowsProcessed": { "type": [ "integer", "null" ] }, "mine": { "type": "boolean" } } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/file/datasets/limits": { "get": { "operationId": "dataset_files_upload_limits_get", "summary": "Read CSV import limits", "tags": [ "File imports" ], "x-unity-scope": "workspace:read", "x-unity-access": "account", "x-unity-reach": [ "model" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "maxBytes": { "type": "integer" }, "maxColumns": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/file/datasets/{dataset_id}": { "delete": { "operationId": "dataset_files_cancel_upload_delete", "summary": "Cancel a CSV import", "tags": [ "File imports" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "model" ], "description": "Before it is ready; afterwards delete its connection.", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } }, "get": { "operationId": "dataset_files_upload_status_get", "summary": "Follow a CSV import", "tags": [ "File imports" ], "x-unity-scope": "workspace:read", "x-unity-access": "edit", "x-unity-reach": [ "model" ], "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "description": "Follow it until ready (or failed)." }, "fileName": { "type": "string" }, "tableName": { "type": "string" }, "rowCount": { "type": [ "integer", "null" ] }, "rowsProcessed": { "type": [ "integer", "null" ] }, "progress": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "connectionId": { "type": [ "integer", "null" ], "description": "Set when ready: the queryable file connection." }, "preview": { "type": [ "object", "null" ], "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" } } } }, "rows": { "type": "array", "items": { "type": "array", "items": {} } } } }, "firstSpellings": { "type": [ "object", "null" ], "additionalProperties": { "type": "object", "properties": { "spellings": { "type": "integer" }, "rows": { "type": "integer" } } }, "description": "Set when ready: per column, the later spellings stored as an earlier one (Unity's text rule treats them as equal) and the rows they were in." }, "message": { "type": [ "string", "null" ] } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/file/datasets/{dataset_id}/import": { "post": { "operationId": "dataset_files_import_dataset_post", "summary": "Import a CSV with column types", "tags": [ "File imports" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "model" ], "description": "Step 3. One type per preview column; the import continues in the background (poll to ready).", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "columnMappings": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "string", "integer", "decimal", "boolean", "date", "datetime", "date_us", "date_eu", "datetime_us", "datetime_eu" ] }, "description": "Preview column name to type." } }, "required": [ "columnMappings" ] }, "example": { "columnMappings": { "date": "date", "amount": "decimal", "category": "string" } } } } }, "responses": { "202": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "description": "Follow it until ready (or failed)." }, "fileName": { "type": "string" }, "tableName": { "type": "string" }, "rowCount": { "type": [ "integer", "null" ] }, "rowsProcessed": { "type": [ "integer", "null" ] }, "progress": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "connectionId": { "type": [ "integer", "null" ], "description": "Set when ready: the queryable file connection." }, "preview": { "type": [ "object", "null" ], "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" } } } }, "rows": { "type": "array", "items": { "type": "array", "items": {} } } } }, "firstSpellings": { "type": [ "object", "null" ], "additionalProperties": { "type": "object", "properties": { "spellings": { "type": "integer" }, "rows": { "type": "integer" } } }, "description": "Set when ready: per column, the later spellings stored as an earlier one (Unity's text rule treats them as equal) and the rows they were in." }, "message": { "type": [ "string", "null" ] } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/file/datasets/{dataset_id}/uploaded": { "post": { "operationId": "dataset_files_uploaded_post", "summary": "Confirm an uploaded CSV", "tags": [ "File imports" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "model" ], "description": "Step 2. Checks the stored size and starts profiling; poll until preview appears.", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "description": "Follow it until ready (or failed)." }, "fileName": { "type": "string" }, "tableName": { "type": "string" }, "rowCount": { "type": [ "integer", "null" ] }, "rowsProcessed": { "type": [ "integer", "null" ] }, "progress": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "connectionId": { "type": [ "integer", "null" ], "description": "Set when ready: the queryable file connection." }, "preview": { "type": [ "object", "null" ], "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" } } } }, "rows": { "type": "array", "items": { "type": "array", "items": {} } } } }, "firstSpellings": { "type": [ "object", "null" ], "additionalProperties": { "type": "object", "properties": { "spellings": { "type": "integer" }, "rows": { "type": "integer" } } }, "description": "Set when ready: per column, the later spellings stored as an earlier one (Unity's text rule treats them as equal) and the rows they were in." }, "message": { "type": [ "string", "null" ] } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/filters": { "get": { "operationId": "filters_get_filters_route_get", "summary": "Read the filters on a page", "tags": [ "Filters" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "pages" ], "description": "InspectFilters: the report's filters, and with pageId the page's and each of its native visuals', with the value that applies to you. sorts lists your own table sorts (the page's; every page's without pageId). differs is true when any of your values in this report differs from its default, or you sort a table yourself. Viewers don't see hidden filters. filterRevision is what PUT /api/filters sends back.", "parameters": [ { "name": "reportId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "pageId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The page's UUID; omit for the report's filters only." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "array", "items": { "type": "object", "properties": { "filterUid": { "type": "string" }, "scope": { "type": "string", "description": "report, page or visual." }, "target": { "type": [ "string", "null" ], "description": "null, a pageId or a visualUid." }, "fieldUid": { "type": "string" }, "field": { "type": "string", "description": "The field's current name." }, "type": { "type": "string", "description": "The field's type: measure, or string, integer, decimal, boolean, date, datetime, json or unknown." }, "kind": { "type": "string" }, "default": { "anyOf": [ { "type": "object", "properties": { "values": { "type": "array", "items": { "type": [ "string", "number", "boolean", "null" ] }, "description": "The values to keep; null is (Blank)." }, "exclude": { "type": "boolean", "description": "true keeps every value except these." } }, "required": [ "values", "exclude" ], "additionalProperties": false }, { "type": "object", "properties": { "conditions": { "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "is", "isNot", "contains", "doesNotContain", "startsWith", "doesNotStartWith", "isBlank", "isNotBlank", "lessThan", "lessThanOrEqual", "greaterThan", "greaterThanOrEqual" ], "description": "Text: is, isNot, contains, doesNotContain, startsWith, doesNotStartWith, isBlank, isNotBlank. Numbers, dates and measures: is, isNot, lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual, isBlank, isNotBlank. doesNotContain, doesNotStartWith and isBlank keep (Blank), which also stands for related rows with no row in the field's table. is, isNot and comparisons treat (Blank) as DAX does, as 0, empty text or the date 1899-12-30: lessThan 1970 keeps it, isNot 0 drops it. A measure filter's is, isNot and comparisons never keep a blank measure. On a date and time, is and isNot compare the day." }, "value": { "type": [ "string", "number", "null" ] } }, "required": [ "operator", "value" ], "additionalProperties": false } }, "join": { "type": [ "string", "null" ], "enum": [ "and", "or", null ], "description": "and or or with two conditions; null with one." } }, "required": [ "conditions", "join" ], "additionalProperties": false }, { "type": "object", "properties": { "when": { "type": "string", "enum": [ "last", "this", "next" ], "description": "last and next count whole units before or after the current one; this is the current one. Weeks start on Monday." }, "count": { "type": [ "integer", "null" ], "description": "1 to 1000 with last and next; null with this." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "quarter", "year" ] } }, "required": [ "when", "count", "unit" ], "additionalProperties": false }, { "type": "null" } ], "description": "The filter's value for its kind; null shows all." }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "label": { "type": "string" }, "value": { "description": "The value that applies to you: yours, or the default." }, "yours": { "type": "boolean", "description": "true when the value is your own." }, "broken": { "type": "string", "description": "Present instead of the design for a filter that can't be read (an older form, a field that is gone, a default its field no longer takes); remove it." } }, "description": "A filter as InspectFilters lists it." } }, "sorts": { "type": "array", "items": { "type": "object", "properties": { "visualUid": { "type": "string", "description": "The table's visualUid." }, "output": { "type": "string", "description": "An output of the table's query." }, "direction": { "type": [ "string", "null" ], "description": "asc or desc; null returns the table to its own order." } }, "required": [ "visualUid", "output", "direction" ], "description": "Your own sort of a table." } }, "differs": { "type": "boolean" }, "filterRevision": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } }, "put": { "operationId": "filters_update_filters_route_put", "summary": "Change filters for everyone", "tags": [ "Filters" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_view", "x-unity-reach": [ "pages" ], "description": "UpdateFilters: add (filterUid null), change or remove filters (report design; Edit access, and report Edit for report scope). A filter's field and scope are fixed. A new default keeps the values people set themselves; changing kind, locked or hidden, or removing a filter, deletes everyone's values for it. filterRevision is the one GET /api/filters returned; if the filters changed since, nothing is saved (409 filter_conflict).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid" }, "filters": { "type": "array", "items": { "type": "object", "properties": { "filterUid": { "type": [ "string", "null" ], "description": "Null adds a filter; a filterUid changes that filter." }, "fieldUid": { "type": "string", "description": "The model field (InspectDataModel). Fixed once created." }, "kind": { "type": "string", "enum": [ "basic", "advanced", "relativeDate" ], "description": "basic: a checklist of values; advanced: one or two conditions; relativeDate: last, this or next N days, weeks, months, quarters or years, today in UTC. A measure takes advanced." }, "default": { "anyOf": [ { "type": "object", "properties": { "values": { "type": "array", "items": { "type": [ "string", "number", "boolean", "null" ] }, "description": "The values to keep; null is (Blank)." }, "exclude": { "type": "boolean", "description": "true keeps every value except these." } }, "required": [ "values", "exclude" ], "additionalProperties": false }, { "type": "object", "properties": { "conditions": { "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "is", "isNot", "contains", "doesNotContain", "startsWith", "doesNotStartWith", "isBlank", "isNotBlank", "lessThan", "lessThanOrEqual", "greaterThan", "greaterThanOrEqual" ], "description": "Text: is, isNot, contains, doesNotContain, startsWith, doesNotStartWith, isBlank, isNotBlank. Numbers, dates and measures: is, isNot, lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual, isBlank, isNotBlank. doesNotContain, doesNotStartWith and isBlank keep (Blank), which also stands for related rows with no row in the field's table. is, isNot and comparisons treat (Blank) as DAX does, as 0, empty text or the date 1899-12-30: lessThan 1970 keeps it, isNot 0 drops it. A measure filter's is, isNot and comparisons never keep a blank measure. On a date and time, is and isNot compare the day." }, "value": { "type": [ "string", "number", "null" ] } }, "required": [ "operator", "value" ], "additionalProperties": false } }, "join": { "type": [ "string", "null" ], "enum": [ "and", "or", null ], "description": "and or or with two conditions; null with one." } }, "required": [ "conditions", "join" ], "additionalProperties": false }, { "type": "object", "properties": { "when": { "type": "string", "enum": [ "last", "this", "next" ], "description": "last and next count whole units before or after the current one; this is the current one. Weeks start on Monday." }, "count": { "type": [ "integer", "null" ], "description": "1 to 1000 with last and next; null with this." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "quarter", "year" ] } }, "required": [ "when", "count", "unit" ], "additionalProperties": false }, { "type": "null" } ], "description": "The filter's value for its kind; null shows all." }, "locked": { "type": "boolean", "description": "Viewers can't change it." }, "hidden": { "type": "boolean", "description": "It applies, but viewers don't see it." }, "label": { "type": [ "string", "null" ], "description": "Null uses the field's name." }, "scope": { "type": "string", "enum": [ "report", "page", "visual" ], "description": "report (target null), page (target: the page's pageId) or visual (target: visualUid). Fixed once created." }, "target": { "type": [ "string", "null" ] } }, "required": [ "filterUid", "fieldUid", "kind", "default", "locked", "hidden", "label", "scope", "target" ], "additionalProperties": false } }, "remove": { "type": "array", "items": { "type": "string", "description": "A filterUid." } }, "filterRevision": { "type": "integer" } }, "required": [ "reportId", "filters", "remove", "filterRevision" ] }, "example": { "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82", "filterRevision": 12, "remove": [], "filters": [ { "filterUid": null, "scope": "page", "target": "678ae2f0-1469-489e-ae28-b729a0000e51", "fieldUid": "6f1d2c9a8b7e4f30a1c5d9e2b4f7a8c1", "kind": "basic", "default": { "values": [ "Dining", "Groceries" ], "exclude": false }, "locked": false, "hidden": false, "label": null } ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "array", "items": { "type": "object", "properties": { "filterUid": { "type": "string" }, "scope": { "type": "string", "description": "report, page or visual." }, "target": { "type": [ "string", "null" ], "description": "null, a pageId or a visualUid." }, "fieldUid": { "type": "string" }, "field": { "type": "string", "description": "The field's current name." }, "type": { "type": "string", "description": "The field's type: measure, or string, integer, decimal, boolean, date, datetime, json or unknown." }, "kind": { "type": "string" }, "default": { "anyOf": [ { "type": "object", "properties": { "values": { "type": "array", "items": { "type": [ "string", "number", "boolean", "null" ] }, "description": "The values to keep; null is (Blank)." }, "exclude": { "type": "boolean", "description": "true keeps every value except these." } }, "required": [ "values", "exclude" ], "additionalProperties": false }, { "type": "object", "properties": { "conditions": { "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "is", "isNot", "contains", "doesNotContain", "startsWith", "doesNotStartWith", "isBlank", "isNotBlank", "lessThan", "lessThanOrEqual", "greaterThan", "greaterThanOrEqual" ], "description": "Text: is, isNot, contains, doesNotContain, startsWith, doesNotStartWith, isBlank, isNotBlank. Numbers, dates and measures: is, isNot, lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual, isBlank, isNotBlank. doesNotContain, doesNotStartWith and isBlank keep (Blank), which also stands for related rows with no row in the field's table. is, isNot and comparisons treat (Blank) as DAX does, as 0, empty text or the date 1899-12-30: lessThan 1970 keeps it, isNot 0 drops it. A measure filter's is, isNot and comparisons never keep a blank measure. On a date and time, is and isNot compare the day." }, "value": { "type": [ "string", "number", "null" ] } }, "required": [ "operator", "value" ], "additionalProperties": false } }, "join": { "type": [ "string", "null" ], "enum": [ "and", "or", null ], "description": "and or or with two conditions; null with one." } }, "required": [ "conditions", "join" ], "additionalProperties": false }, { "type": "object", "properties": { "when": { "type": "string", "enum": [ "last", "this", "next" ], "description": "last and next count whole units before or after the current one; this is the current one. Weeks start on Monday." }, "count": { "type": [ "integer", "null" ], "description": "1 to 1000 with last and next; null with this." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "quarter", "year" ] } }, "required": [ "when", "count", "unit" ], "additionalProperties": false }, { "type": "null" } ], "description": "The filter's value for its kind; null shows all." }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "label": { "type": "string" }, "value": { "description": "The value that applies to you: yours, or the default." }, "yours": { "type": "boolean", "description": "true when the value is your own." }, "broken": { "type": "string", "description": "Present instead of the design for a filter that can't be read (an older form, a field that is gone, a default its field no longer takes); remove it." } }, "description": "A filter as InspectFilters lists it." } }, "removed": { "type": "array", "items": { "type": "string" } }, "filterRevision": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/filters/values": { "get": { "operationId": "filters_filter_values_route_get", "summary": "List the values a filter can choose", "tags": [ "Filters" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "pages" ], "description": "A field's members on a page (and visual), under your filters there without the filter being edited (filterUid). (Blank) is null. A measure answers manualEntryOnly: true with no values. Report access; with access to the page only, the members of a filter you see on it (filterUid), as your page reads them.", "parameters": [ { "name": "reportId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "pageId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The page's UUID." }, { "name": "fieldUid", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "visualUid", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filterUid", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The filter being edited." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search text (contains, ignoring case)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 60 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "fieldUid": { "type": "string" }, "field": { "type": "string" }, "values": { "type": "array", "items": {} }, "manualEntryOnly": { "type": "boolean" }, "offset": { "type": "integer" }, "limit": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextOffset": { "type": [ "integer", "null" ] } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/html/pages/{page_uid}": { "get": { "operationId": "html_reports_page_read_get", "summary": "Read an HTML page", "tags": [ "HTML pages" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "pages" ], "description": "One page's source, registered datasets and visuals, filters and its version (`version`), which changes to it must send as baseVersion.", "parameters": [ { "name": "page_uid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The HTML page UUID." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Report ID." }, "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "pageId": { "type": "string", "format": "uuid", "description": "The page (single-page projection)." }, "name": { "type": "string", "description": "Report name." }, "version": { "type": "integer", "description": "This page's version: send it as baseVersion (for a report-wide read, the highest page version)." }, "pageVersions": { "type": "object", "description": "{pageUid: version} for every page in the document." }, "revisionScope": { "type": "string", "enum": [ "page" ] }, "accessLevel": { "type": "string" }, "document": { "type": "object", "properties": { "formatVersion": { "type": "integer" }, "name": { "type": "string" }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "HTML page UUID." }, "name": { "type": "string" }, "html": { "type": "string" }, "data": { "type": "array", "items": { "type": "object" }, "description": "Registered datasets." }, "visuals": { "type": "array", "items": { "type": "object" }, "description": "Registered visuals." } } } } } }, "nativePages": { "type": "array", "items": { "type": "object", "properties": { "PageID": { "type": "integer" }, "PageUID": { "type": "string", "format": "uuid" }, "PageName": { "type": "string" }, "Hidden": { "type": "boolean" } } } }, "feedback": { "type": "object" }, "updatedAt": { "type": [ "string", "null" ] }, "scope": { "type": "string", "enum": [ "pages" ], "description": "Present for a page-only reader (page grants, no report access): the page is returned without queries, filters or renderer feedback." }, "dataContext": { "type": "string", "description": "An opaque fingerprint of the page's data definitions and the filters as they apply to you. Data responses and renderer feedback repeat it." } }, "description": "An HTML page (or, for a report-wide read, every page the caller can see) with its version." } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/html/pages/{page_uid}/assets/{asset_id}/content": { "get": { "operationId": "html_reports_page_asset_get", "summary": "Read an image the page uses", "tags": [ "HTML pages" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "files", "pages" ], "description": "The bytes of an asset the page's current content references as `unity-asset:` (any part: HTML, visual HTML/CSS/script, registrations), for anyone who can open the page, including a page-only reader. An asset the page does not reference is refused, and nothing is listed: the report file library routes are for report Edit, Admin and Owner only.", "parameters": [ { "name": "page_uid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The HTML page UUID." }, { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The 64-character asset ID in a `unity-asset:` reference." } ], "responses": { "200": { "description": "Success.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/html/pages/{page_uid}/operations": { "post": { "operationId": "html_reports_page_operations_post", "summary": "Change an HTML page", "tags": [ "HTML pages" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "description": "Applies one document operation as one saved version of this page (a report version: GET /api/reports/{reportId}/versions lists it). A baseVersion older than the page's version still applies when what the operation reads or writes is the same in that version and now (element identities aside); otherwise it answers 409 revision_conflict with the page's currentVersion and the changes since, and nothing is saved. A repeated clientRequestId returns the first outcome.", "parameters": [ { "name": "page_uid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The HTML page UUID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "baseVersion": { "type": "integer" }, "operation": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "save_html", "patch_source", "register_data", "register_visual", "remove_data", "remove_visual", "set_data_filters", "batch", "element_ops" ] }, "pageId": { "type": "string", "format": "uuid", "description": "The HTML page (its UUID). Page routes default it to the page in the path." }, "html": { "type": "string", "description": "save_html: the page document." }, "visualId": { "type": "string", "description": "patch_source: a registered visual, or omit for page HTML." }, "part": { "type": "string", "description": "patch_source: html, css or script. element_ops: html (page HTML) or visual//html." }, "ops": { "type": "array", "items": { "type": "object" }, "description": "element_ops: 1-100 ops applied in order to `part` (setText, setAttribute, setStyle, move, remove, insert, duplicate, replaceElement; each names a data-unity-id as `uid`, `parentUid` or `beforeUid`). A refusal answers 422 edit_in_code or invalid, or 409 not_found, and saves nothing." }, "edits": { "type": "array", "items": { "type": "object", "properties": { "find": { "type": "string" }, "replace": { "type": "string" }, "expectedMatches": { "type": "integer" } } }, "description": "patch_source: exact replacements; every match count must agree or nothing is saved." }, "definition": { "type": "object", "description": "register_data: {id, title, query, paging, filters}, query a visual query (the definition schema's query: groups and values naming model fields by fieldUid) and filters its dataset filters (the filter object; locked is ignored: a dataset filter is fixed); register_visual: {id, title, dataIds, html, css, script}." }, "id": { "type": "string", "description": "remove_*, set_data_filters: the dataset or visual ID." }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/Filter" }, "description": "set_data_filters: the dataset's filters (locked is ignored)." }, "operations": { "type": "array", "items": { "type": "object" }, "description": "batch: operations applied together (all on one page)." } }, "required": [ "kind" ], "description": "One atomic change to one HTML page. The html-authoring guide (GET /api/agent/documentation?topic=html-authoring) describes each kind, the renderer API (unity.bind, unity.query) and examples." }, "label": { "type": "string", "description": "History label." }, "clientRequestId": { "type": "string", "description": "A UUID or short string naming this command: a retry with the same ID and body answers with the original outcome instead of saving twice." } }, "required": [ "baseVersion", "operation" ] }, "example": { "baseVersion": 1, "label": "Headline", "operation": { "kind": "patch_source", "part": "html", "edits": [ { "find": "Your data.
A different perspective.", "replace": "Spending at a glance", "expectedMatches": 1 } ] } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Report ID." }, "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "pageId": { "type": "string", "format": "uuid", "description": "The page (single-page projection)." }, "name": { "type": "string", "description": "Report name." }, "version": { "type": "integer", "description": "This page's version: send it as baseVersion (for a report-wide read, the highest page version)." }, "pageVersions": { "type": "object", "description": "{pageUid: version} for every page in the document." }, "revisionScope": { "type": "string", "enum": [ "page" ] }, "accessLevel": { "type": "string" }, "document": { "type": "object", "properties": { "formatVersion": { "type": "integer" }, "name": { "type": "string" }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "HTML page UUID." }, "name": { "type": "string" }, "html": { "type": "string" }, "data": { "type": "array", "items": { "type": "object" }, "description": "Registered datasets." }, "visuals": { "type": "array", "items": { "type": "object" }, "description": "Registered visuals." } } } } } }, "nativePages": { "type": "array", "items": { "type": "object", "properties": { "PageID": { "type": "integer" }, "PageUID": { "type": "string", "format": "uuid" }, "PageName": { "type": "string" }, "Hidden": { "type": "boolean" } } } }, "feedback": { "type": "object" }, "updatedAt": { "type": [ "string", "null" ] }, "scope": { "type": "string", "enum": [ "pages" ], "description": "Present for a page-only reader (page grants, no report access): the page is returned without queries, filters or renderer feedback." }, "dataContext": { "type": "string", "description": "An opaque fingerprint of the page's data definitions and the filters as they apply to you. Data responses and renderer feedback repeat it." }, "receipt": { "type": "object", "description": "Receipt: {resourceType: 'html', label, mutation, change: {before: {pageUid}, after: {pageUid, version}}, pageVersion, changedPageIds, verificationKeys}." }, "changedElements": { "type": "array", "items": { "type": "string" }, "description": "element_ops: the uids written." } }, "description": "The page as saved and the change receipt." } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" }, "413": { "$ref": "#/components/responses/E413" }, "422": { "$ref": "#/components/responses/E422" } } } }, "/api/html/pages/{page_uid}/script-save": { "post": { "operationId": "html_reports_page_script_save_post", "summary": "Save text from a page's own script", "tags": [ "HTML pages" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_content", "x-unity-reach": [ "pages" ], "description": "What `unity.save(element, text)` in an HTML page sends. Writes `text` as plain text into the element whose `data-unity-id` is `uid`, which the page's editors marked `data-unity-writable` (a text-only element), as one new attributed version of the page (ActorKind `page_script`, the label 'Saved text from the page'); every viewer sees it through the live feed. Needs Edit content or above on the page: report Admin/Owner/Edit, a page Edit or Edit content grant, or a report share at Edit content (HTML pages open to everyone). A person who can only view is refused `view_only`; public links have no save route. At most 20,000 characters, 30 saves a minute per person per page. Refusals: 403 `view_only` / `no_access` / `page_unavailable`, 422 `not_writable` (no marker, not a text-only element, unknown uid, or the page has no element identities) / `too_long` / `invalid_text` (a report image reference), 409 `page_held` (another person is editing: {holder}) / `changed` (the element no longer holds previousText: someone changed it; {currentVersion}), 429 `rate_limited` ({retryAfter}, Retry-After). Changes to other elements never refuse it. A repeated clientRequestId answers the first outcome.", "parameters": [ { "name": "page_uid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The HTML page UUID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "uid": { "type": "string", "description": "The element's data-unity-id." }, "text": { "type": "string", "description": "Plain text, up to 20,000 characters." }, "previousText": { "type": "string", "description": "The element's text as the saver's page last applied it (after its own earlier saves; not a change held back while they type)." }, "clientRequestId": { "type": "string", "description": "A UUID or short string naming this command: a retry with the same ID and body answers with the original outcome instead of saving twice." } }, "required": [ "uid", "text", "previousText", "clientRequestId" ] }, "example": { "uid": "k3m9xq", "text": "Approved", "previousText": "Pending", "clientRequestId": "a-new-id-per-save" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "saved": { "type": "boolean" }, "pageId": { "type": "string", "format": "uuid" }, "uid": { "type": "string" }, "version": { "type": "integer", "description": "The page version holding the text." }, "applied": { "type": "boolean", "description": "False when the element already held exactly this text (no new version)." } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/html/reports/{report_id}": { "get": { "operationId": "html_reports_read_get", "summary": "Read the HTML pages of a report", "tags": [ "HTML pages" ], "x-unity-scope": "workspace:read", "x-unity-access": "view", "x-unity-reach": [ "pages" ], "description": "Every HTML page the caller can see, with `pageVersions` ({pageUid: version}).", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Report ID." }, "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "pageId": { "type": "string", "format": "uuid", "description": "The page (single-page projection)." }, "name": { "type": "string", "description": "Report name." }, "version": { "type": "integer", "description": "This page's version: send it as baseVersion (for a report-wide read, the highest page version)." }, "pageVersions": { "type": "object", "description": "{pageUid: version} for every page in the document." }, "revisionScope": { "type": "string", "enum": [ "page" ] }, "accessLevel": { "type": "string" }, "document": { "type": "object", "properties": { "formatVersion": { "type": "integer" }, "name": { "type": "string" }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "HTML page UUID." }, "name": { "type": "string" }, "html": { "type": "string" }, "data": { "type": "array", "items": { "type": "object" }, "description": "Registered datasets." }, "visuals": { "type": "array", "items": { "type": "object" }, "description": "Registered visuals." } } } } } }, "nativePages": { "type": "array", "items": { "type": "object", "properties": { "PageID": { "type": "integer" }, "PageUID": { "type": "string", "format": "uuid" }, "PageName": { "type": "string" }, "Hidden": { "type": "boolean" } } } }, "feedback": { "type": "object" }, "updatedAt": { "type": [ "string", "null" ] }, "scope": { "type": "string", "enum": [ "pages" ], "description": "Present for a page-only reader (page grants, no report access): the page is returned without queries, filters or renderer feedback." }, "dataContext": { "type": "string", "description": "An opaque fingerprint of the page's data definitions and the filters as they apply to you. Data responses and renderer feedback repeat it." } }, "description": "An HTML page (or, for a report-wide read, every page the caller can see) with its version." } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/html/reports/{report_id}/pages/{page_id}/data": { "get": { "operationId": "html_reports_results_get", "summary": "Read an HTML page's data", "tags": [ "HTML pages" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "model", "pages" ], "description": "Reads the page's registered visual queries with saved and interactive filters and returns their results: columns, rows, records, outputs and generatedSql. A dataset saved as SQL answers code legacy_sql. The browser renderer calls it; an agent previews pages with the PreviewPage tool.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The HTML page UUID." }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" }, "description": "JSON runtime state, at most 16,000 characters: a click (interaction: {visualId, dataId, fields: [{column, value}]}, each column a group output of that dataset's query; Unity builds its filters from the stored query), a table window, targets." }, { "name": "target", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One dataset or visual ID." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer" }, "context": { "type": "object" }, "results": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/api/html/reports/{report_id}/pages/{page_id}/data-stream": { "get": { "operationId": "html_reports_stream_results_get", "summary": "Stream an HTML page's data", "tags": [ "HTML pages" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "model", "pages" ], "description": "NDJSON: {context, keys}, then {results} as datasets finish, {jobs} for reads continuing as read jobs, then {done: true}.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/x-ndjson": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/html/reports/{report_id}/query": { "post": { "operationId": "html_reports_query_post", "summary": "Query data for HTML authoring", "tags": [ "HTML pages" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "model" ], "description": "Reads a visual query under the report's filters (and the page's, with a pageId) as they apply to you and returns a sample with its outputs and generatedSql, to design datasets. Edit access.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "object", "description": "A visual query, as a dataset takes it." }, "pageId": { "type": "string", "format": "uuid" }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/Filter" }, "description": "Dataset filters for this query." } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/instructions": { "post": { "operationId": "report_save_instructions_post", "summary": "Save report instructions", "tags": [ "Reports" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "report" ], "description": "Replaces the report's instructions. An empty string clears them. Edit access.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "instructions": { "type": "string", "maxLength": 1500, "description": "At most 1,500 characters." } }, "required": [ "reportId", "instructions" ] }, "example": { "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82", "instructions": "Amounts are USD. Fiscal year starts in May." } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/instructions/{report_id}": { "get": { "operationId": "report_get_instructions_get", "summary": "Read report instructions", "tags": [ "Reports" ], "x-unity-scope": "workspace:read", "x-unity-access": "view", "x-unity-reach": [ "report" ], "description": "The report's lasting guidance to the assistant (terminology, units, conventions).", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "type": "string" } } }, "example": { "instructions": "Amounts are USD. Fiscal year starts in May." } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/lineGraphs/update": { "put": { "operationId": "visuals_update_linegraph_put", "summary": "Update a line chart", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/update.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/linegraphs/data": { "get": { "operationId": "visual_compat_data_linegraphs_get", "summary": "Read a chart preset's data", "tags": [ "Chart preset routes (compatibility)" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "model", "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/reports/{report_id}/visual-data.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/linegraphs/delete": { "delete": { "operationId": "visual_compat_delete_linegraphs_delete", "summary": "Delete a chart preset", "tags": [ "Chart preset routes (compatibility)" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/delete.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/matrices/data": { "get": { "operationId": "visuals_get_matrix_data_get", "summary": "Read a matrix's data", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "model", "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/reports/{report_id}/visual-data.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/matrices/delete": { "delete": { "operationId": "visuals_delete_matrix_delete", "summary": "Delete a matrix", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/delete.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/matrices/update": { "put": { "operationId": "visuals_update_matrix_put", "summary": "Update a matrix", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/update.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/my-view": { "put": { "operationId": "filters_update_my_view_route_put", "summary": "Set your own view", "tags": [ "Filters" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_view", "x-unity-reach": [ "pages" ], "description": "UpdateMyView: your own filter values and table sorts in this report; only you see them, and they're kept between visits. Each value replaces yours for that filter (null shows all); each sort replaces yours for that table (direction null returns it to the table's own order, its query's sort); reset true first returns all of yours to the defaults. Locked and hidden filters need Edit access.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid" }, "values": { "type": "array", "items": { "type": "object", "properties": { "filterUid": { "type": "string" }, "value": { "anyOf": [ { "type": "object", "properties": { "values": { "type": "array", "items": { "type": [ "string", "number", "boolean", "null" ] }, "description": "The values to keep; null is (Blank)." }, "exclude": { "type": "boolean", "description": "true keeps every value except these." } }, "required": [ "values", "exclude" ], "additionalProperties": false }, { "type": "object", "properties": { "conditions": { "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "is", "isNot", "contains", "doesNotContain", "startsWith", "doesNotStartWith", "isBlank", "isNotBlank", "lessThan", "lessThanOrEqual", "greaterThan", "greaterThanOrEqual" ], "description": "Text: is, isNot, contains, doesNotContain, startsWith, doesNotStartWith, isBlank, isNotBlank. Numbers, dates and measures: is, isNot, lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual, isBlank, isNotBlank. doesNotContain, doesNotStartWith and isBlank keep (Blank), which also stands for related rows with no row in the field's table. is, isNot and comparisons treat (Blank) as DAX does, as 0, empty text or the date 1899-12-30: lessThan 1970 keeps it, isNot 0 drops it. A measure filter's is, isNot and comparisons never keep a blank measure. On a date and time, is and isNot compare the day." }, "value": { "type": [ "string", "number", "null" ] } }, "required": [ "operator", "value" ], "additionalProperties": false } }, "join": { "type": [ "string", "null" ], "enum": [ "and", "or", null ], "description": "and or or with two conditions; null with one." } }, "required": [ "conditions", "join" ], "additionalProperties": false }, { "type": "object", "properties": { "when": { "type": "string", "enum": [ "last", "this", "next" ], "description": "last and next count whole units before or after the current one; this is the current one. Weeks start on Monday." }, "count": { "type": [ "integer", "null" ], "description": "1 to 1000 with last and next; null with this." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "quarter", "year" ] } }, "required": [ "when", "count", "unit" ], "additionalProperties": false }, { "type": "null" } ], "description": "The filter's value for its kind; null shows all." } }, "required": [ "filterUid", "value" ] } }, "sorts": { "type": "array", "items": { "type": "object", "properties": { "visualUid": { "type": "string", "description": "The table's visualUid." }, "output": { "type": "string", "description": "An output of the table's query." }, "direction": { "type": [ "string", "null" ], "description": "asc or desc; null returns the table to its own order." } }, "required": [ "visualUid", "output", "direction" ], "description": "Your own sort of a table." } }, "reset": { "type": "boolean" } }, "required": [ "reportId", "values", "reset" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "array", "items": { "type": "object", "properties": { "filterUid": { "type": "string" }, "value": {}, "yours": { "type": "boolean" } } } }, "sorts": { "type": "array", "items": { "type": "object", "properties": { "visualUid": { "type": "string", "description": "The table's visualUid." }, "output": { "type": "string", "description": "An output of the table's query." }, "direction": { "type": [ "string", "null" ], "description": "asc or desc; null returns the table to its own order." } }, "required": [ "visualUid", "output", "direction" ], "description": "Your own sort of a table." } }, "differs": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/openapi.json": { "get": { "operationId": "openapi_document_get", "summary": "Read the OpenAPI document", "tags": [ "Service" ], "x-unity-scope": "workspace:read", "x-unity-access": "account", "x-unity-reach": [ "docs" ], "description": "The OpenAPI 3.1 description of this deployment's token-callable operations, with request and response schemas, examples, token scopes (x-unity-scope) and report access labels (x-unity-access). Generate a client from it, or give it to an AI agent.", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "An OpenAPI 3.1 document." } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/pages": { "get": { "operationId": "page_get_pages_get", "summary": "List a report's pages", "tags": [ "Pages" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "pages" ], "description": "Pages visible to the caller, in creation order, with both IDs and the kind of page: report (a canvas of native visuals) or html.", "parameters": [ { "name": "reportId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Report ID. Also accepted as report_id.", "x-aliases": [ "report_id" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "PageID": { "type": "integer" }, "PageUID": { "type": "string", "format": "uuid" }, "PageName": { "type": "string" }, "PageKind": { "type": "string", "enum": [ "report", "html" ] }, "ReportID": { "type": "string", "format": "uuid" }, "Hidden": { "type": "boolean" } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/pages/add": { "post": { "operationId": "page_add_page_post", "summary": "Create a page", "tags": [ "Pages" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "pages" ], "description": "A canvas page (pageKind report) for native visuals, or an HTML page (pageKind html) that starts from a blank template. Returns [page] by default, or the full receipt with includeReceipt.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "pageName": { "type": "string", "description": "Alias: newPageName." }, "pageKind": { "type": "string", "enum": [ "report", "html" ], "default": "report" }, "clientRequestId": { "type": "string", "maxLength": 64, "description": "Retry key: a UUID or any string up to 64 characters." }, "includeReceipt": { "type": "boolean", "default": false, "description": "Return the receipt instead of [page]." } }, "required": [ "reportId", "pageName" ] }, "example": { "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82", "pageName": "Spending", "clientRequestId": "page-spending-1" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Page" } }, "example": [ { "PageID": 890, "PageUID": "678AE2F0-1469-489E-AE28-B729A0000E51", "PageName": "Spending", "PageKind": "report", "PageLayout": { "kind": "report" }, "Hidden": false, "ReportID": "9af3fb53-34e2-4e88-a953-ffdecdeece82" } ] } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" } } } }, "/api/pages/delete": { "delete": { "operationId": "page_delete_page_delete", "summary": "Delete a page", "tags": [ "Pages" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "pages" ], "description": "Deletes the page with its visuals and filters. Conversations remain. The report's versions list it as a deleted page (GET /api/reports/{reportId}/versions), and restoring it brings it back with its original IDs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "pageId": { "type": "string", "description": "The page: its UUID or its numeric ID (every page parameter accepts either)." } }, "required": [ "reportId", "pageId" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "$ref": "#/components/schemas/Page" }, "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "resourceType": { "type": "string" }, "mutation": { "type": "object" }, "change": { "type": "object", "properties": { "before": { "type": "object", "properties": { "page": { "$ref": "#/components/schemas/Page" } } }, "after": { "type": "object", "properties": { "page": { "$ref": "#/components/schemas/Page" } } } } }, "canvasBounds": { "type": "object" } }, "description": "A page receipt (see Receipt). The change is one report version; restoring the version listed before it (POST /api/reports/{reportId}/versions/{version}/restore) reverses it." } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "422": { "$ref": "#/components/responses/E422" } } } }, "/api/pages/duplicate": { "post": { "operationId": "page_duplicate_page_post", "summary": "Duplicate a page", "tags": [ "Pages" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "pages" ], "description": "Copies a page's visual definitions, layout and saved filters into a new page.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "sourcePageId": { "type": "string", "description": "The page: its UUID or its numeric ID (every page parameter accepts either)." }, "newPageName": { "type": "string" }, "clientRequestId": { "type": "string", "maxLength": 64 } }, "required": [ "reportId", "sourcePageId", "newPageName" ] }, "example": { "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82", "sourcePageId": 890, "newPageName": "Spending copy" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "$ref": "#/components/schemas/Page" }, "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "resourceType": { "type": "string" }, "mutation": { "type": "object" }, "change": { "type": "object", "properties": { "before": { "type": "object", "properties": { "page": { "$ref": "#/components/schemas/Page" } } }, "after": { "type": "object", "properties": { "page": { "$ref": "#/components/schemas/Page" } } } } }, "canvasBounds": { "type": "object" }, "sourcePage": { "type": "object" }, "duplicatedVisuals": { "type": "array", "items": { "type": "object" } }, "lockedViewport": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" } } } }, "/api/pages/update": { "put": { "operationId": "page_update_page_put", "summary": "Rename a page", "tags": [ "Pages" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "pages" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "pageId": { "type": "string", "description": "The page: its UUID or its numeric ID (every page parameter accepts either)." }, "pageName": { "type": "string", "description": "Alias: newPageName." } }, "required": [ "reportId", "pageId", "pageName" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "$ref": "#/components/schemas/Page" }, "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "resourceType": { "type": "string" }, "mutation": { "type": "object" }, "change": { "type": "object", "properties": { "before": { "type": "object", "properties": { "page": { "$ref": "#/components/schemas/Page" } } }, "after": { "type": "object", "properties": { "page": { "$ref": "#/components/schemas/Page" } } } } }, "canvasBounds": { "type": "object" } }, "description": "A page receipt (see Receipt). The change is one report version; restoring the version listed before it (POST /api/reports/{reportId}/versions/{version}/restore) reverses it." } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "422": { "$ref": "#/components/responses/E422" } } } }, "/api/pages/viewport-settings": { "get": { "operationId": "page_get_page_viewport_settings_get", "summary": "Read a page's canvas settings", "tags": [ "Pages" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "pages" ], "parameters": [ { "name": "reportId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Report ID. Also accepted as report_id.", "x-aliases": [ "report_id" ] }, { "name": "pageId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The page: its UUID or its numeric ID (every page parameter accepts either). Also accepted as page_id.", "x-aliases": [ "page_id" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "pageId": { "type": "integer" }, "lockedViewport": { "$ref": "#/components/schemas/Viewport" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" } } }, "put": { "operationId": "page_update_page_viewport_settings_put", "summary": "Change a page's canvas size and colors", "tags": [ "Pages" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "pages" ], "description": "Canvas pages have a fixed logical size (default 1280x720); visuals do not grow it. Send lockedViewport or its fields at the top level. An HTML page fills the window and has no canvas size: viewport fields on one are refused (422).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "pageId": { "type": "string", "description": "The page: its UUID or its numeric ID (every page parameter accepts either)." }, "lockedViewport": { "$ref": "#/components/schemas/Viewport" } }, "required": [ "reportId", "pageId" ] }, "example": { "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82", "pageId": 890, "lockedViewport": { "width": 1600, "height": 900, "backgroundColor": "#ffffff" } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "$ref": "#/components/schemas/Page" }, "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "resourceType": { "type": "string" }, "mutation": { "type": "object" }, "change": { "type": "object", "properties": { "before": { "type": "object", "properties": { "page": { "$ref": "#/components/schemas/Page" } } }, "after": { "type": "object", "properties": { "page": { "$ref": "#/components/schemas/Page" } } } } }, "canvasBounds": { "type": "object" }, "status": { "type": "string" }, "pageId": { "type": "integer" }, "pageLayout": { "type": "object" }, "lockedViewport": { "$ref": "#/components/schemas/Viewport" } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "422": { "$ref": "#/components/responses/E422" } } } }, "/api/pages/visual-shell-manifest": { "get": { "operationId": "page_get_page_visual_shell_manifest_get", "summary": "Read a page's visual layout", "tags": [ "Pages" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "model", "pages" ], "description": "Every visual on a page with its kind, title, position and connection, without data. The browser draws placeholders from it; read data with POST /api/reports/{report_id}/visual-data.", "parameters": [ { "name": "reportId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Report ID. Also accepted as report_id.", "x-aliases": [ "report_id" ] }, { "name": "pageId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The page: its UUID or its numeric ID (every page parameter accepts either). Also accepted as page_id.", "x-aliases": [ "page_id" ] }, { "name": "initialPage", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "first" ] }, "description": "Read the first visible page when pageId is omitted." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "visuals": { "type": "array", "items": { "type": "object" } }, "connections": { "type": "array", "items": { "type": "object" } }, "shellCounts": { "type": "object" }, "page": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "422": { "$ref": "#/components/responses/E422" } } } }, "/api/pages/{page_uid}/hold": { "get": { "operationId": "page_layer_hold_state_get", "summary": "Read the leases on a page and who is on it", "tags": [ "Live viewing and editing presence" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "pages" ], "description": "`hold` is an HTML page's editing session (null when free or native). `leases` are the live element leases of a native page (a chart is leased while someone drags or resizes it, has unsaved edits in its edit drawer, or their assistant is changing it, and never more than 5 minutes after it was taken or last written; the caller's own are flagged `mine`). `presence` lists the people on the page and what each has selected. `granularity` is `page` (HTML: one editor at a time) or `element` (native: everyone edits at once; a chart is protected for about 10 s after the activity stops). The same for HTML and native pages.", "parameters": [ { "name": "page_uid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The HTML page UUID." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "granularity": { "type": "string", "enum": [ "page", "element" ] }, "hold": { "type": [ "object", "null" ], "properties": { "pageUid": { "type": "string", "format": "uuid" }, "target": { "type": "string", "description": "`page` for an HTML page's session; `visual:` for a native page's element lease." }, "mode": { "type": "string", "enum": [ "session", "lease", "oneshot" ], "description": "`session`: an HTML page's editing session (45 s from the last renewal, 10 minutes from the last write); `lease`: a chart on a native page (10 s from the last activity); `oneshot`: held for one write." }, "holdId": { "type": "string", "format": "uuid", "description": "Only the holder sees it: send it with every renew, leave and answer (a stale one answers 409 hold_lost)." }, "holder": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "since": { "type": "string" }, "kinds": { "type": "array", "items": { "type": "string" }, "description": "Who is acting under the hold." }, "mine": { "type": "boolean", "description": "The caller is the holder." }, "expiresAt": { "type": "string", "description": "The hold lapses then unless a participant renews." }, "participants": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "browser", "assistant", "external", "page_script" ] }, "id": { "type": "string" } } }, "description": "The holder's live participants (holder only)." }, "takeoverRequested": { "type": "boolean" }, "takeoverRequestedBy": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "takeoverDeadline": { "type": [ "string", "null" ], "description": "Server time at which an unanswered request is granted." } }, "description": "One person's lease on a target of a page: an HTML page's editing session, or a chart of a native page. A participant (a browser tab, an assistant run, an API caller) is live for the mode's window after its last renewal (see `mode`); the lease ends when none is live." }, "leases": { "type": "array", "items": { "type": "object", "properties": { "pageUid": { "type": "string", "format": "uuid" }, "target": { "type": "string", "description": "`page` for an HTML page's session; `visual:` for a native page's element lease." }, "mode": { "type": "string", "enum": [ "session", "lease", "oneshot" ], "description": "`session`: an HTML page's editing session (45 s from the last renewal, 10 minutes from the last write); `lease`: a chart on a native page (10 s from the last activity); `oneshot`: held for one write." }, "holdId": { "type": "string", "format": "uuid", "description": "Only the holder sees it: send it with every renew, leave and answer (a stale one answers 409 hold_lost)." }, "holder": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "since": { "type": "string" }, "kinds": { "type": "array", "items": { "type": "string" }, "description": "Who is acting under the hold." }, "mine": { "type": "boolean", "description": "The caller is the holder." }, "expiresAt": { "type": "string", "description": "The hold lapses then unless a participant renews." }, "participants": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "browser", "assistant", "external", "page_script" ] }, "id": { "type": "string" } } }, "description": "The holder's live participants (holder only)." }, "takeoverRequested": { "type": "boolean" }, "takeoverRequestedBy": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "takeoverDeadline": { "type": [ "string", "null" ], "description": "Server time at which an unanswered request is granted." } }, "description": "One person's lease on a target of a page: an HTML page's editing session, or a chart of a native page. A participant (a browser tab, an assistant run, an API caller) is live for the mode's window after its last renewal (see `mode`); the lease ends when none is live." } }, "presence": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "mine": { "type": "boolean" }, "target": { "type": [ "string", "null" ] }, "editing": { "type": "boolean", "description": "The person holds a live lease on the target they selected." } }, "description": "A person on the page (one entry each, however many tabs)." } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/pages/{page_uid}/live": { "get": { "operationId": "page_layer_live_get", "summary": "Read what changed on a page since a version (live viewing)", "tags": [ "Live viewing and editing presence" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "pages" ], "description": "The net change from `after` (the version the viewer shows) to the page's head, for anyone who can view the page: in-place patches addressed by `data-unity-id`, or `rebuild: true` asking the viewer to rebuild. It never reveals what happened in between: every patch is taken from the head markup. HTML pages only (a native page answers 400: its viewers follow the report liveness poll). `rebuild: false` carries patches addressed by `data-unity-id`: `attrs` (the element's full final attributes and start tag), `text` (text-only elements) and `children` (new inner HTML), at most 40 patches and 200 KB; `rebuild: true` asks the viewer to rebuild the page (reason: styles, script, visuals, data, filters, settings, unidentified, structure, too_large, unverified or history_unavailable: the version shown isn't in the report's versions). `after` must be between 1 and the head version. Answers are cached for 30 s.", "parameters": [ { "name": "page_uid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The HTML page UUID." }, { "name": "after", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "The page version the viewer shows." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pageUid": { "type": "string", "format": "uuid" }, "fromVersion": { "type": "integer" }, "version": { "type": "integer" }, "rebuild": { "type": "boolean" }, "reason": { "type": "string", "description": "Why the viewer must rebuild; present when rebuild is true." }, "patches": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string", "enum": [ "attrs", "text", "children" ] }, "uid": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/pieCharts/update": { "put": { "operationId": "visuals_update_piechart_put", "summary": "Update a pie chart", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/update.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/piecharts/data": { "get": { "operationId": "visual_compat_data_piecharts_get", "summary": "Read a chart preset's data", "tags": [ "Chart preset routes (compatibility)" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "model", "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/reports/{report_id}/visual-data.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/piecharts/delete": { "delete": { "operationId": "visual_compat_delete_piecharts_delete", "summary": "Delete a chart preset", "tags": [ "Chart preset routes (compatibility)" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/delete.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/read-jobs/{job_id}": { "get": { "operationId": "read_jobs_poll_get", "summary": "Follow a long-running read", "tags": [ "Long-running reads" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "model", "pages" ], "description": "202 with {readJob} (state and progress) while the read runs; afterwards the original operation's own response and status, once (collecting it removes the job). Poll at least every 45 seconds or the read is abandoned. 404 read_job_gone: the job ended, was collected, or its server restarted; start the read again. A stopped read answers 503 read_stopped with its reason.\n\nRead jobs belong to the account that started them.", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "The original operation's response." } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/api/read-jobs/{job_id}/cancel": { "post": { "operationId": "read_jobs_cancel_post", "summary": "Cancel a long-running read", "tags": [ "Long-running reads" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "model", "pages" ], "description": "Stops your read; it never undoes saved changes.", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelled": { "type": "boolean", "description": "Whether a running job was found." } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/reports": { "get": { "operationId": "report_get_reports_get", "summary": "List reports", "tags": [ "Reports" ], "x-unity-scope": "workspace:read", "x-unity-access": "account", "x-unity-reach": [ "report" ], "description": "Reports the caller can open, newest first, including ones being deleted (with deletion).", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ReportSummary" } }, "example": [ { "id": "9af3fb53-34e2-4e88-a953-ffdecdeece82", "reportName": "Sales overview", "accessLevel": "Owner", "ownerFullName": "Alex Morgan", "createdAt": "2026-10-13T10:52:04.120Z", "sourceCount": 1 } ] } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/reports/create": { "post": { "operationId": "report_create_new_report_post", "summary": "Create a report", "tags": [ "Reports" ], "x-unity-scope": "workspace:write", "x-unity-access": "account", "x-unity-reach": [ "report" ], "description": "A new report owned by the caller, with one empty canvas page and one conversation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportName": { "type": "string", "minLength": 1, "maxLength": 50, "description": "1 to 50 characters." }, "clientRequestId": { "type": "string", "maxLength": 64, "description": "Optional retry key, a UUID or any string up to 64 characters. Retrying with the same key returns the first result instead of a second report." } }, "required": [ "reportName" ] }, "example": { "reportName": "Sales overview", "clientRequestId": "sales-overview-1" } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "defaultPageId": { "type": "integer", "description": "Numeric ID of the first page." }, "defaultPageUid": { "type": "string", "format": "uuid", "description": "UUID of the first page." }, "message": { "type": "string" } } }, "example": { "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82", "defaultPageId": 888, "defaultPageUid": "34432e64-7f1e-43b7-8a6c-bdb0926d0577", "message": "Report created successfully" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/reports/{report_id}": { "delete": { "operationId": "report_delete_report_delete", "summary": "Delete a report", "tags": [ "Reports" ], "x-unity-scope": "workspace:write", "x-unity-access": "owner", "x-unity-reach": [ "report" ], "description": "Owner only. Deletion runs in the background: the report disappears from content APIs at once and GET /api/reports/{report_id}/deletion follows it. An active assistant run must stop first.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deletion": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "reportName": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "failed", "succeeded" ] }, "phase": { "type": "string", "description": "What the deletion is doing now." }, "error": { "type": [ "string", "null" ] }, "requestedAt": { "type": "string", "description": "ISO 8601 UTC." }, "updatedAt": { "type": "string", "description": "ISO 8601 UTC." }, "completedAt": { "type": [ "string", "null" ], "description": "ISO 8601 UTC." } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/reports/{report_id}/assets": { "get": { "operationId": "report_files_report_assets_get", "summary": "List report images", "tags": [ "Reference files and assets" ], "x-unity-scope": "workspace:read", "x-unity-access": "edit", "x-unity-reach": [ "files" ], "description": "Images imported into the report's asset library. Report Edit, Admin or Owner only (a page displays its own images through the page's asset route).", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/reports/{report_id}/assets/{asset_id}/content": { "get": { "operationId": "report_files_asset_image_get", "summary": "Read a report image", "tags": [ "Reference files and assets" ], "x-unity-scope": "workspace:read", "x-unity-access": "edit", "x-unity-reach": [ "files" ], "description": "Report Edit, Admin or Owner only. The page that displays an image reads it through GET /api/html/pages/{pageUid}/assets/{assetId}/content, which any viewer of the page may use.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/reports/{report_id}/catalog": { "get": { "operationId": "report_get_report_catalog_get", "summary": "Search a report", "tags": [ "Reports" ], "x-unity-scope": "workspace:read", "x-unity-access": "view", "x-unity-reach": [ "model", "pages" ], "description": "Pages, visuals and connections across the whole report without loading every visual. Each page carries its id, name, kind, viewport and hidden (limited to editors and people added to it). Each visual carries its key, type, title, page, query, contract, appearance, revision and layout; detail=true adds bindings and lineage. Page with offset and nextOffset while complete is false.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "page", "visual", "connection" ], "default": "all" } }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search text over titles and queries." }, { "name": "pageId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Restrict to one page: its UUID or numeric ID." }, { "name": "currentPageId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The page the caller is looking at (marks it in the result)." }, { "name": "visualKey", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "0B5C...-visual-uuid" ] }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "true adds bindings, lineage and filters per visual." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 40, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "items": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" }, "offset": { "type": "integer" }, "complete": { "type": "boolean" }, "nextOffset": { "type": [ "integer", "null" ] }, "missingVisualKeys": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/reports/{report_id}/data-model": { "get": { "operationId": "connection_model_bp_get_report_data_model_get", "summary": "Read a report's data model", "tags": [ "Data model" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_data", "x-unity-reach": [ "model", "pages" ], "description": "Every entity, field, measure, relationship and source of the report, with the model revision that writes must send. Report SQL (POST /api/sql/execute) reads exactly this namespace.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "model": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid" }, "modelRevision": { "type": "integer" }, "snapshotVersion": { "type": "string" }, "queryDialect": { "type": "string", "description": "Report SQL dialect: duckdb." }, "primaryEntityKey": { "type": [ "string", "null" ] }, "entities": { "type": "array", "items": { "type": "object", "properties": { "entityKey": { "type": "string", "description": "Report-unique entity key: the one name report SQL reads this output by (FROM dbo_transactions), exactly, with no schema. Lowercase; case is ignored when reading. It cannot change after saving." }, "entityName": { "type": "string", "description": "Display name only; report SQL does not read an output by it." }, "entityUid": { "type": "string", "description": "Read-only identity (ent_...), assigned by Unity; sent with another entityKey, the save is refused." }, "entitySqlQuery": { "type": "string", "description": "The source query in the source's native dialect (T-SQL for SQL Server); API providers use provider query JSON." }, "sourceTableName": { "type": [ "string", "null" ], "description": "The table it reads in tables mode (dbo.transactions)." }, "description": { "type": [ "string", "null" ] }, "isPrimary": { "type": "boolean", "description": "The source's primary output." }, "primaryKeyColumns": { "type": "array", "items": { "type": "string" }, "description": "Row identity: the source's declared key; empty when it declares none." }, "entityColumns": { "type": "array", "items": { "type": "string" } }, "entityColumnsDetailed": { "type": "array", "items": { "type": "object" } } }, "required": [ "entityKey" ] } }, "relationships": { "type": "array", "items": { "type": "object", "properties": { "fromEntityKey": { "type": "string" }, "fromColumn": { "type": "string" }, "toEntityKey": { "type": "string" }, "toColumn": { "type": "string" }, "isActive": { "type": "boolean", "default": true }, "crossFilter": { "type": "string", "enum": [ "single", "both" ], "description": "single (the default when absent): filters flow from the to (key) end to the from end; both: each end filters the other." }, "relationshipName": { "type": "string", "description": "A display name." }, "relationshipId": { "type": "integer", "description": "Read-only." } }, "required": [ "fromEntityKey", "fromColumn", "toEntityKey", "toColumn" ], "description": "A filter reaches the other end as a key set, in the relationship's crossFilter direction; it never multiplies rows." } }, "dataDefinitions": { "type": "array", "items": { "type": "object", "properties": { "definitionId": { "type": "integer", "description": "Assigned by Unity. Sent back with its definitionVersion, it edits that definition (a stale version answers 409); without it, a definition is matched by aliasName and sourceEntityKey." }, "definitionVersion": { "type": "integer", "description": "Read-only; the version a definitionId edit is checked against." }, "aliasName": { "type": "string", "description": "Field or measure name used in report SQL (t.\"Total Spend\")." }, "description": { "type": "string", "description": "Business meaning: inclusions, exclusions, units." }, "sqlExpression": { "type": "string", "description": "DuckDB expression over the owning entity's columns; an aggregate for a measure. A typed measure has none." }, "measureKind": { "type": "string", "enum": [ "composite", "share", "timeComparison", "runningTotal", "rank" ], "description": "A typed measure's kind, compiled by the query builder; a SQL definition has none." }, "spec": { "type": "object", "description": "A typed measure's fields by fieldUid. composite {formula: node}, a node {measure: uid}, {number: \"1.5\"} or {add|subtract|multiply|divide: [node, node]}; share {measure, across: [uid]}; timeComparison {measure, date, shift: previousYear|previousPeriod}; runningTotal {measure, along}; rank {measure, within: [uid], direction: desc|asc}." }, "definitionType": { "type": "string", "enum": [ "direct_column", "derived_column", "measure" ], "description": "measure for an aggregate, SQL or typed." }, "canonicalType": { "type": "string", "enum": [ "string", "integer", "decimal", "boolean", "date", "datetime", "json", "unknown" ], "description": "Read-only: the type the engine returns when it is saved." }, "sourceEntityKey": { "type": "string", "description": "The owning entity. A typed measure other than a composite is listed on its measure's table." }, "sourceColumns": { "type": "array", "items": { "type": "string" }, "description": "Columns of sourceEntityKey the expression reads; not used by a typed measure." }, "format": { "type": "object", "additionalProperties": false, "required": [ "style" ], "properties": { "style": { "type": "string", "enum": [ "number", "percent", "currency" ] }, "decimals": { "type": "integer", "minimum": 0, "maximum": 8, "description": "Default 2." }, "currency": { "type": "string", "enum": [ "USD", "EUR", "GBP", "JPY" ], "description": "style currency; default USD." }, "percentInputScale": { "type": "string", "enum": [ "ratio", "percentagePoints" ], "description": "style percent. ratio (the default): 0.372 shows as 37.2%; percentagePoints: 37.2 shows as 37.2%." }, "thousandsSeparator": { "type": "boolean", "description": "Default true." } }, "description": "How visuals show this field's values unless a visual sets its own format; an aggregation of it (sum, count) has none. Empty ({}, or every property null in a tool call) removes it." } }, "required": [ "aliasName", "definitionType", "sourceEntityKey" ], "anyOf": [ { "required": [ "sqlExpression" ] }, { "required": [ "measureKind", "spec" ] } ], "description": "A SQL definition (sqlExpression) or a typed measure (measureKind and spec)." } }, "modelFields": { "type": "array", "items": { "type": "object", "properties": { "fieldUid": { "type": "string", "description": "Exact identity: col_... (source column) or fld_... (definition)." }, "aliasName": { "type": "string" }, "fieldName": { "type": "string" }, "entityKey": { "type": "string" }, "entityUid": { "type": "string" }, "fieldKind": { "type": "string", "enum": [ "source_column", "direct_column", "derived_column", "measure" ] }, "definitionType": { "type": "string" }, "canonicalType": { "type": "string" }, "nativeType": { "type": [ "string", "null" ] }, "sqlExpression": { "type": [ "string", "null" ], "description": "null for a typed measure." }, "measureKind": { "type": "string", "enum": [ "composite", "share", "timeComparison", "runningTotal", "rank" ], "description": "A typed measure's kind, compiled by the query builder; a SQL definition has none." }, "spec": { "type": "object", "description": "A typed measure's fields by fieldUid. composite {formula: node}, a node {measure: uid}, {number: \"1.5\"} or {add|subtract|multiply|divide: [node, node]}; share {measure, across: [uid]}; timeComparison {measure, date, shift: previousYear|previousPeriod}; runningTotal {measure, along}; rank {measure, within: [uid], direction: desc|asc}." }, "isPrimaryKey": { "type": "boolean" }, "isFilterable": { "type": "boolean", "description": "Whether a row filter and a click on a visual can filter by it." }, "filterLevel": { "type": "string", "enum": [ "row", "aggregate", "none" ], "description": "How a saved filter uses it. row: a predicate on source rows, in every visual reading the entity. aggregate (measures): compared with each visual's result at that visual's grain, only in visuals whose result outputs the measure. none: not usable by a filter." }, "description": { "type": [ "string", "null" ] }, "format": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "style" ], "properties": { "style": { "type": "string", "enum": [ "number", "percent", "currency" ] }, "decimals": { "type": "integer", "minimum": 0, "maximum": 8, "description": "Default 2." }, "currency": { "type": "string", "enum": [ "USD", "EUR", "GBP", "JPY" ], "description": "style currency; default USD." }, "percentInputScale": { "type": "string", "enum": [ "ratio", "percentagePoints" ], "description": "style percent. ratio (the default): 0.372 shows as 37.2%; percentagePoints: 37.2 shows as 37.2%." }, "thousandsSeparator": { "type": "boolean", "description": "Default true." } }, "description": "How visuals show this field's values unless a visual sets its own format; an aggregation of it (sum, count) has none. Empty ({}, or every property null in a tool call) removes it." } } }, "description": "Every queryable field and measure." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "connectionId": { "type": "integer" }, "entities": { "type": "array", "items": { "type": "object", "properties": { "entityKey": { "type": "string", "description": "Report-unique entity key: the one name report SQL reads this output by (FROM dbo_transactions), exactly, with no schema. Lowercase; case is ignored when reading. It cannot change after saving." }, "entityName": { "type": "string", "description": "Display name only; report SQL does not read an output by it." }, "entityUid": { "type": "string", "description": "Read-only identity (ent_...), assigned by Unity; sent with another entityKey, the save is refused." }, "entitySqlQuery": { "type": "string", "description": "The source query in the source's native dialect (T-SQL for SQL Server); API providers use provider query JSON." }, "sourceTableName": { "type": [ "string", "null" ], "description": "The table it reads in tables mode (dbo.transactions)." }, "description": { "type": [ "string", "null" ] }, "isPrimary": { "type": "boolean", "description": "The source's primary output." }, "primaryKeyColumns": { "type": "array", "items": { "type": "string" }, "description": "Row identity: the source's declared key; empty when it declares none." }, "entityColumns": { "type": "array", "items": { "type": "string" } }, "entityColumnsDetailed": { "type": "array", "items": { "type": "object" } } }, "required": [ "entityKey" ] } }, "sourceMode": { "type": "string" }, "selectedSchema": { "type": "object" } } }, "description": "Per-connection fragments." } }, "description": "The report's semantic model: the namespace report SQL reads." } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/reports/{report_id}/data-model/calculated-tables": { "put": { "operationId": "connection_model_bp_save_calculated_table_route_put", "summary": "Create or edit a calculated table", "tags": [ "Data model" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "model" ], "description": "Report SQL (DuckDB) over the report's tables whose output columns become fields. It is static: computed from all rows of its tables; filters reach it only through its relationships. Saving runs the SQL once to set its fields and types; a column keeps its fieldUid while its name stays. The entity key cannot change. Removing a field also removes the calculated fields, measures and relationships that use it. When anything reads what a write removes, or SQL names what it renames, the write is refused with code in_use (HTTP 409) and the readers (kind, title, id, pageId, page, effect); confirm=true makes it anyway, and the result lists what went with it (removedWith) and what now shows an error (breaks). Documentation topic connections has the full rules.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entityKey": { "type": "string", "description": "Its report name: lowercase letters, digits and underscores." }, "sql": { "type": "string", "description": "One SELECT or WITH statement over the report's tables." }, "entityName": { "type": "string", "description": "Display name." }, "description": { "type": "string" }, "expectedModelRevision": { "type": "integer", "minimum": 0, "description": "The model revision you inspected. A stale revision answers 409 model_conflict." }, "confirm": { "type": "boolean", "description": "true makes the change after 409 in_use." } }, "required": [ "entityKey", "sql", "expectedModelRevision" ] }, "example": { "entityKey": "customer_orders", "entityName": "Customer orders", "expectedModelRevision": 4, "sql": "SELECT o.customer_id, COUNT(*) AS orders FROM dbo_transactions o GROUP BY o.customer_id" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "model": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid" }, "modelRevision": { "type": "integer" }, "snapshotVersion": { "type": "string" }, "queryDialect": { "type": "string", "description": "Report SQL dialect: duckdb." }, "primaryEntityKey": { "type": [ "string", "null" ] }, "entities": { "type": "array", "items": { "type": "object", "properties": { "entityKey": { "type": "string", "description": "Report-unique entity key: the one name report SQL reads this output by (FROM dbo_transactions), exactly, with no schema. Lowercase; case is ignored when reading. It cannot change after saving." }, "entityName": { "type": "string", "description": "Display name only; report SQL does not read an output by it." }, "entityUid": { "type": "string", "description": "Read-only identity (ent_...), assigned by Unity; sent with another entityKey, the save is refused." }, "entitySqlQuery": { "type": "string", "description": "The source query in the source's native dialect (T-SQL for SQL Server); API providers use provider query JSON." }, "sourceTableName": { "type": [ "string", "null" ], "description": "The table it reads in tables mode (dbo.transactions)." }, "description": { "type": [ "string", "null" ] }, "isPrimary": { "type": "boolean", "description": "The source's primary output." }, "primaryKeyColumns": { "type": "array", "items": { "type": "string" }, "description": "Row identity: the source's declared key; empty when it declares none." }, "entityColumns": { "type": "array", "items": { "type": "string" } }, "entityColumnsDetailed": { "type": "array", "items": { "type": "object" } } }, "required": [ "entityKey" ] } }, "relationships": { "type": "array", "items": { "type": "object", "properties": { "fromEntityKey": { "type": "string" }, "fromColumn": { "type": "string" }, "toEntityKey": { "type": "string" }, "toColumn": { "type": "string" }, "isActive": { "type": "boolean", "default": true }, "crossFilter": { "type": "string", "enum": [ "single", "both" ], "description": "single (the default when absent): filters flow from the to (key) end to the from end; both: each end filters the other." }, "relationshipName": { "type": "string", "description": "A display name." }, "relationshipId": { "type": "integer", "description": "Read-only." } }, "required": [ "fromEntityKey", "fromColumn", "toEntityKey", "toColumn" ], "description": "A filter reaches the other end as a key set, in the relationship's crossFilter direction; it never multiplies rows." } }, "dataDefinitions": { "type": "array", "items": { "type": "object", "properties": { "definitionId": { "type": "integer", "description": "Assigned by Unity. Sent back with its definitionVersion, it edits that definition (a stale version answers 409); without it, a definition is matched by aliasName and sourceEntityKey." }, "definitionVersion": { "type": "integer", "description": "Read-only; the version a definitionId edit is checked against." }, "aliasName": { "type": "string", "description": "Field or measure name used in report SQL (t.\"Total Spend\")." }, "description": { "type": "string", "description": "Business meaning: inclusions, exclusions, units." }, "sqlExpression": { "type": "string", "description": "DuckDB expression over the owning entity's columns; an aggregate for a measure. A typed measure has none." }, "measureKind": { "type": "string", "enum": [ "composite", "share", "timeComparison", "runningTotal", "rank" ], "description": "A typed measure's kind, compiled by the query builder; a SQL definition has none." }, "spec": { "type": "object", "description": "A typed measure's fields by fieldUid. composite {formula: node}, a node {measure: uid}, {number: \"1.5\"} or {add|subtract|multiply|divide: [node, node]}; share {measure, across: [uid]}; timeComparison {measure, date, shift: previousYear|previousPeriod}; runningTotal {measure, along}; rank {measure, within: [uid], direction: desc|asc}." }, "definitionType": { "type": "string", "enum": [ "direct_column", "derived_column", "measure" ], "description": "measure for an aggregate, SQL or typed." }, "canonicalType": { "type": "string", "enum": [ "string", "integer", "decimal", "boolean", "date", "datetime", "json", "unknown" ], "description": "Read-only: the type the engine returns when it is saved." }, "sourceEntityKey": { "type": "string", "description": "The owning entity. A typed measure other than a composite is listed on its measure's table." }, "sourceColumns": { "type": "array", "items": { "type": "string" }, "description": "Columns of sourceEntityKey the expression reads; not used by a typed measure." }, "format": { "type": "object", "additionalProperties": false, "required": [ "style" ], "properties": { "style": { "type": "string", "enum": [ "number", "percent", "currency" ] }, "decimals": { "type": "integer", "minimum": 0, "maximum": 8, "description": "Default 2." }, "currency": { "type": "string", "enum": [ "USD", "EUR", "GBP", "JPY" ], "description": "style currency; default USD." }, "percentInputScale": { "type": "string", "enum": [ "ratio", "percentagePoints" ], "description": "style percent. ratio (the default): 0.372 shows as 37.2%; percentagePoints: 37.2 shows as 37.2%." }, "thousandsSeparator": { "type": "boolean", "description": "Default true." } }, "description": "How visuals show this field's values unless a visual sets its own format; an aggregation of it (sum, count) has none. Empty ({}, or every property null in a tool call) removes it." } }, "required": [ "aliasName", "definitionType", "sourceEntityKey" ], "anyOf": [ { "required": [ "sqlExpression" ] }, { "required": [ "measureKind", "spec" ] } ], "description": "A SQL definition (sqlExpression) or a typed measure (measureKind and spec)." } }, "modelFields": { "type": "array", "items": { "type": "object", "properties": { "fieldUid": { "type": "string", "description": "Exact identity: col_... (source column) or fld_... (definition)." }, "aliasName": { "type": "string" }, "fieldName": { "type": "string" }, "entityKey": { "type": "string" }, "entityUid": { "type": "string" }, "fieldKind": { "type": "string", "enum": [ "source_column", "direct_column", "derived_column", "measure" ] }, "definitionType": { "type": "string" }, "canonicalType": { "type": "string" }, "nativeType": { "type": [ "string", "null" ] }, "sqlExpression": { "type": [ "string", "null" ], "description": "null for a typed measure." }, "measureKind": { "type": "string", "enum": [ "composite", "share", "timeComparison", "runningTotal", "rank" ], "description": "A typed measure's kind, compiled by the query builder; a SQL definition has none." }, "spec": { "type": "object", "description": "A typed measure's fields by fieldUid. composite {formula: node}, a node {measure: uid}, {number: \"1.5\"} or {add|subtract|multiply|divide: [node, node]}; share {measure, across: [uid]}; timeComparison {measure, date, shift: previousYear|previousPeriod}; runningTotal {measure, along}; rank {measure, within: [uid], direction: desc|asc}." }, "isPrimaryKey": { "type": "boolean" }, "isFilterable": { "type": "boolean", "description": "Whether a row filter and a click on a visual can filter by it." }, "filterLevel": { "type": "string", "enum": [ "row", "aggregate", "none" ], "description": "How a saved filter uses it. row: a predicate on source rows, in every visual reading the entity. aggregate (measures): compared with each visual's result at that visual's grain, only in visuals whose result outputs the measure. none: not usable by a filter." }, "description": { "type": [ "string", "null" ] }, "format": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "style" ], "properties": { "style": { "type": "string", "enum": [ "number", "percent", "currency" ] }, "decimals": { "type": "integer", "minimum": 0, "maximum": 8, "description": "Default 2." }, "currency": { "type": "string", "enum": [ "USD", "EUR", "GBP", "JPY" ], "description": "style currency; default USD." }, "percentInputScale": { "type": "string", "enum": [ "ratio", "percentagePoints" ], "description": "style percent. ratio (the default): 0.372 shows as 37.2%; percentagePoints: 37.2 shows as 37.2%." }, "thousandsSeparator": { "type": "boolean", "description": "Default true." } }, "description": "How visuals show this field's values unless a visual sets its own format; an aggregation of it (sum, count) has none. Empty ({}, or every property null in a tool call) removes it." } } }, "description": "Every queryable field and measure." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "connectionId": { "type": "integer" }, "entities": { "type": "array", "items": { "type": "object", "properties": { "entityKey": { "type": "string", "description": "Report-unique entity key: the one name report SQL reads this output by (FROM dbo_transactions), exactly, with no schema. Lowercase; case is ignored when reading. It cannot change after saving." }, "entityName": { "type": "string", "description": "Display name only; report SQL does not read an output by it." }, "entityUid": { "type": "string", "description": "Read-only identity (ent_...), assigned by Unity; sent with another entityKey, the save is refused." }, "entitySqlQuery": { "type": "string", "description": "The source query in the source's native dialect (T-SQL for SQL Server); API providers use provider query JSON." }, "sourceTableName": { "type": [ "string", "null" ], "description": "The table it reads in tables mode (dbo.transactions)." }, "description": { "type": [ "string", "null" ] }, "isPrimary": { "type": "boolean", "description": "The source's primary output." }, "primaryKeyColumns": { "type": "array", "items": { "type": "string" }, "description": "Row identity: the source's declared key; empty when it declares none." }, "entityColumns": { "type": "array", "items": { "type": "string" } }, "entityColumnsDetailed": { "type": "array", "items": { "type": "object" } } }, "required": [ "entityKey" ] } }, "sourceMode": { "type": "string" }, "selectedSchema": { "type": "object" } } }, "description": "Per-connection fragments." } }, "description": "The report's semantic model: the namespace report SQL reads." } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/reports/{report_id}/data-model/calculated-tables/{entity_key}": { "delete": { "operationId": "connection_model_bp_delete_calculated_table_route_delete", "summary": "Delete a calculated table", "tags": [ "Data model" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "model" ], "description": "Removes it and its relationships, listed in removedRelationships. Removing a field also removes the calculated fields, measures and relationships that use it. When anything reads what a write removes, or SQL names what it renames, the write is refused with code in_use (HTTP 409) and the readers (kind, title, id, pageId, page, effect); confirm=true makes it anyway, and the result lists what went with it (removedWith) and what now shows an error (breaks). Documentation topic connections has the full rules.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "entity_key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedModelRevision": { "type": "integer", "minimum": 0, "description": "The model revision you inspected. A stale revision answers 409 model_conflict." }, "confirm": { "type": "boolean", "description": "true makes the change after 409 in_use." } }, "required": [ "expectedModelRevision" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "model": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid" }, "modelRevision": { "type": "integer" }, "snapshotVersion": { "type": "string" }, "queryDialect": { "type": "string", "description": "Report SQL dialect: duckdb." }, "primaryEntityKey": { "type": [ "string", "null" ] }, "entities": { "type": "array", "items": { "type": "object", "properties": { "entityKey": { "type": "string", "description": "Report-unique entity key: the one name report SQL reads this output by (FROM dbo_transactions), exactly, with no schema. Lowercase; case is ignored when reading. It cannot change after saving." }, "entityName": { "type": "string", "description": "Display name only; report SQL does not read an output by it." }, "entityUid": { "type": "string", "description": "Read-only identity (ent_...), assigned by Unity; sent with another entityKey, the save is refused." }, "entitySqlQuery": { "type": "string", "description": "The source query in the source's native dialect (T-SQL for SQL Server); API providers use provider query JSON." }, "sourceTableName": { "type": [ "string", "null" ], "description": "The table it reads in tables mode (dbo.transactions)." }, "description": { "type": [ "string", "null" ] }, "isPrimary": { "type": "boolean", "description": "The source's primary output." }, "primaryKeyColumns": { "type": "array", "items": { "type": "string" }, "description": "Row identity: the source's declared key; empty when it declares none." }, "entityColumns": { "type": "array", "items": { "type": "string" } }, "entityColumnsDetailed": { "type": "array", "items": { "type": "object" } } }, "required": [ "entityKey" ] } }, "relationships": { "type": "array", "items": { "type": "object", "properties": { "fromEntityKey": { "type": "string" }, "fromColumn": { "type": "string" }, "toEntityKey": { "type": "string" }, "toColumn": { "type": "string" }, "isActive": { "type": "boolean", "default": true }, "crossFilter": { "type": "string", "enum": [ "single", "both" ], "description": "single (the default when absent): filters flow from the to (key) end to the from end; both: each end filters the other." }, "relationshipName": { "type": "string", "description": "A display name." }, "relationshipId": { "type": "integer", "description": "Read-only." } }, "required": [ "fromEntityKey", "fromColumn", "toEntityKey", "toColumn" ], "description": "A filter reaches the other end as a key set, in the relationship's crossFilter direction; it never multiplies rows." } }, "dataDefinitions": { "type": "array", "items": { "type": "object", "properties": { "definitionId": { "type": "integer", "description": "Assigned by Unity. Sent back with its definitionVersion, it edits that definition (a stale version answers 409); without it, a definition is matched by aliasName and sourceEntityKey." }, "definitionVersion": { "type": "integer", "description": "Read-only; the version a definitionId edit is checked against." }, "aliasName": { "type": "string", "description": "Field or measure name used in report SQL (t.\"Total Spend\")." }, "description": { "type": "string", "description": "Business meaning: inclusions, exclusions, units." }, "sqlExpression": { "type": "string", "description": "DuckDB expression over the owning entity's columns; an aggregate for a measure. A typed measure has none." }, "measureKind": { "type": "string", "enum": [ "composite", "share", "timeComparison", "runningTotal", "rank" ], "description": "A typed measure's kind, compiled by the query builder; a SQL definition has none." }, "spec": { "type": "object", "description": "A typed measure's fields by fieldUid. composite {formula: node}, a node {measure: uid}, {number: \"1.5\"} or {add|subtract|multiply|divide: [node, node]}; share {measure, across: [uid]}; timeComparison {measure, date, shift: previousYear|previousPeriod}; runningTotal {measure, along}; rank {measure, within: [uid], direction: desc|asc}." }, "definitionType": { "type": "string", "enum": [ "direct_column", "derived_column", "measure" ], "description": "measure for an aggregate, SQL or typed." }, "canonicalType": { "type": "string", "enum": [ "string", "integer", "decimal", "boolean", "date", "datetime", "json", "unknown" ], "description": "Read-only: the type the engine returns when it is saved." }, "sourceEntityKey": { "type": "string", "description": "The owning entity. A typed measure other than a composite is listed on its measure's table." }, "sourceColumns": { "type": "array", "items": { "type": "string" }, "description": "Columns of sourceEntityKey the expression reads; not used by a typed measure." }, "format": { "type": "object", "additionalProperties": false, "required": [ "style" ], "properties": { "style": { "type": "string", "enum": [ "number", "percent", "currency" ] }, "decimals": { "type": "integer", "minimum": 0, "maximum": 8, "description": "Default 2." }, "currency": { "type": "string", "enum": [ "USD", "EUR", "GBP", "JPY" ], "description": "style currency; default USD." }, "percentInputScale": { "type": "string", "enum": [ "ratio", "percentagePoints" ], "description": "style percent. ratio (the default): 0.372 shows as 37.2%; percentagePoints: 37.2 shows as 37.2%." }, "thousandsSeparator": { "type": "boolean", "description": "Default true." } }, "description": "How visuals show this field's values unless a visual sets its own format; an aggregation of it (sum, count) has none. Empty ({}, or every property null in a tool call) removes it." } }, "required": [ "aliasName", "definitionType", "sourceEntityKey" ], "anyOf": [ { "required": [ "sqlExpression" ] }, { "required": [ "measureKind", "spec" ] } ], "description": "A SQL definition (sqlExpression) or a typed measure (measureKind and spec)." } }, "modelFields": { "type": "array", "items": { "type": "object", "properties": { "fieldUid": { "type": "string", "description": "Exact identity: col_... (source column) or fld_... (definition)." }, "aliasName": { "type": "string" }, "fieldName": { "type": "string" }, "entityKey": { "type": "string" }, "entityUid": { "type": "string" }, "fieldKind": { "type": "string", "enum": [ "source_column", "direct_column", "derived_column", "measure" ] }, "definitionType": { "type": "string" }, "canonicalType": { "type": "string" }, "nativeType": { "type": [ "string", "null" ] }, "sqlExpression": { "type": [ "string", "null" ], "description": "null for a typed measure." }, "measureKind": { "type": "string", "enum": [ "composite", "share", "timeComparison", "runningTotal", "rank" ], "description": "A typed measure's kind, compiled by the query builder; a SQL definition has none." }, "spec": { "type": "object", "description": "A typed measure's fields by fieldUid. composite {formula: node}, a node {measure: uid}, {number: \"1.5\"} or {add|subtract|multiply|divide: [node, node]}; share {measure, across: [uid]}; timeComparison {measure, date, shift: previousYear|previousPeriod}; runningTotal {measure, along}; rank {measure, within: [uid], direction: desc|asc}." }, "isPrimaryKey": { "type": "boolean" }, "isFilterable": { "type": "boolean", "description": "Whether a row filter and a click on a visual can filter by it." }, "filterLevel": { "type": "string", "enum": [ "row", "aggregate", "none" ], "description": "How a saved filter uses it. row: a predicate on source rows, in every visual reading the entity. aggregate (measures): compared with each visual's result at that visual's grain, only in visuals whose result outputs the measure. none: not usable by a filter." }, "description": { "type": [ "string", "null" ] }, "format": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "style" ], "properties": { "style": { "type": "string", "enum": [ "number", "percent", "currency" ] }, "decimals": { "type": "integer", "minimum": 0, "maximum": 8, "description": "Default 2." }, "currency": { "type": "string", "enum": [ "USD", "EUR", "GBP", "JPY" ], "description": "style currency; default USD." }, "percentInputScale": { "type": "string", "enum": [ "ratio", "percentagePoints" ], "description": "style percent. ratio (the default): 0.372 shows as 37.2%; percentagePoints: 37.2 shows as 37.2%." }, "thousandsSeparator": { "type": "boolean", "description": "Default true." } }, "description": "How visuals show this field's values unless a visual sets its own format; an aggregation of it (sum, count) has none. Empty ({}, or every property null in a tool call) removes it." } } }, "description": "Every queryable field and measure." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "connectionId": { "type": "integer" }, "entities": { "type": "array", "items": { "type": "object", "properties": { "entityKey": { "type": "string", "description": "Report-unique entity key: the one name report SQL reads this output by (FROM dbo_transactions), exactly, with no schema. Lowercase; case is ignored when reading. It cannot change after saving." }, "entityName": { "type": "string", "description": "Display name only; report SQL does not read an output by it." }, "entityUid": { "type": "string", "description": "Read-only identity (ent_...), assigned by Unity; sent with another entityKey, the save is refused." }, "entitySqlQuery": { "type": "string", "description": "The source query in the source's native dialect (T-SQL for SQL Server); API providers use provider query JSON." }, "sourceTableName": { "type": [ "string", "null" ], "description": "The table it reads in tables mode (dbo.transactions)." }, "description": { "type": [ "string", "null" ] }, "isPrimary": { "type": "boolean", "description": "The source's primary output." }, "primaryKeyColumns": { "type": "array", "items": { "type": "string" }, "description": "Row identity: the source's declared key; empty when it declares none." }, "entityColumns": { "type": "array", "items": { "type": "string" } }, "entityColumnsDetailed": { "type": "array", "items": { "type": "object" } } }, "required": [ "entityKey" ] } }, "sourceMode": { "type": "string" }, "selectedSchema": { "type": "object" } } }, "description": "Per-connection fragments." } }, "description": "The report's semantic model: the namespace report SQL reads." }, "removedRelationships": { "type": "array", "items": { "type": "object", "properties": { "fromEntityKey": { "type": "string" }, "fromColumn": { "type": "string" }, "toEntityKey": { "type": "string" }, "toColumn": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/reports/{report_id}/data-model/fields/{field_uid}": { "delete": { "operationId": "connection_model_bp_remove_report_field_delete", "summary": "Remove a field from the model", "tags": [ "Data model" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "model" ], "description": "Removes a field (by fieldUid): a definition, or a column of a tables-mode table, whose generated query then selects the others. A custom-SQL table's columns come from its SQL: remove one from its query. A table keeps at least one column. Removing a field also removes the calculated fields, measures and relationships that use it. When anything reads what a write removes, or SQL names what it renames, the write is refused with code in_use (HTTP 409) and the readers (kind, title, id, pageId, page, effect); confirm=true makes it anyway, and the result lists what went with it (removedWith) and what now shows an error (breaks). Documentation topic connections has the full rules.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "field_uid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedModelRevision": { "type": "integer", "minimum": 0, "description": "The model revision you inspected. A stale revision answers 409 model_conflict." }, "confirm": { "type": "boolean", "description": "true makes the change after 409 in_use." }, "check": { "type": "boolean", "description": "true removes nothing (a column only): the answer is 409 in_use with what the removal would remove or break, an empty readers list when nothing." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/reports/{report_id}/data-model/query": { "post": { "operationId": "connection_model_bp_query_report_data_model_post", "summary": "Query the model (preview)", "tags": [ "Data model" ], "x-unity-scope": "workspace:read", "x-unity-access": "view", "x-unity-reach": [ "model" ], "description": "Runs report SQL over the model and returns up to 200 rows with column details, for checking a model while editing it. For analysis use POST /api/sql/execute.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sql": { "type": "string", "description": "Report SQL (DuckDB)." }, "rowLimit": { "type": "integer", "default": 100, "minimum": 1, "maximum": 200 } }, "required": [ "sql" ] }, "example": { "sql": "SELECT region, COUNT(*) AS n FROM dbo_customers GROUP BY region", "rowLimit": 10 } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "array", "items": {} } }, "column_metadata": { "type": "array", "items": { "$ref": "#/components/schemas/ColumnMetadata" } }, "columnDetails": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/reports/{report_id}/data-model/relationships": { "put": { "operationId": "connection_model_bp_replace_report_relationships_put", "summary": "Replace the report's relationships", "tags": [ "Data model" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "model" ], "description": "The report's complete relationship collection, including edges between sources. Entity keys and output columns identify each end. A relationship change (added, removed, activated, deactivated or a new crossFilter) that would break a saved visual or page dataset, change what it shows (another join path), or stop or change a filter's reach to one is refused with code in_use and the readers (effect breaks, changes or stopsFiltering); confirm=true makes it anyway, and the result lists them (breaks). A key (to) end with duplicate or blank values is refused (code duplicate_key or blank_key), as is a both that gives a filter a second path (code ambiguous_both).", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "relationships": { "type": "array", "items": { "type": "object", "properties": { "fromEntityKey": { "type": "string" }, "fromColumn": { "type": "string" }, "toEntityKey": { "type": "string" }, "toColumn": { "type": "string" }, "isActive": { "type": "boolean", "default": true }, "crossFilter": { "type": "string", "enum": [ "single", "both" ], "description": "single (the default when absent): filters flow from the to (key) end to the from end; both: each end filters the other." }, "relationshipName": { "type": "string", "description": "A display name." }, "relationshipId": { "type": "integer", "description": "Read-only." } }, "required": [ "fromEntityKey", "fromColumn", "toEntityKey", "toColumn" ], "description": "A filter reaches the other end as a key set, in the relationship's crossFilter direction; it never multiplies rows." } }, "expectedModelRevision": { "type": "integer", "minimum": 0, "description": "The model revision you inspected. A stale revision answers 409 model_conflict." }, "confirm": { "type": "boolean", "description": "true makes the change after 409 in_use." }, "entityLayouts": { "type": "object", "description": "Optional diagram positions by entity key." } }, "required": [ "relationships", "expectedModelRevision" ] }, "example": { "expectedModelRevision": 3, "relationships": [ { "fromEntityKey": "dbo_transactions", "fromColumn": "customer_id", "toEntityKey": "dbo_customers", "toColumn": "customer_id", "isActive": true } ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "model": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid" }, "modelRevision": { "type": "integer" }, "snapshotVersion": { "type": "string" }, "queryDialect": { "type": "string", "description": "Report SQL dialect: duckdb." }, "primaryEntityKey": { "type": [ "string", "null" ] }, "entities": { "type": "array", "items": { "type": "object", "properties": { "entityKey": { "type": "string", "description": "Report-unique entity key: the one name report SQL reads this output by (FROM dbo_transactions), exactly, with no schema. Lowercase; case is ignored when reading. It cannot change after saving." }, "entityName": { "type": "string", "description": "Display name only; report SQL does not read an output by it." }, "entityUid": { "type": "string", "description": "Read-only identity (ent_...), assigned by Unity; sent with another entityKey, the save is refused." }, "entitySqlQuery": { "type": "string", "description": "The source query in the source's native dialect (T-SQL for SQL Server); API providers use provider query JSON." }, "sourceTableName": { "type": [ "string", "null" ], "description": "The table it reads in tables mode (dbo.transactions)." }, "description": { "type": [ "string", "null" ] }, "isPrimary": { "type": "boolean", "description": "The source's primary output." }, "primaryKeyColumns": { "type": "array", "items": { "type": "string" }, "description": "Row identity: the source's declared key; empty when it declares none." }, "entityColumns": { "type": "array", "items": { "type": "string" } }, "entityColumnsDetailed": { "type": "array", "items": { "type": "object" } } }, "required": [ "entityKey" ] } }, "relationships": { "type": "array", "items": { "type": "object", "properties": { "fromEntityKey": { "type": "string" }, "fromColumn": { "type": "string" }, "toEntityKey": { "type": "string" }, "toColumn": { "type": "string" }, "isActive": { "type": "boolean", "default": true }, "crossFilter": { "type": "string", "enum": [ "single", "both" ], "description": "single (the default when absent): filters flow from the to (key) end to the from end; both: each end filters the other." }, "relationshipName": { "type": "string", "description": "A display name." }, "relationshipId": { "type": "integer", "description": "Read-only." } }, "required": [ "fromEntityKey", "fromColumn", "toEntityKey", "toColumn" ], "description": "A filter reaches the other end as a key set, in the relationship's crossFilter direction; it never multiplies rows." } }, "dataDefinitions": { "type": "array", "items": { "type": "object", "properties": { "definitionId": { "type": "integer", "description": "Assigned by Unity. Sent back with its definitionVersion, it edits that definition (a stale version answers 409); without it, a definition is matched by aliasName and sourceEntityKey." }, "definitionVersion": { "type": "integer", "description": "Read-only; the version a definitionId edit is checked against." }, "aliasName": { "type": "string", "description": "Field or measure name used in report SQL (t.\"Total Spend\")." }, "description": { "type": "string", "description": "Business meaning: inclusions, exclusions, units." }, "sqlExpression": { "type": "string", "description": "DuckDB expression over the owning entity's columns; an aggregate for a measure. A typed measure has none." }, "measureKind": { "type": "string", "enum": [ "composite", "share", "timeComparison", "runningTotal", "rank" ], "description": "A typed measure's kind, compiled by the query builder; a SQL definition has none." }, "spec": { "type": "object", "description": "A typed measure's fields by fieldUid. composite {formula: node}, a node {measure: uid}, {number: \"1.5\"} or {add|subtract|multiply|divide: [node, node]}; share {measure, across: [uid]}; timeComparison {measure, date, shift: previousYear|previousPeriod}; runningTotal {measure, along}; rank {measure, within: [uid], direction: desc|asc}." }, "definitionType": { "type": "string", "enum": [ "direct_column", "derived_column", "measure" ], "description": "measure for an aggregate, SQL or typed." }, "canonicalType": { "type": "string", "enum": [ "string", "integer", "decimal", "boolean", "date", "datetime", "json", "unknown" ], "description": "Read-only: the type the engine returns when it is saved." }, "sourceEntityKey": { "type": "string", "description": "The owning entity. A typed measure other than a composite is listed on its measure's table." }, "sourceColumns": { "type": "array", "items": { "type": "string" }, "description": "Columns of sourceEntityKey the expression reads; not used by a typed measure." }, "format": { "type": "object", "additionalProperties": false, "required": [ "style" ], "properties": { "style": { "type": "string", "enum": [ "number", "percent", "currency" ] }, "decimals": { "type": "integer", "minimum": 0, "maximum": 8, "description": "Default 2." }, "currency": { "type": "string", "enum": [ "USD", "EUR", "GBP", "JPY" ], "description": "style currency; default USD." }, "percentInputScale": { "type": "string", "enum": [ "ratio", "percentagePoints" ], "description": "style percent. ratio (the default): 0.372 shows as 37.2%; percentagePoints: 37.2 shows as 37.2%." }, "thousandsSeparator": { "type": "boolean", "description": "Default true." } }, "description": "How visuals show this field's values unless a visual sets its own format; an aggregation of it (sum, count) has none. Empty ({}, or every property null in a tool call) removes it." } }, "required": [ "aliasName", "definitionType", "sourceEntityKey" ], "anyOf": [ { "required": [ "sqlExpression" ] }, { "required": [ "measureKind", "spec" ] } ], "description": "A SQL definition (sqlExpression) or a typed measure (measureKind and spec)." } }, "modelFields": { "type": "array", "items": { "type": "object", "properties": { "fieldUid": { "type": "string", "description": "Exact identity: col_... (source column) or fld_... (definition)." }, "aliasName": { "type": "string" }, "fieldName": { "type": "string" }, "entityKey": { "type": "string" }, "entityUid": { "type": "string" }, "fieldKind": { "type": "string", "enum": [ "source_column", "direct_column", "derived_column", "measure" ] }, "definitionType": { "type": "string" }, "canonicalType": { "type": "string" }, "nativeType": { "type": [ "string", "null" ] }, "sqlExpression": { "type": [ "string", "null" ], "description": "null for a typed measure." }, "measureKind": { "type": "string", "enum": [ "composite", "share", "timeComparison", "runningTotal", "rank" ], "description": "A typed measure's kind, compiled by the query builder; a SQL definition has none." }, "spec": { "type": "object", "description": "A typed measure's fields by fieldUid. composite {formula: node}, a node {measure: uid}, {number: \"1.5\"} or {add|subtract|multiply|divide: [node, node]}; share {measure, across: [uid]}; timeComparison {measure, date, shift: previousYear|previousPeriod}; runningTotal {measure, along}; rank {measure, within: [uid], direction: desc|asc}." }, "isPrimaryKey": { "type": "boolean" }, "isFilterable": { "type": "boolean", "description": "Whether a row filter and a click on a visual can filter by it." }, "filterLevel": { "type": "string", "enum": [ "row", "aggregate", "none" ], "description": "How a saved filter uses it. row: a predicate on source rows, in every visual reading the entity. aggregate (measures): compared with each visual's result at that visual's grain, only in visuals whose result outputs the measure. none: not usable by a filter." }, "description": { "type": [ "string", "null" ] }, "format": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "style" ], "properties": { "style": { "type": "string", "enum": [ "number", "percent", "currency" ] }, "decimals": { "type": "integer", "minimum": 0, "maximum": 8, "description": "Default 2." }, "currency": { "type": "string", "enum": [ "USD", "EUR", "GBP", "JPY" ], "description": "style currency; default USD." }, "percentInputScale": { "type": "string", "enum": [ "ratio", "percentagePoints" ], "description": "style percent. ratio (the default): 0.372 shows as 37.2%; percentagePoints: 37.2 shows as 37.2%." }, "thousandsSeparator": { "type": "boolean", "description": "Default true." } }, "description": "How visuals show this field's values unless a visual sets its own format; an aggregation of it (sum, count) has none. Empty ({}, or every property null in a tool call) removes it." } } }, "description": "Every queryable field and measure." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "connectionId": { "type": "integer" }, "entities": { "type": "array", "items": { "type": "object", "properties": { "entityKey": { "type": "string", "description": "Report-unique entity key: the one name report SQL reads this output by (FROM dbo_transactions), exactly, with no schema. Lowercase; case is ignored when reading. It cannot change after saving." }, "entityName": { "type": "string", "description": "Display name only; report SQL does not read an output by it." }, "entityUid": { "type": "string", "description": "Read-only identity (ent_...), assigned by Unity; sent with another entityKey, the save is refused." }, "entitySqlQuery": { "type": "string", "description": "The source query in the source's native dialect (T-SQL for SQL Server); API providers use provider query JSON." }, "sourceTableName": { "type": [ "string", "null" ], "description": "The table it reads in tables mode (dbo.transactions)." }, "description": { "type": [ "string", "null" ] }, "isPrimary": { "type": "boolean", "description": "The source's primary output." }, "primaryKeyColumns": { "type": "array", "items": { "type": "string" }, "description": "Row identity: the source's declared key; empty when it declares none." }, "entityColumns": { "type": "array", "items": { "type": "string" } }, "entityColumnsDetailed": { "type": "array", "items": { "type": "object" } } }, "required": [ "entityKey" ] } }, "sourceMode": { "type": "string" }, "selectedSchema": { "type": "object" } } }, "description": "Per-connection fragments." } }, "description": "The report's semantic model: the namespace report SQL reads." } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/reports/{report_id}/data-model/sources/{connection_id}": { "delete": { "operationId": "connection_model_bp_remove_connection_model_delete", "summary": "Remove a source from the model", "tags": [ "Data model" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "model" ], "description": "Removes the source's outputs from this report's model; the source stays attached, with no tables. Removing a field also removes the calculated fields, measures and relationships that use it. When anything reads what a write removes, or SQL names what it renames, the write is refused with code in_use (HTTP 409) and the readers (kind, title, id, pageId, page, effect); confirm=true makes it anyway, and the result lists what went with it (removedWith) and what now shows an error (breaks). Documentation topic connections has the full rules.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedModelRevision": { "type": "integer", "minimum": 0, "description": "The model revision you inspected. A stale revision answers 409 model_conflict." }, "confirm": { "type": "boolean", "description": "true makes the change after 409 in_use." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/reports/{report_id}/data-model/sources/{connection_id}/catalog": { "get": { "operationId": "connection_model_bp_get_model_catalog_get", "summary": "Search a source's model", "tags": [ "Data model" ], "x-unity-scope": "workspace:read", "x-unity-access": "view", "x-unity-reach": [ "model" ], "description": "Entities, fields and relationships of one source, searchable and paged; lighter than the whole model.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "entity", "field", "relationship" ], "default": "all" } }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search by model terminology." }, { "name": "fieldUid", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "fld_34b252e22d4a4bfead53432d2da1a22f" ] }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 40, "minimum": 1, "maximum": 100 } }, { "name": "reportId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Compatibility path only: the report." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "items": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" }, "offset": { "type": "integer" }, "complete": { "type": "boolean" }, "nextOffset": { "type": [ "integer", "null" ] }, "modelRevision": { "type": "integer" }, "snapshotVersion": { "type": "string" }, "missingFieldUids": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/reports/{report_id}/data-model/sources/{connection_id}/definitions": { "put": { "operationId": "connection_model_bp_replace_connection_model_definitions_put", "summary": "Save a source's fields and measures", "tags": [ "Data model" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "model" ], "description": "Replaces this source's definitions: send every definition to keep (with its definitionId) plus new ones. Each is validated against the source before saving; a definition sent with its definitionId and a new aliasName is renamed and keeps its fieldUid. Removing a field also removes the calculated fields, measures and relationships that use it. When anything reads what a write removes, or SQL names what it renames, the write is refused with code in_use (HTTP 409) and the readers (kind, title, id, pageId, page, effect); confirm=true makes it anyway, and the result lists what went with it (removedWith) and what now shows an error (breaks). Documentation topic connections has the full rules. Edit access.\n\nUse a measure in report SQL through its entity: SELECT t.\"Total Spend\" FROM dbo_transactions t.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "definitions": { "type": "array", "items": { "type": "object", "properties": { "definitionId": { "type": "integer", "description": "Assigned by Unity. Sent back with its definitionVersion, it edits that definition (a stale version answers 409); without it, a definition is matched by aliasName and sourceEntityKey." }, "definitionVersion": { "type": "integer", "description": "Read-only; the version a definitionId edit is checked against." }, "aliasName": { "type": "string", "description": "Field or measure name used in report SQL (t.\"Total Spend\")." }, "description": { "type": "string", "description": "Business meaning: inclusions, exclusions, units." }, "sqlExpression": { "type": "string", "description": "DuckDB expression over the owning entity's columns; an aggregate for a measure. A typed measure has none." }, "measureKind": { "type": "string", "enum": [ "composite", "share", "timeComparison", "runningTotal", "rank" ], "description": "A typed measure's kind, compiled by the query builder; a SQL definition has none." }, "spec": { "type": "object", "description": "A typed measure's fields by fieldUid. composite {formula: node}, a node {measure: uid}, {number: \"1.5\"} or {add|subtract|multiply|divide: [node, node]}; share {measure, across: [uid]}; timeComparison {measure, date, shift: previousYear|previousPeriod}; runningTotal {measure, along}; rank {measure, within: [uid], direction: desc|asc}." }, "definitionType": { "type": "string", "enum": [ "direct_column", "derived_column", "measure" ], "description": "measure for an aggregate, SQL or typed." }, "canonicalType": { "type": "string", "enum": [ "string", "integer", "decimal", "boolean", "date", "datetime", "json", "unknown" ], "description": "Read-only: the type the engine returns when it is saved." }, "sourceEntityKey": { "type": "string", "description": "The owning entity. A typed measure other than a composite is listed on its measure's table." }, "sourceColumns": { "type": "array", "items": { "type": "string" }, "description": "Columns of sourceEntityKey the expression reads; not used by a typed measure." }, "format": { "type": "object", "additionalProperties": false, "required": [ "style" ], "properties": { "style": { "type": "string", "enum": [ "number", "percent", "currency" ] }, "decimals": { "type": "integer", "minimum": 0, "maximum": 8, "description": "Default 2." }, "currency": { "type": "string", "enum": [ "USD", "EUR", "GBP", "JPY" ], "description": "style currency; default USD." }, "percentInputScale": { "type": "string", "enum": [ "ratio", "percentagePoints" ], "description": "style percent. ratio (the default): 0.372 shows as 37.2%; percentagePoints: 37.2 shows as 37.2%." }, "thousandsSeparator": { "type": "boolean", "description": "Default true." } }, "description": "How visuals show this field's values unless a visual sets its own format; an aggregation of it (sum, count) has none. Empty ({}, or every property null in a tool call) removes it." } }, "required": [ "aliasName", "definitionType", "sourceEntityKey" ], "anyOf": [ { "required": [ "sqlExpression" ] }, { "required": [ "measureKind", "spec" ] } ], "description": "A SQL definition (sqlExpression) or a typed measure (measureKind and spec)." } }, "expectedModelRevision": { "type": "integer", "minimum": 0, "description": "The model revision you inspected. A stale revision answers 409 model_conflict." }, "confirm": { "type": "boolean", "description": "true makes the change after 409 in_use." } }, "required": [ "definitions" ] }, "example": { "expectedModelRevision": 2, "definitions": [ { "aliasName": "Total Spend", "description": "Sum of absolute debit amounts, excluding internal transfers.", "sqlExpression": "SUM(CASE WHEN direction = 'debit' AND type <> 'INTERNAL_TRANSFER' THEN ABS(signed_amount) ELSE 0 END)", "definitionType": "measure", "sourceEntityKey": "dbo_transactions", "sourceColumns": [ "direction", "type", "signed_amount" ] } ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "definitions": { "type": "array", "items": { "type": "object", "properties": { "definitionId": { "type": "integer", "description": "Assigned by Unity. Sent back with its definitionVersion, it edits that definition (a stale version answers 409); without it, a definition is matched by aliasName and sourceEntityKey." }, "definitionVersion": { "type": "integer", "description": "Read-only; the version a definitionId edit is checked against." }, "aliasName": { "type": "string", "description": "Field or measure name used in report SQL (t.\"Total Spend\")." }, "description": { "type": "string", "description": "Business meaning: inclusions, exclusions, units." }, "sqlExpression": { "type": "string", "description": "DuckDB expression over the owning entity's columns; an aggregate for a measure. A typed measure has none." }, "measureKind": { "type": "string", "enum": [ "composite", "share", "timeComparison", "runningTotal", "rank" ], "description": "A typed measure's kind, compiled by the query builder; a SQL definition has none." }, "spec": { "type": "object", "description": "A typed measure's fields by fieldUid. composite {formula: node}, a node {measure: uid}, {number: \"1.5\"} or {add|subtract|multiply|divide: [node, node]}; share {measure, across: [uid]}; timeComparison {measure, date, shift: previousYear|previousPeriod}; runningTotal {measure, along}; rank {measure, within: [uid], direction: desc|asc}." }, "definitionType": { "type": "string", "enum": [ "direct_column", "derived_column", "measure" ], "description": "measure for an aggregate, SQL or typed." }, "canonicalType": { "type": "string", "enum": [ "string", "integer", "decimal", "boolean", "date", "datetime", "json", "unknown" ], "description": "Read-only: the type the engine returns when it is saved." }, "sourceEntityKey": { "type": "string", "description": "The owning entity. A typed measure other than a composite is listed on its measure's table." }, "sourceColumns": { "type": "array", "items": { "type": "string" }, "description": "Columns of sourceEntityKey the expression reads; not used by a typed measure." }, "format": { "type": "object", "additionalProperties": false, "required": [ "style" ], "properties": { "style": { "type": "string", "enum": [ "number", "percent", "currency" ] }, "decimals": { "type": "integer", "minimum": 0, "maximum": 8, "description": "Default 2." }, "currency": { "type": "string", "enum": [ "USD", "EUR", "GBP", "JPY" ], "description": "style currency; default USD." }, "percentInputScale": { "type": "string", "enum": [ "ratio", "percentagePoints" ], "description": "style percent. ratio (the default): 0.372 shows as 37.2%; percentagePoints: 37.2 shows as 37.2%." }, "thousandsSeparator": { "type": "boolean", "description": "Default true." } }, "description": "How visuals show this field's values unless a visual sets its own format; an aggregation of it (sum, count) has none. Empty ({}, or every property null in a tool call) removes it." } }, "required": [ "aliasName", "definitionType", "sourceEntityKey" ], "anyOf": [ { "required": [ "sqlExpression" ] }, { "required": [ "measureKind", "spec" ] } ], "description": "A SQL definition (sqlExpression) or a typed measure (measureKind and spec)." } }, "model": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/reports/{report_id}/data-model/sources/{connection_id}/editor-context": { "get": { "operationId": "connection_model_bp_get_connection_model_editor_context_get", "summary": "Read a source's editing context", "tags": [ "Data model" ], "x-unity-scope": "workspace:read", "x-unity-access": "view", "x-unity-reach": [ "model" ], "description": "What a source editor needs: discovered schema, current selection and mode, saved entities and relationships, and entities suggested for the selected tables.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "connection": { "type": "object" }, "schema": { "type": "object" }, "selectedSchema": { "type": "object" }, "selectedTables": { "type": "array", "items": { "type": "string" } }, "sourceMode": { "type": "string" }, "model": { "type": "object" }, "suggestedEntities": { "type": "array", "items": { "type": "object", "properties": { "entityKey": { "type": "string", "description": "Report-unique entity key: the one name report SQL reads this output by (FROM dbo_transactions), exactly, with no schema. Lowercase; case is ignored when reading. It cannot change after saving." }, "entityName": { "type": "string", "description": "Display name only; report SQL does not read an output by it." }, "entityUid": { "type": "string", "description": "Read-only identity (ent_...), assigned by Unity; sent with another entityKey, the save is refused." }, "entitySqlQuery": { "type": "string", "description": "The source query in the source's native dialect (T-SQL for SQL Server); API providers use provider query JSON." }, "sourceTableName": { "type": [ "string", "null" ], "description": "The table it reads in tables mode (dbo.transactions)." }, "description": { "type": [ "string", "null" ] }, "isPrimary": { "type": "boolean", "description": "The source's primary output." }, "primaryKeyColumns": { "type": "array", "items": { "type": "string" }, "description": "Row identity: the source's declared key; empty when it declares none." }, "entityColumns": { "type": "array", "items": { "type": "string" } }, "entityColumnsDetailed": { "type": "array", "items": { "type": "object" } } }, "required": [ "entityKey" ] } }, "entities": { "type": "array", "items": { "type": "object", "properties": { "entityKey": { "type": "string", "description": "Report-unique entity key: the one name report SQL reads this output by (FROM dbo_transactions), exactly, with no schema. Lowercase; case is ignored when reading. It cannot change after saving." }, "entityName": { "type": "string", "description": "Display name only; report SQL does not read an output by it." }, "entityUid": { "type": "string", "description": "Read-only identity (ent_...), assigned by Unity; sent with another entityKey, the save is refused." }, "entitySqlQuery": { "type": "string", "description": "The source query in the source's native dialect (T-SQL for SQL Server); API providers use provider query JSON." }, "sourceTableName": { "type": [ "string", "null" ], "description": "The table it reads in tables mode (dbo.transactions)." }, "description": { "type": [ "string", "null" ] }, "isPrimary": { "type": "boolean", "description": "The source's primary output." }, "primaryKeyColumns": { "type": "array", "items": { "type": "string" }, "description": "Row identity: the source's declared key; empty when it declares none." }, "entityColumns": { "type": "array", "items": { "type": "string" } }, "entityColumnsDetailed": { "type": "array", "items": { "type": "object" } } }, "required": [ "entityKey" ] } }, "relationships": { "type": "array", "items": { "type": "object", "properties": { "fromEntityKey": { "type": "string" }, "fromColumn": { "type": "string" }, "toEntityKey": { "type": "string" }, "toColumn": { "type": "string" }, "isActive": { "type": "boolean", "default": true }, "crossFilter": { "type": "string", "enum": [ "single", "both" ], "description": "single (the default when absent): filters flow from the to (key) end to the from end; both: each end filters the other." }, "relationshipName": { "type": "string", "description": "A display name." }, "relationshipId": { "type": "integer", "description": "Read-only." } }, "required": [ "fromEntityKey", "fromColumn", "toEntityKey", "toColumn" ], "description": "A filter reaches the other end as a key set, in the relationship's crossFilter direction; it never multiplies rows." } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/reports/{report_id}/data-model/sources/{connection_id}/entities": { "put": { "operationId": "connection_model_bp_replace_connection_model_entities_route_put", "summary": "Save a source's entities", "tags": [ "Data model" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "model" ], "description": "Saves this source's part of the model: its mode, selection, entities and optionally its relationships and definitions. Sent without entities, each selected table with no query yet gets a full-table query; saved queries stay. Other reports using the same connection are unaffected. An entity key cannot change after saving. Sent entities can't be empty: removing a source's last table is removing its outputs (the source DELETE). Removing a field also removes the calculated fields, measures and relationships that use it. When anything reads what a write removes, or SQL names what it renames, the write is refused with code in_use (HTTP 409) and the readers (kind, title, id, pageId, page, effect); confirm=true makes it anyway, and the result lists what went with it (removedWith) and what now shows an error (breaks). Documentation topic connections has the full rules. A relationship change (added, removed, activated, deactivated or a new crossFilter) that would break a saved visual or page dataset, change what it shows (another join path), or stop or change a filter's reach to one is refused with code in_use and the readers (effect breaks, changes or stopsFiltering); confirm=true makes it anyway, and the result lists them (breaks). A key (to) end with duplicate or blank values is refused (code duplicate_key or blank_key), as is a both that gives a filter a second path (code ambiguous_both). Edit access.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceMode": { "type": "string", "enum": [ "tables", "custom_sql" ], "description": "tables: entities read whole tables; custom_sql: authored queries." }, "selectedTables": { "type": "array", "items": { "type": "string" }, "description": "Tables to model, as discovered (dbo.transactions). Sent without entities, each one with no query yet gets one, and the saved queries stay." }, "selectedSchema": { "type": "object", "properties": { "tables": { "type": "object", "description": "Table name -> {} for each selected table." } }, "description": "tables mode: the selection; columns come from discovery." }, "entities": { "type": "array", "items": { "type": "object", "properties": { "entityKey": { "type": "string", "description": "Report-unique entity key: the one name report SQL reads this output by (FROM dbo_transactions), exactly, with no schema. Lowercase; case is ignored when reading. It cannot change after saving." }, "entityName": { "type": "string", "description": "Display name only; report SQL does not read an output by it." }, "entityUid": { "type": "string", "description": "Read-only identity (ent_...), assigned by Unity; sent with another entityKey, the save is refused." }, "entitySqlQuery": { "type": "string", "description": "The source query in the source's native dialect (T-SQL for SQL Server); API providers use provider query JSON." }, "sourceTableName": { "type": [ "string", "null" ], "description": "The table it reads in tables mode (dbo.transactions)." }, "description": { "type": [ "string", "null" ] }, "isPrimary": { "type": "boolean", "description": "The source's primary output." }, "primaryKeyColumns": { "type": "array", "items": { "type": "string" }, "description": "Row identity: the source's declared key; empty when it declares none." }, "entityColumns": { "type": "array", "items": { "type": "string" } }, "entityColumnsDetailed": { "type": "array", "items": { "type": "object" } } }, "required": [ "entityKey" ] }, "description": "Replaces this source's entities." }, "relationships": { "type": "array", "items": { "type": "object", "properties": { "fromEntityKey": { "type": "string" }, "fromColumn": { "type": "string" }, "toEntityKey": { "type": "string" }, "toColumn": { "type": "string" }, "isActive": { "type": "boolean", "default": true }, "crossFilter": { "type": "string", "enum": [ "single", "both" ], "description": "single (the default when absent): filters flow from the to (key) end to the from end; both: each end filters the other." }, "relationshipName": { "type": "string", "description": "A display name." }, "relationshipId": { "type": "integer", "description": "Read-only." } }, "required": [ "fromEntityKey", "fromColumn", "toEntityKey", "toColumn" ], "description": "A filter reaches the other end as a key set, in the relationship's crossFilter direction; it never multiplies rows." }, "description": "Relationships within this source." }, "definitions": { "type": "array", "items": { "type": "object", "properties": { "definitionId": { "type": "integer", "description": "Assigned by Unity. Sent back with its definitionVersion, it edits that definition (a stale version answers 409); without it, a definition is matched by aliasName and sourceEntityKey." }, "definitionVersion": { "type": "integer", "description": "Read-only; the version a definitionId edit is checked against." }, "aliasName": { "type": "string", "description": "Field or measure name used in report SQL (t.\"Total Spend\")." }, "description": { "type": "string", "description": "Business meaning: inclusions, exclusions, units." }, "sqlExpression": { "type": "string", "description": "DuckDB expression over the owning entity's columns; an aggregate for a measure. A typed measure has none." }, "measureKind": { "type": "string", "enum": [ "composite", "share", "timeComparison", "runningTotal", "rank" ], "description": "A typed measure's kind, compiled by the query builder; a SQL definition has none." }, "spec": { "type": "object", "description": "A typed measure's fields by fieldUid. composite {formula: node}, a node {measure: uid}, {number: \"1.5\"} or {add|subtract|multiply|divide: [node, node]}; share {measure, across: [uid]}; timeComparison {measure, date, shift: previousYear|previousPeriod}; runningTotal {measure, along}; rank {measure, within: [uid], direction: desc|asc}." }, "definitionType": { "type": "string", "enum": [ "direct_column", "derived_column", "measure" ], "description": "measure for an aggregate, SQL or typed." }, "canonicalType": { "type": "string", "enum": [ "string", "integer", "decimal", "boolean", "date", "datetime", "json", "unknown" ], "description": "Read-only: the type the engine returns when it is saved." }, "sourceEntityKey": { "type": "string", "description": "The owning entity. A typed measure other than a composite is listed on its measure's table." }, "sourceColumns": { "type": "array", "items": { "type": "string" }, "description": "Columns of sourceEntityKey the expression reads; not used by a typed measure." }, "format": { "type": "object", "additionalProperties": false, "required": [ "style" ], "properties": { "style": { "type": "string", "enum": [ "number", "percent", "currency" ] }, "decimals": { "type": "integer", "minimum": 0, "maximum": 8, "description": "Default 2." }, "currency": { "type": "string", "enum": [ "USD", "EUR", "GBP", "JPY" ], "description": "style currency; default USD." }, "percentInputScale": { "type": "string", "enum": [ "ratio", "percentagePoints" ], "description": "style percent. ratio (the default): 0.372 shows as 37.2%; percentagePoints: 37.2 shows as 37.2%." }, "thousandsSeparator": { "type": "boolean", "description": "Default true." } }, "description": "How visuals show this field's values unless a visual sets its own format; an aggregation of it (sum, count) has none. Empty ({}, or every property null in a tool call) removes it." } }, "required": [ "aliasName", "definitionType", "sourceEntityKey" ], "anyOf": [ { "required": [ "sqlExpression" ] }, { "required": [ "measureKind", "spec" ] } ], "description": "A SQL definition (sqlExpression) or a typed measure (measureKind and spec)." }, "description": "This source's reusable fields and measures." }, "description": { "type": [ "string", "null" ] }, "expectedModelRevision": { "type": "integer", "minimum": 0, "description": "The model revision you inspected. A stale revision answers 409 model_conflict." }, "confirm": { "type": "boolean", "description": "true makes the change after 409 in_use." }, "finalizeConnection": { "type": "boolean", "description": "Mark the source configured (the editor's Save)." } } }, "example": { "sourceMode": "tables", "selectedTables": [ "dbo.customers", "dbo.transactions" ], "selectedSchema": { "tables": { "dbo.customers": {}, "dbo.transactions": {} } }, "finalizeConnection": true, "expectedModelRevision": 1 } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "model": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/reports/{report_id}/data-model/sources/{connection_id}/entities/preview": { "post": { "operationId": "connection_model_bp_preview_connection_model_entity_post", "summary": "Preview an entity query", "tags": [ "Data model" ], "x-unity-scope": "workspace:read", "x-unity-access": "edit", "x-unity-reach": [ "model", "source" ], "description": "Runs a native-dialect entity query (or a saved entity, by entityKey) on the source and returns the first rows and typed columns, without saving.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entitySqlQuery": { "type": "string", "description": "Native-dialect SELECT." }, "entityKey": { "type": "string", "description": "Or a saved entity." }, "rowLimit": { "type": "integer", "default": 100 } } }, "example": { "entitySqlQuery": "SELECT TOP 10 * FROM dbo.transactions", "rowLimit": 10 } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "preview": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "array", "items": {} } }, "columnDetails": { "type": "array", "items": { "type": "object" } } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/reports/{report_id}/data-model/sources/{connection_id}/refresh-model": { "post": { "operationId": "connection_model_bp_refresh_semantic_model_route_post", "summary": "Refresh an Analysis Services model", "tags": [ "Data model" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "model", "source" ], "description": "Rediscovers the cube's columns and measures as the caller: existing fields keep their names, new ones are added, removed ones disappear. Removing a field also removes the calculated fields, measures and relationships that use it. When anything reads what a write removes, or SQL names what it renames, the write is refused with code in_use (HTTP 409) and the readers (kind, title, id, pageId, page, effect); confirm=true makes it anyway, and the result lists what went with it (removedWith) and what now shows an error (breaks). Documentation topic connections has the full rules.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedModelRevision": { "type": "integer", "minimum": 0, "description": "The model revision you inspected. A stale revision answers 409 model_conflict." }, "confirm": { "type": "boolean", "description": "true makes the change after 409 in_use." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/reports/{report_id}/deletion": { "get": { "operationId": "report_get_report_deletion_get", "summary": "Follow a report deletion", "tags": [ "Reports" ], "x-unity-scope": "workspace:read", "x-unity-access": "owner", "x-unity-reach": [ "report" ], "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deletion": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "reportName": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "failed", "succeeded" ] }, "phase": { "type": "string", "description": "What the deletion is doing now." }, "error": { "type": [ "string", "null" ] }, "requestedAt": { "type": "string", "description": "ISO 8601 UTC." }, "updatedAt": { "type": "string", "description": "ISO 8601 UTC." }, "completedAt": { "type": [ "string", "null" ], "description": "ISO 8601 UTC." } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/reports/{report_id}/files": { "get": { "operationId": "report_files_report_files_get", "summary": "List a report's files", "tags": [ "Reference files and assets" ], "x-unity-scope": "workspace:read", "x-unity-access": "edit", "x-unity-reach": [ "files" ], "description": "Reference files attached to the report (documents, slides, spreadsheets, HTML, images) that the assistant can read, with the upload limits. Report Edit, Admin or Owner only.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string" }, "sizeBytes": { "type": "integer" }, "createdAt": { "type": "string" } } } }, "maxBytes": { "type": "integer" }, "maxAttachments": { "type": "integer" }, "extensions": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } }, "post": { "operationId": "report_files_report_files_post", "summary": "Upload a reference file", "tags": [ "Reference files and assets" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "files" ], "description": "Multipart form with file (up to 25 MB): PDF, PPTX, DOCX, XLSX, CSV, HTML, text and images. Unity extracts its text, layout and embedded images. Report Edit, Admin or Owner only.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "fileId": { "type": "string", "format": "uuid", "description": "Optional: replace this file." } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string" }, "sizeBytes": { "type": "integer" }, "createdAt": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "413": { "$ref": "#/components/responses/E413" } } } }, "/api/reports/{report_id}/files/{file_id}": { "delete": { "operationId": "report_files_report_file_delete", "summary": "Delete a file", "tags": [ "Reference files and assets" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "files" ], "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } }, "get": { "operationId": "report_files_report_file_get", "summary": "Inspect a file", "tags": [ "Reference files and assets" ], "x-unity-scope": "workspace:read", "x-unity-access": "edit", "x-unity-reach": [ "files" ], "description": "Sections (pages, slides, sheets), an HTML/CSS outline and the embedded image inventory. Report Edit, Admin or Owner only.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/reports/{report_id}/files/{file_id}/assets/{asset_id}/preview": { "get": { "operationId": "report_files_asset_preview_image_get", "summary": "Read an embedded image", "tags": [ "Reference files and assets" ], "x-unity-scope": "workspace:read", "x-unity-access": "edit", "x-unity-reach": [ "files" ], "description": "Report Edit, Admin or Owner only.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/reports/{report_id}/files/{file_id}/assets/{asset_id}/reuse": { "post": { "operationId": "report_files_reuse_asset_post", "summary": "Import an image from a file", "tags": [ "Reference files and assets" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "files" ], "description": "Copies an exact embedded image into the report's asset library; HTML references it as unity-asset:. Report Edit, Admin or Owner only.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/reports/{report_id}/files/{file_id}/content": { "get": { "operationId": "report_files_file_content_get", "summary": "Read a file's text", "tags": [ "Reference files and assets" ], "x-unity-scope": "workspace:read", "x-unity-access": "edit", "x-unity-reach": [ "files" ], "description": "Readable text of one section (or the file), paged by characters or spreadsheet rows; embedded media appear as short asset references. Report Edit, Admin or Owner only.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sectionId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 8000 } }, { "name": "columnOffset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/reports/{report_id}/files/{file_id}/download": { "get": { "operationId": "report_files_download_file_get", "summary": "Download a file", "tags": [ "Reference files and assets" ], "x-unity-scope": "workspace:read", "x-unity-access": "edit", "x-unity-reach": [ "files" ], "description": "Report Edit, Admin or Owner only.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/reports/{report_id}/files/{file_id}/preview": { "post": { "operationId": "report_files_file_preview_post", "summary": "Render a file page or image", "tags": [ "Reference files and assets" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "files" ], "description": "Renders one page or slide (page, 1-based) or one embedded image (assetId) to an image, for an AI that reads images. Report Edit, Admin or Owner only.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "type": "integer", "default": 1, "minimum": 1 }, "assetId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/reports/{report_id}/files/{file_id}/previews/{page}": { "get": { "operationId": "report_files_preview_image_get", "summary": "Read a rendered page image", "tags": [ "Reference files and assets" ], "x-unity-scope": "workspace:read", "x-unity-access": "edit", "x-unity-reach": [ "files" ], "description": "Report Edit, Admin or Owner only.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/reports/{report_id}/files/{file_id}/search": { "get": { "operationId": "report_files_file_search_get", "summary": "Search a file", "tags": [ "Reference files and assets" ], "x-unity-scope": "workspace:read", "x-unity-access": "edit", "x-unity-reach": [ "files" ], "description": "Report Edit, Admin or Owner only.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "query", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "sectionId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } }, { "name": "caseSensitive", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/reports/{report_id}/live": { "get": { "operationId": "report_get_report_liveness_get", "summary": "Poll a report for changes", "tags": [ "Reports" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "chat", "pages", "report" ], "description": "Cheap revision counters: compare them with the last values you saw to know what to re-read (pagesVersion, modelRevision, pagesFingerprint, and with visualsPage that page's visualsRevision), plus each of your conversations' run state. pagesFingerprint changes when any page (HTML or canvas) is saved, created or deleted. With visualsPage it also answers `page` ({pageUid, kind, version}), `hold`, `leases` and `presence` for that page; each HTML page's own version comes from GET /api/html/pages/{pageUid}; history is the report's (GET /api/reports/{reportId}/versions).", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "visualsPage", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Numeric page ID whose visualsRevision to include." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "accessLevel": { "type": "string" }, "pagesVersion": { "type": "string" }, "modelRevision": { "type": "integer" }, "pagesFingerprint": { "type": "string" }, "page": { "type": [ "object", "null" ], "properties": { "pageUid": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "html", "native" ] }, "version": { "type": "integer" } } }, "visualsPageId": { "type": [ "integer", "null" ] }, "visualsRevision": { "type": [ "string", "null" ] }, "chat": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "object", "properties": { "unread_count": { "type": "integer" }, "working_count": { "type": "integer" } } } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/reports/{report_id}/name": { "put": { "operationId": "report_update_report_name_put", "summary": "Rename a report", "tags": [ "Reports" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "report" ], "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportName": { "type": "string", "minLength": 1, "maxLength": 50, "description": "1 to 50 characters." } }, "required": [ "reportName" ] }, "example": { "reportName": "Sales overview FY27" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reportName": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/reports/{report_id}/tools": { "get": { "operationId": "agent_tools_list_report_tools_get", "summary": "List the agent tools", "tags": [ "Agent tools" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "docs" ], "description": "The tools Unity's own assistant uses, offered to your AI for this report: each with its description, access (view or edit), readOnly, and exact JSON input schema. available says whether you can call it here (Edit access and a workspace:write key for tools that change the report); tools your access could never call are left out. A report Viewer (or Edit content person) who also holds Edit on some pages can call the tools that change those pages (editablePages), and only for those pages. Give these to your model as function definitions; call them with POST /api/reports/{report_id}/tools/{name}.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid" }, "accessLevel": { "type": "string" }, "contentEdit": { "type": "boolean", "description": "True for an Edit content share (View access: the tools are a Viewer's)." }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "access": { "type": "string", "enum": [ "view", "edit" ] }, "readOnly": { "type": "boolean", "description": "The tool only reads: a workspace:read key may call it." }, "reach": { "type": "array", "items": { "type": "string" } }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string" }, "inputSchema": { "type": "object", "description": "The exact JSON Schema of the tool's arguments." } } } }, "editablePages": { "type": "array", "items": { "type": "object", "properties": { "pageId": { "type": "string", "format": "uuid" }, "pageName": { "type": "string" }, "pageKind": { "type": "string", "enum": [ "report", "html" ] }, "accessLevel": { "type": "string" } } }, "description": "Present for a Viewer who holds Edit on pages: the pages the change tools work on (every other page, and every report-level action, stays a Viewer's)." } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/reports/{report_id}/tools/{name}": { "post": { "operationId": "agent_tools_call_report_tool_post", "summary": "Call an agent tool", "tags": [ "Agent tools" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_view", "x-unity-reach": [ "docs", "files", "history", "model", "pages", "report", "source" ], "description": "Runs one tool as you, exactly as Unity's assistant would: the arguments are validated against its schema, your report access and key scope apply, and the result is what the assistant would receive. A change returns its receipt and reportVersion, the report version it made: ListReportVersions lists it and RestoreReportVersion brings back the version before it. View tools accept a workspace:read key; tools that change the report need workspace:write and Edit access. Parameters named *Json (also inside a list's items, and HTML operation) take the JSON as text or as the value.\n\nThe HTTP status says whether the call ran: 200 for an executed call (status success or error), 4xx when it did not (unknown tool 404 tool_not_found, invalid arguments 422 invalid_tool_arguments with the failing field, access or scope 403).", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "arguments": { "type": "object", "description": "The tool's arguments, per its inputSchema." }, "sessionId": { "type": "string", "maxLength": 64, "description": "Optional, up to 64 characters: groups your calls into one recorded session (an external assistant run without a conversation)." } }, "required": [ "arguments" ] }, "example": { "arguments": { "visuals": [ { "pageId": "678AE2F0-1469-489E-AE28-B729A0000E51", "visualType": "dataCard", "definitionJson": { "title": "Total spend", "query": { "values": [ { "name": "Spend", "field": "fld_0a1b2c3d4e5f60718293a4b5c6d7e8f9" } ] } } } ] }, "sessionId": "my-agent-session-1" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "status": { "type": "string", "enum": [ "success", "error" ], "description": "error: the tool ran and refused or failed; read result.error." }, "result": { "type": "object", "description": "The tool's result as the assistant receives it." }, "images": { "type": "array", "items": { "type": "object", "properties": { "mimeType": { "type": "string" }, "data": { "type": "string", "description": "Base64." }, "label": { "type": "string" } } }, "description": "Screenshots from preview tools (PreviewPage, PreviewFile, ...)." }, "runId": { "type": "string", "format": "uuid" }, "callId": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" } } }, "get": { "operationId": "agent_tools_read_report_tool_get", "summary": "Read one agent tool", "tags": [ "Agent tools" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "docs" ], "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "access": { "type": "string", "enum": [ "view", "edit" ] }, "readOnly": { "type": "boolean", "description": "The tool only reads: a workspace:read key may call it." }, "reach": { "type": "array", "items": { "type": "string" } }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string" }, "inputSchema": { "type": "object", "description": "The exact JSON Schema of the tool's arguments." } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/reports/{report_id}/versions": { "get": { "operationId": "report_list_report_versions_get", "summary": "List report versions", "tags": [ "Reports" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "history", "model", "pages", "report" ], "description": "The report's saved versions, newest first. Every saved change makes one; version n is the report after that change. Each entry is one assistant run or one person's burst of edits (each within 5 minutes of the one before); expand lists one entry's versions one by one, so one change inside an entry can be undone by restoring the version before it. The first list of the whole report also has deletedPages. Needs Edit access to the report, or to the page with pageId.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "pageId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A page's pageId: only that page's versions and its filters (page Edit is enough)." }, { "name": "beforeVersion", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "nextBeforeVersion from the previous list, for older entries." }, { "name": "expand", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "An entry's version: its versions one by one, each as an entry of its own." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "head": { "type": [ "integer", "null" ], "description": "The latest version." }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer", "description": "The entry's last version: the report after its last change." }, "firstVersion": { "type": "integer" }, "count": { "type": "integer" }, "at": { "type": "string", "description": "ISO 8601 UTC." }, "actor": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Unity for system; null for a caller without Edit access to the report." }, "kind": { "type": "string", "enum": [ "person", "assistant", "external", "page_script", "system" ] } } }, "label": { "type": "string" }, "changed": { "type": "array", "items": { "type": "string" }, "description": "Report, Connections, Model, Filters and pages by name." } } } }, "nextBeforeVersion": { "type": [ "integer", "null" ] }, "deletedPages": { "type": "array", "items": { "type": "object", "properties": { "pageId": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "deletedAt": { "type": "string", "description": "ISO 8601 UTC." }, "deletedBy": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string" } } }, "version": { "type": "integer", "description": "The newest version that still has the page: restore it with this version and pageId." } } }, "description": "Pages deleted since history started that are still gone, newest first (the first list of the whole report)." } } }, "example": { "head": 42, "nextBeforeVersion": null, "versions": [ { "version": 42, "firstVersion": 39, "count": 4, "at": "2026-11-01T09:12:44.120Z", "actor": { "name": "Alex Morgan", "kind": "assistant" }, "label": "Moved visual", "changed": [ "Model", "Page 'Sales'" ] } ] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/reports/{report_id}/versions/diff": { "get": { "operationId": "report_diff_report_versions_get", "summary": "Compare report versions", "tags": [ "Reports" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "history", "model", "pages", "report" ], "description": "What changed from one saved version to another (to omitted: the report now): each object added, removed or changed, by section, kind, id and name, with the keys that changed.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "The earlier version." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The later version." }, { "name": "pageId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A page's pageId: only that page's versions and its filters (page Edit is enough)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "fromVersion": { "type": "integer" }, "toVersion": { "type": [ "integer", "null" ] }, "changes": { "type": "array", "items": { "type": "object", "properties": { "section": { "type": "string", "enum": [ "report", "connections", "model", "pages", "filters" ] }, "kind": { "type": "string" }, "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "pageId": { "type": "string", "format": "uuid" }, "change": { "type": "string", "enum": [ "added", "removed", "changed" ] }, "keys": { "type": "array", "items": { "type": "string" } } } } }, "more": { "type": "integer", "description": "How many changes beyond the first 300 are left out." } } }, "example": { "fromVersion": 38, "toVersion": null, "changes": [ { "section": "pages", "kind": "visual", "id": "8c1f0b7e-2d1a-4c55-9a0e-5b7f0e1d2c3a", "name": "Revenue by month", "pageId": "34432e64-7f1e-43b7-8a6c-bdb0926d0577", "change": "changed", "keys": [ "position" ] } ] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/reports/{report_id}/versions/{version}": { "get": { "operationId": "report_get_report_version_get", "summary": "Read a report version", "tags": [ "Reports" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "history", "model", "pages", "report" ], "description": "The report's definition document (GetReportDefinition) as it was at that version; with pageId, only that page and its filters.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "pageId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A page's pageId: only that page's versions and its filters (page Edit is enough)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "The report's definition document at that version (UnityReportDefinition), or with pageId {unityReportDefinition, pages: [that page], filters: [its filters]}." } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/reports/{report_id}/versions/{version}/restore": { "post": { "operationId": "report_restore_report_version_post", "summary": "Restore a report version", "tags": [ "Reports" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_view", "x-unity-reach": [ "history", "model", "pages", "report" ], "description": "Make the report, or one page with pageId (a deleted page too), equal to a saved version, with the checks a save makes. Version n is the report after change n: to undo a change, restore the version listed before it (GET /api/reports/{report_id}/versions); for one change inside a grouped entry, list the entry with expand and restore the version before that change. A dry run (dryRun true, the default) changes nothing and returns the changes, the warnings (what can't come back), expectedVersion and expectedWarnings; the restore (dryRun false) needs both and answers 409 version_conflict when the report or the warnings moved since, and 409 restore_failed when a section wouldn't come back as saved. Restoring the whole report deletes pages added after that version. A restore is a new version. Needs Edit access to the report, or to the page with pageId; a deleted page needs Edit access to the report.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageId": { "type": [ "string", "null" ], "description": "A page's pageId: only that page and its filters." }, "dryRun": { "type": "boolean" }, "expectedVersion": { "type": [ "integer", "null" ], "description": "expectedVersion from the dry run." }, "expectedWarnings": { "type": [ "string", "null" ], "description": "expectedWarnings from the dry run." } } }, "example": { "pageId": null, "dryRun": false, "expectedVersion": 42, "expectedWarnings": "3f9a1c0b7d2e4a65" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dryRun": { "type": "boolean" }, "applied": { "type": "boolean", "description": "Whether the restore changed anything (it made a version)." }, "reportVersion": { "type": "integer", "description": "The new version the restore made; absent when it changed nothing." }, "restoredFrom": { "type": "integer" }, "pageId": { "type": [ "string", "null" ], "format": "uuid" }, "expectedVersion": { "type": "integer" }, "expectedWarnings": { "type": "string" }, "changes": { "type": "array", "items": { "type": "object", "properties": { "section": { "type": "string", "enum": [ "report", "connections", "model", "pages", "filters" ] }, "kind": { "type": "string" }, "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "pageId": { "type": "string", "format": "uuid" }, "change": { "type": "string", "enum": [ "added", "removed", "changed" ] }, "keys": { "type": "array", "items": { "type": "string" } } } } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "connection_missing", "connection_access", "source_changed", "source_unread", "wont_compile", "field_missing", "visual_refused", "moved", "page_refused", "page_row_kept", "page_removed", "order", "filter_target", "filter_refused", "broken", "filter_defaults" ] }, "section": { "type": "string", "enum": [ "model", "pages", "filters" ] }, "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "text": { "type": "string", "description": "What stays out, or what happens, in one sentence." } } } }, "more": { "type": "integer", "description": "How many changes beyond the first 300 are left out." } } }, "example": { "dryRun": true, "restoredFrom": 38, "pageId": null, "expectedVersion": 42, "expectedWarnings": "3f9a1c0b7d2e4a65", "changes": [ { "section": "pages", "kind": "page", "id": "34432e64-7f1e-43b7-8a6c-bdb0926d0577", "name": "Draft", "pageId": "34432e64-7f1e-43b7-8a6c-bdb0926d0577", "change": "removed", "keys": [] } ], "warnings": [ { "code": "page_removed", "section": "pages", "id": "34432e64-7f1e-43b7-8a6c-bdb0926d0577", "name": "Draft", "text": "Page 'Draft' isn't in version 38, so the restore deletes it; it can be brought back from the deleted pages." } ] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/reports/{report_id}/visual-data": { "post": { "operationId": "visual_reads_batch_post", "summary": "Read visuals' data", "tags": [ "Visual data" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "model", "pages" ], "description": "Reads 1 to 40 saved visuals of one page, with saved report, page and visual filters applied. The response is NDJSON: one line per read as it completes, {\"key\": index in reads, \"status\": HTTP status, \"data\": payload}, then {\"done\": true}. A read still running after the synchronous wait has status 202 and data {readJob}; collect it with GET /api/read-jobs/{job_id}.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageId": { "type": "string", "description": "The page: its UUID or numeric ID." }, "reads": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "declarativeChart", "dataTable", "matrix", "dataCard" ] }, "id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "integer" } ], "description": "The visual's UUID (visualUid), or its legacy numeric ID." }, "options": { "type": "object", "properties": { "pageIndex": { "type": "integer", "default": 0, "description": "dataTable: zero-based page." }, "pageSize": { "type": "integer", "default": 50, "description": "dataTable rows per page." }, "includeTotal": { "type": "boolean", "description": "dataTable: count every row (total_rows)." }, "interactionFilters": { "type": "array", "items": { "type": "object", "properties": { "sourceVisualId": { "type": "string" }, "outputColumn": { "type": "string" }, "value": {} }, "required": [ "sourceVisualId", "outputColumn", "value" ] }, "maxItems": 20, "description": "Temporary selections (a click on another visual), applied on top of saved filters; not saved. Each names the clicked visual (sourceVisualId), a group output (outputColumn) and its value; Unity builds the filter from that visual's stored query and adds that visual's own visual filters." }, "matrixView": { "type": "object", "description": "matrix: the reader's expansion, sort and window." }, "includeEffectiveSql": { "type": "boolean", "description": "Return the SQL Unity ran (effective_sql)." } }, "description": "Per-read options. They cannot change the report, page or caller." } }, "required": [ "type", "id" ] }, "minItems": 1, "maxItems": 40 } }, "required": [ "pageId", "reads" ] }, "example": { "pageId": "678AE2F0-1469-489E-AE28-B729A0000E51", "reads": [ { "type": "declarativeChart", "id": "3976903A-10E2-4861-B202-A29CF2BD7531" }, { "type": "dataTable", "id": "755B3D02-0153-4031-BE24-73E1DB250E5B", "options": { "pageIndex": 0, "pageSize": 50 } } ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/x-ndjson": { "schema": { "type": "object", "properties": { "key": { "type": "integer" }, "status": { "type": "integer" }, "data": { "type": "object", "properties": { "visualUid": { "type": "string", "format": "uuid" }, "revision": { "type": "string" }, "sql_data": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "array", "items": {} } }, "column_metadata": { "type": "array", "items": { "$ref": "#/components/schemas/ColumnMetadata" } } } }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "group", "value" ] }, "fieldUid": { "type": "string" }, "grain": { "type": "string" }, "aggregation": { "type": "string" }, "canonicalType": { "type": "string" }, "formatString": { "type": "string" } } }, "description": "The query's outputs: groups, then values, with the result's types." }, "generatedSql": { "type": "string", "description": "The SQL the visual query compiles to (read-only)." }, "filtersNotApplied": { "type": "array", "items": { "type": "object", "properties": { "filterUid": { "type": [ "string", "null" ], "description": "null for a click." }, "label": { "type": "string" }, "reason": { "type": "string", "description": "noPath: no relationship path joins the filter's field to this visual's tables; ambiguousPath: two equally short paths join it to one of them." } } }, "description": "The filters that don't reach this visual." }, "effective_sql": { "type": "string" }, "page_index": { "type": "integer" }, "page_size": { "type": "integer" }, "total_rows": { "type": [ "integer", "null" ] }, "seek_token": { "type": [ "string", "null" ] } } }, "done": { "type": "boolean" } }, "description": "One NDJSON line." }, "example": { "key": 0, "status": 200, "data": { "visualUid": "3976903A-10E2-4861-B202-A29CF2BD7531", "sql_data": { "columns": [ "Category", "Spend" ], "rows": [ [ "Groceries", "27711.43" ] ], "column_metadata": [ { "name": "Spend", "type_code": "DECIMAL(38,2)", "valueEncoding": "decimal-string" } ] } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/reports/{report_id}/workspace": { "get": { "operationId": "report_get_report_workspace_get", "summary": "Read a report workspace", "tags": [ "Reports" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "chat", "model", "pages", "report" ], "description": "The report's name, the caller's access, its pages (both page IDs, kind, visibility and canvas) and its attached connections. Start here after choosing a report. contentEdit is true when the caller's View share is Edit content (they can also save text through the report's HTML pages); accessLevel stays View.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "reportName": { "type": "string" }, "hasPermission": { "type": "boolean" }, "accessLevel": { "type": "string" }, "contentEdit": { "type": "boolean" }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspacePage" } }, "connections": { "type": "array", "items": { "type": "object", "description": "An attached connection: connectionId, name, serverType." } } } }, "example": { "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82", "reportName": "Sales overview", "hasPermission": true, "accessLevel": "Owner", "connections": [], "pages": [ { "PageID": 888, "PageUID": "34432E64-7F1E-43B7-8A6C-BDB0926D0577", "PageName": "Page 1", "PageKind": "report", "Hidden": false, "lockedViewport": null } ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/scatterPlots/update": { "put": { "operationId": "visuals_update_scatterplot_put", "summary": "Update a scatter plot", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/update.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/scatterplots/data": { "get": { "operationId": "visual_compat_data_scatterplots_get", "summary": "Read a chart preset's data", "tags": [ "Chart preset routes (compatibility)" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "model", "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/reports/{report_id}/visual-data.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/scatterplots/delete": { "delete": { "operationId": "visual_compat_delete_scatterplots_delete", "summary": "Delete a chart preset", "tags": [ "Chart preset routes (compatibility)" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/delete.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/shapes/add": { "post": { "operationId": "manual_visuals_add_shape_post", "summary": "Add a shape", "tags": [ "Text boxes and shapes (compatibility)" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/create with type shape.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/shapes/delete": { "delete": { "operationId": "manual_visuals_delete_shape_delete", "summary": "Delete a shape", "tags": [ "Text boxes and shapes (compatibility)" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/delete.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/shapes/update": { "put": { "operationId": "manual_visuals_update_shape_put", "summary": "Update a shape", "tags": [ "Text boxes and shapes (compatibility)" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/update.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/sql/delete-query/{query_id}": { "delete": { "operationId": "sql_playground_delete_query_delete", "summary": "Delete a saved query", "tags": [ "SQL" ], "x-unity-scope": "workspace:write", "x-unity-access": "account", "x-unity-reach": [ "source" ], "parameters": [ { "name": "query_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/api/sql/execute": { "post": { "operationId": "sql_playground_execute_sql_post", "summary": "Run report SQL", "tags": [ "SQL" ], "x-unity-scope": "workspace:read", "x-unity-access": "account", "x-unity-reach": [ "source" ], "description": "Runs one read-only DuckDB query over the report's whole model: every entity of every source, joins across sources, model fields and measures (t.\"Total Spend\"). Name each entity by its entity key alone, as the model lists it, with no schema (FROM dbo_transactions); case is ignored. Writes, commands and multiple statements are refused. Unity adds LIMIT rowLimit when the outermost query has none. Saved report filters do not apply here.\n\nA read still running after the synchronous wait answers 202 with {readJob}: poll GET /api/read-jobs/{job_id}.\n\nA name that is not in the model answers 400 naming it and the closest entity keys. A table name, display name or schema-qualified name is not a name.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid" }, "sqlQuery": { "type": "string", "description": "Report SQL (DuckDB)." }, "rowLimit": { "type": "integer", "default": 1000, "minimum": 1, "description": "Rows to return when the query has no LIMIT of its own." }, "skipLimit": { "type": "boolean", "default": false, "description": "Return every row (within Unity's result bound) instead of rowLimit." }, "connectionId": { "type": "integer", "description": "Compatibility hint; the report model decides the sources." } }, "required": [ "reportId", "sqlQuery" ] }, "example": { "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82", "sqlQuery": "SELECT c.region, COUNT(*) AS n, t.\"Total Spend\" AS spend FROM dbo_transactions t JOIN dbo_customers c ON c.customer_id = t.customer_id GROUP BY 1 ORDER BY 1", "rowLimit": 100 } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResult" }, "example": { "columns": [ "region", "n", "spend" ], "rows": [ [ "East", 71, "14520.11" ] ], "column_metadata": [ { "name": "region", "type_code": "VARCHAR", "valueEncoding": "string" }, { "name": "n", "type_code": "BIGINT", "valueEncoding": "big-integer" }, { "name": "spend", "type_code": "DECIMAL(38,2)", "valueEncoding": "decimal-string" } ], "limitApplied": true, "rowLimit": 100 } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/api/sql/save-query": { "post": { "operationId": "sql_playground_save_query_post", "summary": "Save a query", "tags": [ "SQL" ], "x-unity-scope": "workspace:write", "x-unity-access": "account", "x-unity-reach": [ "source" ], "description": "Keeps a named query with a report, in your saved queries (SQL Playground).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sqlQuery": { "type": "string" } }, "required": [ "reportId", "name", "sqlQuery" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/sql/saved-queries": { "get": { "operationId": "sql_playground_get_saved_queries_get", "summary": "List saved queries", "tags": [ "SQL" ], "x-unity-scope": "workspace:read", "x-unity-access": "account", "x-unity-reach": [ "source" ], "description": "Your saved queries across reports, newest first.", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "sqlQuery": { "type": "string" }, "reportId": { "type": "string", "format": "uuid" }, "reportName": { "type": "string" }, "createdAt": { "type": "string" } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/textboxes/add": { "post": { "operationId": "manual_visuals_add_textbox_post", "summary": "Add a text box", "tags": [ "Text boxes and shapes (compatibility)" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/create with type textBox.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/textboxes/delete": { "delete": { "operationId": "manual_visuals_delete_textbox_delete", "summary": "Delete a text box", "tags": [ "Text boxes and shapes (compatibility)" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/delete.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/textboxes/update": { "put": { "operationId": "manual_visuals_update_textbox_put", "summary": "Update a text box", "tags": [ "Text boxes and shapes (compatibility)" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "deprecated": true, "description": "Compatibility route; use POST /api/visuals/update.", "responses": { "200": { "description": "Success." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/visuals/capabilities": { "get": { "operationId": "visuals_get_visual_capabilities_get", "summary": "Read visual capabilities", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:read", "x-unity-access": "account", "x-unity-reach": [ "docs" ], "description": "Without kind: the native kinds and their purpose. With kind (repeat for up to three): the exact JSON Schemas for a definition, its changes and its appearance, plus rendering semantics and the renderer guide. Build create and update bodies from these.", "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "declarativeChart", "dataTable", "matrix", "dataCard", "textBox", "shape" ], "description": "Native visual kind. Chart presets (bar, line, scatter, pie) are declarativeChart specifications; an older name (barGraph, pieChart, ...) is refused with the current kind." } }, "example": [ "declarativeChart" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "type": "integer" }, "kinds": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/api/visuals/copy": { "post": { "operationId": "visuals_copy_visual_selection_post", "summary": "Copy a visual", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "description": "Copies a visual (definition, appearance and filters) to a page of the same report.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "type": { "type": "string", "enum": [ "declarativeChart", "dataTable", "matrix", "dataCard", "textBox", "shape" ], "description": "Native visual kind. Chart presets (bar, line, scatter, pie) are declarativeChart specifications; an older name (barGraph, pieChart, ...) is refused with the current kind." }, "id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "integer" } ], "description": "The visual's UUID (visualUid), or its legacy numeric ID." }, "pageId": { "type": "string", "description": "The page: its UUID or numeric ID." }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "zIndex": { "type": "integer" } }, "description": "Logical canvas pixels on the page (default page 1280x720). Omitted: Unity finds free space." } }, "required": [ "reportId", "type", "id", "pageId" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": {}, "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "pageId": { "type": "integer" }, "visual": { "$ref": "#/components/schemas/VisualState" }, "mutation": { "type": "object", "properties": { "applied": { "type": "boolean" }, "persisted": { "type": "boolean" }, "mode": { "type": "string" }, "revision": { "type": "string" }, "visualUid": { "type": "string", "format": "uuid" }, "target": { "type": "object", "properties": { "page_id": { "type": "integer" }, "visual_id": { "type": "string" }, "visual_type": { "type": "string" } } } } }, "change": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" } } } }, "/api/visuals/create": { "post": { "operationId": "visuals_create_native_visual_post", "summary": "Create a visual", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "description": "Validates the definition and its query against the report model and the kind's rules, saves it on the page and returns the receipt. Text boxes and shapes need no query.\n\nA query or presentation that breaks a rule answers 422 with one sentence and its code (invalid_query, unknown_field, or legacy_sql for a visual saved as SQL).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "type": { "type": "string", "enum": [ "declarativeChart", "dataTable", "matrix", "dataCard", "textBox", "shape" ], "description": "Native visual kind. Chart presets (bar, line, scatter, pie) are declarativeChart specifications; an older name (barGraph, pieChart, ...) is refused with the current kind." }, "pageId": { "type": "string", "description": "The page: its UUID or numeric ID." }, "definition": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 1000 }, "query": { "type": "object", "description": "Groups and values naming model fields by fieldUid (InspectDataModel). A value is a measure, or a column with an aggregation. Tables combine only through model relationships. Output names are the result's column names.", "properties": { "groups": { "type": [ "array", "null" ], "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "name", "field" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "Output column name, unique ignoring case; presentation binds to it." }, "field": { "type": "string", "minLength": 1, "description": "fieldUid from InspectDataModel." }, "grain": { "type": [ "string", "null" ], "enum": [ "year", "quarter", "month", "week", "day", null ], "description": "A date or datetime field truncated to this period." } } } }, "values": { "type": [ "array", "null" ], "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "name", "field" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "Output column name, unique ignoring case; presentation binds to it." }, "field": { "type": "string", "minLength": 1, "description": "fieldUid from InspectDataModel." }, "aggregation": { "type": [ "string", "null" ], "enum": [ "sum", "avg", "min", "max", "count", "countDistinct", null ], "description": "For a column or calculated field; a measure takes none. count counts non-null values, so count of a key column counts rows; countDistinct counts distinct values, a blank as one, as Power BI's Count (Distinct)." } } } }, "sort": { "type": [ "array", "null" ], "description": "Output names in order; every group is added as a tiebreak.", "items": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "Output column name, unique ignoring case; presentation binds to it." }, "direction": { "type": [ "string", "null" ], "enum": [ "asc", "desc", null ] } } } }, "top": { "type": [ "object", "null" ], "description": "Keep the count members of a group ranked by a value; totals cover the kept members.", "additionalProperties": false, "required": [ "group", "count", "by" ], "properties": { "group": { "type": "string", "minLength": 1, "description": "Output column name, unique ignoring case; presentation binds to it." }, "count": { "type": "integer", "minimum": 1 }, "by": { "type": "string", "minLength": 1, "description": "Output column name, unique ignoring case; presentation binds to it." }, "direction": { "type": [ "string", "null" ], "enum": [ "asc", "desc", null ] } } } }, "additionalProperties": false }, "rendererSpec": { "type": "object", "description": "declarativeChart: a Vega-Lite specification over the query's output names (data is supplied by Unity). Channel sorts such as \"-x\" are accepted." }, "matrixSpec": { "type": "object", "description": "matrix: labels, formats and widths of its rows (the query's groups, in order) and measures (its values, in order) by output name, and options." }, "columnConfig": { "type": "object", "description": "dataTable: column widths, visibility and alignment, by output name; the columns are the query's outputs in query order." }, "customization": { "type": "object", "description": "Appearance (the kind's appearance schema); omit for Unity's defaults." }, "subtitle": { "type": "string", "description": "dataCard." }, "shapeType": { "type": "string", "description": "shape: rectangle, ellipse, line, ..." }, "text": { "type": "string", "description": "textBox: its text (alias of title)." } }, "description": "Per kind: GET /api/visuals/capabilities?kind={kind} returns the exact definition, changes and appearance schemas, required fields and rendering semantics." }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "zIndex": { "type": "integer" } }, "description": "Logical canvas pixels on the page (default page 1280x720). Omitted: Unity finds free space." } }, "required": [ "reportId", "type", "pageId", "definition" ] }, "example": { "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82", "type": "declarativeChart", "pageId": "678AE2F0-1469-489E-AE28-B729A0000E51", "definition": { "title": "Spend by category", "query": { "groups": [ { "name": "Category", "field": "col_6f1c0d2a9b8e4f3a8c7d6e5f4a3b2c1d" } ], "values": [ { "name": "Spend", "field": "fld_0a1b2c3d4e5f60718293a4b5c6d7e8f9" } ], "sort": [ { "name": "Spend", "direction": "desc" } ] }, "rendererSpec": { "mark": { "type": "bar", "cornerRadiusEnd": 3 }, "encoding": { "x": { "field": "Spend", "type": "quantitative" }, "y": { "field": "Category", "type": "nominal", "sort": "-x", "title": null } } } }, "position": { "x": 24, "y": 24, "width": 600, "height": 320 } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "persisted": { "type": "boolean" }, "visualUid": { "type": "string", "format": "uuid" }, "visual_id": { "type": "string" }, "visual_type": { "type": "string" }, "visual": { "$ref": "#/components/schemas/VisualState" }, "mutation": { "type": "object", "properties": { "applied": { "type": "boolean" }, "persisted": { "type": "boolean" }, "mode": { "type": "string" }, "revision": { "type": "string" }, "visualUid": { "type": "string", "format": "uuid" }, "target": { "type": "object", "properties": { "page_id": { "type": "integer" }, "visual_id": { "type": "string" }, "visual_type": { "type": "string" } } } } }, "change": { "type": "object", "properties": { "before": { "type": [ "object", "null" ], "properties": { "id": {}, "type": { "type": "string" }, "visualUid": { "type": "string", "format": "uuid" }, "pageId": { "type": "integer" }, "revision": { "type": "string" } } }, "after": { "type": [ "object", "null" ], "properties": { "id": {}, "type": { "type": "string" }, "visualUid": { "type": "string", "format": "uuid" }, "pageId": { "type": "integer" }, "revision": { "type": "string" } } } }, "description": "The visual before and after the change (null: created, deleted), for the tabs that show it." }, "layout": { "type": "object", "description": "Geometry feedback: canvasBounds, fitsWithinPage, overflowPixels, overlaps." }, "warnings": { "type": "array", "items": { "type": "object" } }, "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "visual_data": { "type": "object", "description": "The saved definition and, for charts and cards, the first read (sql_data, outputs, generatedSql)." } }, "description": "A visual change receipt. The change is one report version: GET /api/reports/{reportId}/versions lists it, and restoring the version listed before it brings the visual back as it was." } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" } } } }, "/api/visuals/delete": { "post": { "operationId": "visuals_delete_native_visual_post", "summary": "Delete a visual", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "description": "Deletes one visual. Restoring the report version listed before the delete brings it back.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "type": { "type": "string", "enum": [ "declarativeChart", "dataTable", "matrix", "dataCard", "textBox", "shape" ], "description": "Native visual kind. Chart presets (bar, line, scatter, pie) are declarativeChart specifications; an older name (barGraph, pieChart, ...) is refused with the current kind." }, "id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "integer" } ], "description": "The visual's UUID (visualUid), or its legacy numeric ID." }, "expectedRevision": { "type": "string" }, "clientRequestId": { "type": "string", "maxLength": 64, "description": "Retry key, a UUID or any string up to 64 characters. A retry of a committed request writes nothing and answers the first attempt's outcome with replayed true; the same key with a different body answers 409." } }, "required": [ "reportId", "type", "id" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "persisted": { "type": "boolean" }, "visualUid": { "type": "string", "format": "uuid" }, "visual_id": { "type": "string" }, "visual_type": { "type": "string" }, "visual": { "$ref": "#/components/schemas/VisualState" }, "mutation": { "type": "object", "properties": { "applied": { "type": "boolean" }, "persisted": { "type": "boolean" }, "mode": { "type": "string" }, "revision": { "type": "string" }, "visualUid": { "type": "string", "format": "uuid" }, "target": { "type": "object", "properties": { "page_id": { "type": "integer" }, "visual_id": { "type": "string" }, "visual_type": { "type": "string" } } } } }, "change": { "type": "object", "properties": { "before": { "type": [ "object", "null" ], "properties": { "id": {}, "type": { "type": "string" }, "visualUid": { "type": "string", "format": "uuid" }, "pageId": { "type": "integer" }, "revision": { "type": "string" } } }, "after": { "type": [ "object", "null" ], "properties": { "id": {}, "type": { "type": "string" }, "visualUid": { "type": "string", "format": "uuid" }, "pageId": { "type": "integer" }, "revision": { "type": "string" } } } }, "description": "The visual before and after the change (null: created, deleted), for the tabs that show it." }, "layout": { "type": "object", "description": "Geometry feedback: canvasBounds, fitsWithinPage, overflowPixels, overlaps." }, "warnings": { "type": "array", "items": { "type": "object" } }, "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "visual_data": { "type": "object", "description": "The saved definition and, for charts and cards, the first read (sql_data, outputs, generatedSql)." } }, "description": "A visual change receipt. The change is one report version: GET /api/reports/{reportId}/versions lists it, and restoring the version listed before it brings the visual back as it was." } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/api/visuals/delete-batch": { "post": { "operationId": "visuals_delete_visual_selection_post", "summary": "Delete several visuals", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "description": "Deletes 1 to 100 visuals in one transaction.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "targets": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "declarativeChart", "dataTable", "matrix", "dataCard", "textBox", "shape" ], "description": "Native visual kind. Chart presets (bar, line, scatter, pie) are declarativeChart specifications; an older name (barGraph, pieChart, ...) is refused with the current kind." }, "id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "integer" } ], "description": "The visual's UUID (visualUid), or its legacy numeric ID." } } }, "minItems": 1, "maxItems": 100 }, "clientRequestId": { "type": "string", "maxLength": 64, "description": "Retry key, a UUID or any string up to 64 characters. A retry of a committed request writes nothing and answers the first attempt's outcome with replayed true; the same key with a different body answers 409." } }, "required": [ "reportId", "targets" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "receipts": { "type": "array", "items": { "type": "object", "properties": { "persisted": { "type": "boolean" }, "visualUid": { "type": "string", "format": "uuid" }, "visual_id": { "type": "string" }, "visual_type": { "type": "string" }, "visual": { "$ref": "#/components/schemas/VisualState" }, "mutation": { "type": "object", "properties": { "applied": { "type": "boolean" }, "persisted": { "type": "boolean" }, "mode": { "type": "string" }, "revision": { "type": "string" }, "visualUid": { "type": "string", "format": "uuid" }, "target": { "type": "object", "properties": { "page_id": { "type": "integer" }, "visual_id": { "type": "string" }, "visual_type": { "type": "string" } } } } }, "change": { "type": "object", "properties": { "before": { "type": [ "object", "null" ], "properties": { "id": {}, "type": { "type": "string" }, "visualUid": { "type": "string", "format": "uuid" }, "pageId": { "type": "integer" }, "revision": { "type": "string" } } }, "after": { "type": [ "object", "null" ], "properties": { "id": {}, "type": { "type": "string" }, "visualUid": { "type": "string", "format": "uuid" }, "pageId": { "type": "integer" }, "revision": { "type": "string" } } } }, "description": "The visual before and after the change (null: created, deleted), for the tabs that show it." }, "layout": { "type": "object", "description": "Geometry feedback: canvasBounds, fitsWithinPage, overflowPixels, overlaps." }, "warnings": { "type": "array", "items": { "type": "object" } }, "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "visual_data": { "type": "object", "description": "The saved definition and, for charts and cards, the first read (sql_data, outputs, generatedSql)." } }, "description": "A visual change receipt. The change is one report version: GET /api/reports/{reportId}/versions lists it, and restoring the version listed before it brings the visual back as it was." }, "description": "One receipt per visual." } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" } } } }, "/api/visuals/page-state": { "get": { "operationId": "visuals_inspect_page_visual_state_get", "summary": "Read every visual on a page", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "pages" ], "description": "All saved visuals of one page and the page's visualsRevision (compare it with GET /api/reports/{report_id}/live to know when to re-read).", "parameters": [ { "name": "reportId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Report ID. Also accepted as report_id.", "x-aliases": [ "report_id" ] }, { "name": "pageId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The page: its UUID or numeric ID. Also accepted as page_id, pageUid.", "x-aliases": [ "page_id", "pageUid" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "pageId": { "type": "integer" }, "pageUid": { "type": "string", "format": "uuid" }, "visualsRevision": { "type": "string" }, "visuals": { "type": "array", "items": { "$ref": "#/components/schemas/VisualState" } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "422": { "$ref": "#/components/responses/E422" } } } }, "/api/visuals/positions": { "post": { "operationId": "visuals_save_visual_positions_post", "summary": "Move and resize visuals", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "description": "Saves 1 to 100 visuals' positions and z-order in one transaction.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "targets": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "declarativeChart", "dataTable", "matrix", "dataCard", "textBox", "shape" ], "description": "Native visual kind. Chart presets (bar, line, scatter, pie) are declarativeChart specifications; an older name (barGraph, pieChart, ...) is refused with the current kind." }, "id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "integer" } ], "description": "The visual's UUID (visualUid), or its legacy numeric ID." }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "zIndex": { "type": "integer" } }, "description": "Logical canvas pixels on the page (default page 1280x720). Omitted: Unity finds free space." } } }, "minItems": 1, "maxItems": 100 }, "clientRequestId": { "type": "string", "maxLength": 64, "description": "Retry key, a UUID or any string up to 64 characters. A retry of a committed request writes nothing and answers the first attempt's outcome with replayed true; the same key with a different body answers 409." } }, "required": [ "reportId", "targets" ] }, "example": { "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82", "targets": [ { "type": "declarativeChart", "id": "3976903A-10E2-4861-B202-A29CF2BD7531", "position": { "x": 24, "y": 24, "width": 620, "height": 320 } } ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "receipts": { "type": "array", "items": { "type": "object", "properties": { "persisted": { "type": "boolean" }, "visualUid": { "type": "string", "format": "uuid" }, "visual_id": { "type": "string" }, "visual_type": { "type": "string" }, "visual": { "$ref": "#/components/schemas/VisualState" }, "mutation": { "type": "object", "properties": { "applied": { "type": "boolean" }, "persisted": { "type": "boolean" }, "mode": { "type": "string" }, "revision": { "type": "string" }, "visualUid": { "type": "string", "format": "uuid" }, "target": { "type": "object", "properties": { "page_id": { "type": "integer" }, "visual_id": { "type": "string" }, "visual_type": { "type": "string" } } } } }, "change": { "type": "object", "properties": { "before": { "type": [ "object", "null" ], "properties": { "id": {}, "type": { "type": "string" }, "visualUid": { "type": "string", "format": "uuid" }, "pageId": { "type": "integer" }, "revision": { "type": "string" } } }, "after": { "type": [ "object", "null" ], "properties": { "id": {}, "type": { "type": "string" }, "visualUid": { "type": "string", "format": "uuid" }, "pageId": { "type": "integer" }, "revision": { "type": "string" } } } }, "description": "The visual before and after the change (null: created, deleted), for the tabs that show it." }, "layout": { "type": "object", "description": "Geometry feedback: canvasBounds, fitsWithinPage, overflowPixels, overlaps." }, "warnings": { "type": "array", "items": { "type": "object" } }, "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "visual_data": { "type": "object", "description": "The saved definition and, for charts and cards, the first read (sql_data, outputs, generatedSql)." } }, "description": "A visual change receipt. The change is one report version: GET /api/reports/{reportId}/versions lists it, and restoring the version listed before it brings the visual back as it was." }, "description": "One receipt per visual, in request order." } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" } } } }, "/api/visuals/preview": { "post": { "operationId": "visuals_preview_native_visual_post", "summary": "Preview a visual", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_data", "x-unity-reach": [ "model", "pages" ], "description": "Validates a definition and runs its query without saving anything: the result a create would produce. Use it to check a query, its outputs and a renderer specification.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "type": { "type": "string", "enum": [ "declarativeChart", "dataTable", "matrix", "dataCard", "textBox", "shape" ], "description": "Native visual kind. Chart presets (bar, line, scatter, pie) are declarativeChart specifications; an older name (barGraph, pieChart, ...) is refused with the current kind." }, "definition": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 1000 }, "query": { "type": "object", "description": "Groups and values naming model fields by fieldUid (InspectDataModel). A value is a measure, or a column with an aggregation. Tables combine only through model relationships. Output names are the result's column names.", "properties": { "groups": { "type": [ "array", "null" ], "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "name", "field" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "Output column name, unique ignoring case; presentation binds to it." }, "field": { "type": "string", "minLength": 1, "description": "fieldUid from InspectDataModel." }, "grain": { "type": [ "string", "null" ], "enum": [ "year", "quarter", "month", "week", "day", null ], "description": "A date or datetime field truncated to this period." } } } }, "values": { "type": [ "array", "null" ], "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "name", "field" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "Output column name, unique ignoring case; presentation binds to it." }, "field": { "type": "string", "minLength": 1, "description": "fieldUid from InspectDataModel." }, "aggregation": { "type": [ "string", "null" ], "enum": [ "sum", "avg", "min", "max", "count", "countDistinct", null ], "description": "For a column or calculated field; a measure takes none. count counts non-null values, so count of a key column counts rows; countDistinct counts distinct values, a blank as one, as Power BI's Count (Distinct)." } } } }, "sort": { "type": [ "array", "null" ], "description": "Output names in order; every group is added as a tiebreak.", "items": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "Output column name, unique ignoring case; presentation binds to it." }, "direction": { "type": [ "string", "null" ], "enum": [ "asc", "desc", null ] } } } }, "top": { "type": [ "object", "null" ], "description": "Keep the count members of a group ranked by a value; totals cover the kept members.", "additionalProperties": false, "required": [ "group", "count", "by" ], "properties": { "group": { "type": "string", "minLength": 1, "description": "Output column name, unique ignoring case; presentation binds to it." }, "count": { "type": "integer", "minimum": 1 }, "by": { "type": "string", "minLength": 1, "description": "Output column name, unique ignoring case; presentation binds to it." }, "direction": { "type": [ "string", "null" ], "enum": [ "asc", "desc", null ] } } } }, "additionalProperties": false }, "rendererSpec": { "type": "object", "description": "declarativeChart: a Vega-Lite specification over the query's output names (data is supplied by Unity). Channel sorts such as \"-x\" are accepted." }, "matrixSpec": { "type": "object", "description": "matrix: labels, formats and widths of its rows (the query's groups, in order) and measures (its values, in order) by output name, and options." }, "columnConfig": { "type": "object", "description": "dataTable: column widths, visibility and alignment, by output name; the columns are the query's outputs in query order." }, "customization": { "type": "object", "description": "Appearance (the kind's appearance schema); omit for Unity's defaults." }, "subtitle": { "type": "string", "description": "dataCard." }, "shapeType": { "type": "string", "description": "shape: rectangle, ellipse, line, ..." }, "text": { "type": "string", "description": "textBox: its text (alias of title)." } }, "description": "Per kind: GET /api/visuals/capabilities?kind={kind} returns the exact definition, changes and appearance schemas, required fields and rendering semantics." } }, "required": [ "reportId", "type", "definition" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "persisted": { "type": "boolean", "enum": [ false ] }, "sql_data": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "array", "items": {} } }, "column_metadata": { "type": "array", "items": { "$ref": "#/components/schemas/ColumnMetadata" } } } }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "group", "value" ] }, "fieldUid": { "type": "string" }, "grain": { "type": "string" }, "aggregation": { "type": "string" }, "canonicalType": { "type": "string" }, "formatString": { "type": "string" } } }, "description": "The query's outputs: groups, then values, with the result's types." }, "generatedSql": { "type": "string", "description": "The SQL the visual query compiles to (read-only)." }, "rendererSpec": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" } } } }, "/api/visuals/state": { "get": { "operationId": "visuals_inspect_native_visual_get", "summary": "Read a visual", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:read", "x-unity-access": "page_view", "x-unity-reach": [ "pages" ], "description": "A saved visual's authored state (its visual query), its outputs and generatedSql, position and revision, with both page IDs.", "parameters": [ { "name": "reportId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Report ID. Also accepted as report_id.", "x-aliases": [ "report_id" ] }, { "name": "type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "declarativeChart", "dataTable", "matrix", "dataCard", "textBox", "shape" ] }, "description": "Native visual kind. Chart presets (bar, line, scatter, pie) are declarativeChart specifications; an older name (barGraph, pieChart, ...) is refused with the current kind." }, { "name": "id", "in": "query", "required": true, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "integer" } ] }, "description": "The visual's UUID (visualUid), or its legacy numeric ID." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisualState" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "422": { "$ref": "#/components/responses/E422" } } } }, "/api/visuals/update": { "post": { "operationId": "visuals_update_native_visual_post", "summary": "Update a visual", "tags": [ "Native visuals" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_edit", "x-unity-reach": [ "pages" ], "description": "Applies only the given changes (title, query, rendererSpec, customization, position, pageId to move it, ...). Send expectedRevision from the last read; a stale one answers 409 visual_conflict with currentRevision.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "type": { "type": "string", "enum": [ "declarativeChart", "dataTable", "matrix", "dataCard", "textBox", "shape" ], "description": "Native visual kind. Chart presets (bar, line, scatter, pie) are declarativeChart specifications; an older name (barGraph, pieChart, ...) is refused with the current kind." }, "id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "integer" } ], "description": "The visual's UUID (visualUid), or its legacy numeric ID." }, "changes": { "type": "object", "description": "Fields to change; GET /api/visuals/capabilities lists them per kind." }, "expectedRevision": { "type": "string", "description": "The revision you read, for example 0x000000000000c356." }, "refreshData": { "type": "boolean", "default": true, "description": "Return a fresh read." }, "clientRequestId": { "type": "string", "maxLength": 64, "description": "Retry key, a UUID or any string up to 64 characters. A retry of a committed request writes nothing and answers the first attempt's outcome with replayed true; the same key with a different body answers 409." } }, "required": [ "reportId", "type", "id", "changes" ] }, "example": { "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82", "type": "declarativeChart", "id": "3976903A-10E2-4861-B202-A29CF2BD7531", "expectedRevision": "0x000000000000c356", "changes": { "title": "Debit spend by category" }, "refreshData": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "persisted": { "type": "boolean" }, "visualUid": { "type": "string", "format": "uuid" }, "visual_id": { "type": "string" }, "visual_type": { "type": "string" }, "visual": { "$ref": "#/components/schemas/VisualState" }, "mutation": { "type": "object", "properties": { "applied": { "type": "boolean" }, "persisted": { "type": "boolean" }, "mode": { "type": "string" }, "revision": { "type": "string" }, "visualUid": { "type": "string", "format": "uuid" }, "target": { "type": "object", "properties": { "page_id": { "type": "integer" }, "visual_id": { "type": "string" }, "visual_type": { "type": "string" } } } } }, "change": { "type": "object", "properties": { "before": { "type": [ "object", "null" ], "properties": { "id": {}, "type": { "type": "string" }, "visualUid": { "type": "string", "format": "uuid" }, "pageId": { "type": "integer" }, "revision": { "type": "string" } } }, "after": { "type": [ "object", "null" ], "properties": { "id": {}, "type": { "type": "string" }, "visualUid": { "type": "string", "format": "uuid" }, "pageId": { "type": "integer" }, "revision": { "type": "string" } } } }, "description": "The visual before and after the change (null: created, deleted), for the tabs that show it." }, "layout": { "type": "object", "description": "Geometry feedback: canvasBounds, fitsWithinPage, overflowPixels, overlaps." }, "warnings": { "type": "array", "items": { "type": "object" } }, "reportId": { "type": "string", "format": "uuid", "description": "Report ID." }, "visual_data": { "type": "object", "description": "The saved definition and, for charts and cards, the first read (sql_data, outputs, generatedSql)." } }, "description": "A visual change receipt. The change is one report version: GET /api/reports/{reportId}/versions lists it, and restoring the version listed before it brings the visual back as it was." } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" } } } }, "/get-schema": { "post": { "operationId": "schema_bp_get_schema_post", "summary": "List a connection's tables again", "tags": [ "Schema discovery" ], "x-unity-scope": "workspace:write", "x-unity-access": "edit", "x-unity-reach": [ "source" ], "description": "Connects with the saved connection's settings and credentials and lists its tables and columns, through its connector, saving them as its discovery. The connection's owner, or an editor of reportId when the connection belongs to it. Create connections with POST /api/connections/add. No /api prefix.\n\nA source that needs the reader's own sign-in answers 409 with code source_auth_sign_in_required and a sourceAuth payload; sign in through the browser application.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connectionId": { "type": "integer", "description": "The connection whose tables to list." }, "reportId": { "type": "string", "format": "uuid" } }, "required": [ "connectionId" ] }, "example": { "connectionId": 42, "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "type": "object", "description": "Tables, each with its columns and types." }, "selectedSchema": { "type": "object" }, "connectionId": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/get-selected-schema/{report_id}": { "get": { "operationId": "schema_bp_get_selected_schema_get", "summary": "Read the selected schema of a report source", "tags": [ "Schema discovery" ], "x-unity-scope": "workspace:read", "x-unity-access": "view", "x-unity-reach": [ "model" ], "description": "The tables and columns selected for a source in this report. No /api prefix.", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connectionId", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "selectedSchema": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/health": { "get": { "operationId": "health_check_get", "summary": "Check service health", "tags": [ "Service" ], "x-unity-scope": "public", "x-unity-access": "public", "x-unity-reach": [ "platform" ], "description": "Answers while the web process is serving. It does not check the database or sources.", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy" ] } } }, "example": { "status": "healthy" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } }, "security": [] } }, "/mcp": { "post": { "operationId": "mcp_mcp_post_post", "summary": "Model Context Protocol endpoint", "tags": [ "Model Context Protocol" ], "x-unity-scope": "workspace:write", "x-unity-access": "page_view", "x-unity-reach": [ "docs", "files", "history", "model", "pages", "report", "source" ], "description": "Connect any MCP client (Claude, ChatGPT, Cursor, Grok, your own agent) to Unity: Streamable HTTP transport, one JSON-RPC message per POST, answered with JSON; no session. Authenticate with a Unity API key (Authorization: Bearer). tools/list returns the agent tools you may call; tools/call runs one with the same validation, access, receipts and versions as POST /api/reports/{report_id}/tools/{name} (images come back as image content). resources/list offers Unity's guides (unity://docs/{topic}) and this API's OpenAPI document. With ?reportId= the server is bound to that report; without it every tool takes reportId, and ListReports and CreateReport are added.\n\nA workspace:read key can list tools, read resources and call view tools; changing tools need workspace:write and Edit access on the report.\n\nClaude Code: claude mcp add --transport http unity https://api.x4tech.org/mcp --header \"Authorization: Bearer $UNITY_API_KEY\".", "parameters": [ { "name": "reportId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Bind the server to one report." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "description": "Request ID; omitted for notifications." }, "method": { "type": "string", "enum": [ "initialize", "ping", "tools/list", "tools/call", "resources/list", "resources/read", "resources/templates/list", "prompts/list", "notifications/initialized" ] }, "params": { "type": "object" } }, "required": [ "jsonrpc", "method" ] }, "example": { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "InspectReport", "arguments": { "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82", "query": "", "kind": "page", "pageId": null, "visualKeys": [], "detail": false, "offset": 0, "limit": 20 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string" }, "id": {}, "result": { "type": "object" }, "error": { "type": "object" } }, "description": "The JSON-RPC response; 202 with no body for a notification." } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } }, "get": { "operationId": "mcp_mcp_stream_get", "summary": "MCP server stream (not offered)", "tags": [ "Model Context Protocol" ], "x-unity-scope": "workspace:read", "x-unity-access": "account", "x-unity-reach": [ "docs" ], "description": "Answers 405: this server sends no server-initiated messages; every response comes on its POST.", "responses": { "405": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A personal Unity API key (Account menu, API access & sessions)." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "What went wrong, for a person or an agent to act on." }, "message": { "type": "string", "description": "The same text (every error carries both error and message)." }, "code": { "type": "string", "description": "A stable machine-readable code when the operation has one: insufficient_scope, edit_access_required, visual_conflict, model_conflict, filter_conflict, mutation_conflict, read_stopped, read_job_gone, chat_unavailable, subscription_required, missing_parameter, invalid_parameter, source_auth_sign_in_required, ..." }, "field": { "type": "string", "description": "The request field the error concerns, when there is one." } }, "required": [ "error" ], "description": "Every error response. Operations may add fields (currentRevision on a conflict)." }, "Viewport": { "type": "object", "properties": { "width": { "type": [ "integer", "null" ], "description": "Canvas width in logical pixels; null is the default 1280." }, "height": { "type": [ "integer", "null" ], "description": "Canvas height in logical pixels; null is the default 720." }, "backgroundColor": { "type": "string", "example": "#ffffff", "description": "Canvas color." }, "outerBackgroundColor": { "type": "string", "example": "#f5f5f5", "description": "Color around the canvas." } }, "description": "A report page's canvas size and colors." }, "ReportSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Report ID." }, "reportName": { "type": "string" }, "accessLevel": { "type": "string", "enum": [ "Owner", "Admin", "Edit", "View" ], "description": "The caller's access to the report." }, "contentEdit": { "type": "boolean", "description": "True for a View share that is Edit content: the person can also fill in the fields the report's HTML pages made saveable. Access decisions are View's; this only describes the share." }, "ownerFullName": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 UTC." }, "sourceCount": { "type": "integer", "description": "Data sources attached to the report." }, "deletion": { "type": "object", "description": "Present while the report is being deleted." } } }, "WorkspacePage": { "type": "object", "properties": { "PageID": { "type": "integer", "description": "Numeric page ID." }, "PageUID": { "type": "string", "format": "uuid", "description": "Stable page UUID." }, "PageName": { "type": "string" }, "PageKind": { "type": "string", "enum": [ "report", "html" ], "description": "report is a canvas of native visuals; html is an HTML page." }, "Hidden": { "type": "boolean", "description": "Hidden from viewers (editors still see it)." }, "accessLevel": { "type": "string", "enum": [ "EditContent" ], "description": "Present when the caller can save text through this HTML page's scripts without being able to edit it (Edit content on the page or on the report)." }, "lockedViewport": { "anyOf": [ { "$ref": "#/components/schemas/Viewport" }, { "type": "null" } ] } } }, "Page": { "type": "object", "properties": { "PageID": { "type": "integer", "description": "Numeric page ID." }, "PageUID": { "type": "string", "format": "uuid", "description": "Stable page UUID; every page parameter accepts either." }, "PageName": { "type": "string" }, "ReportID": { "type": "string", "format": "uuid" }, "PageLayout": { "type": "object", "description": "Saved layout: kind and lockedViewport." } } }, "Receipt": { "type": "object", "properties": { "resourceType": { "type": "string", "description": "What changed: page, visual, report-model, html, ..." }, "mutation": { "type": "object", "properties": { "applied": { "type": "boolean" }, "persisted": { "type": "boolean", "description": "Whether the change was saved." }, "mode": { "type": "string", "description": "The operation, for example create_page, rename_page, delete_page." } } }, "change": { "type": "object", "properties": { "before": { "type": [ "object", "null" ], "description": "What changed as it was (its identity); null for a creation." }, "after": { "type": [ "object", "null" ], "description": "As it is now; null for a deletion." } }, "description": "Which page or visual changed, for the tabs that show it." }, "reportVersion": { "type": "integer", "description": "Tool calls: the report version the change made (ListReportVersions)." } }, "description": "The record of one saved change; operations add their own fields (page, visual, model). Every saved change is a report version: GET /api/reports/{reportId}/versions lists them, and restoring the version listed before a change brings back the report as it was." }, "ColumnMetadata": { "type": "object", "properties": { "name": { "type": "string", "description": "Output column name." }, "type_code": { "type": "string", "description": "The engine's type, for example DECIMAL(38,2), BIGINT, VARCHAR, DATE." }, "type_name": { "type": "string" }, "precision": { "type": [ "integer", "null" ] }, "scale": { "type": [ "integer", "null" ] }, "valueEncoding": { "type": "string", "enum": [ "decimal-string", "integer", "big-integer", "number", "boolean", "string", "date", "time", "timestamp", "hex-string", "unknown" ], "description": "How this column's values are written in JSON. decimal-string: exact decimal text (\"15913.23\"), never a float; integer: a number (types of at most 32 bits); big-integer: a number within ±(2^53-1), else exact base-10 text (64-bit and wider); number: a float, null for NaN and infinities; date, time, timestamp: ISO 8601 text (offset-bearing timestamps in UTC); hex-string: binary." } } }, "QueryResult": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "string" }, "description": "Output column names, in order." }, "rows": { "type": "array", "items": { "type": "array", "items": {} }, "description": "Rows as arrays in column order. Read each column's valueEncoding." }, "column_metadata": { "type": "array", "items": { "$ref": "#/components/schemas/ColumnMetadata" } }, "limitApplied": { "type": "boolean", "description": "Whether Unity added a row limit (rowLimit)." }, "rowLimit": { "type": [ "integer", "null" ] } }, "description": "Rows of one read. Values stay exact: decimals are strings, see valueEncoding." }, "ReadJobAccepted": { "type": "object", "properties": { "readJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Pass to GET /api/read-jobs/{job_id}." }, "state": { "type": "string" }, "progress": { "type": "object", "description": "Rows read so far and, when known, the total." } }, "required": [ "id" ] } }, "required": [ "readJob" ], "description": "202 Accepted: the read continues past the synchronous wait (15 s by default). Poll the read job; its final response is this operation's response." }, "Filter": { "type": "object", "properties": { "filterUid": { "type": [ "string", "null" ], "description": "Null adds a filter; a filterUid changes that filter." }, "fieldUid": { "type": "string", "description": "The model field (InspectDataModel). Fixed once created." }, "kind": { "type": "string", "enum": [ "basic", "advanced", "relativeDate" ], "description": "basic: a checklist of values; advanced: one or two conditions; relativeDate: last, this or next N days, weeks, months, quarters or years, today in UTC. A measure takes advanced." }, "default": { "anyOf": [ { "type": "object", "properties": { "values": { "type": "array", "items": { "type": [ "string", "number", "boolean", "null" ] }, "description": "The values to keep; null is (Blank)." }, "exclude": { "type": "boolean", "description": "true keeps every value except these." } }, "required": [ "values", "exclude" ], "additionalProperties": false }, { "type": "object", "properties": { "conditions": { "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "is", "isNot", "contains", "doesNotContain", "startsWith", "doesNotStartWith", "isBlank", "isNotBlank", "lessThan", "lessThanOrEqual", "greaterThan", "greaterThanOrEqual" ], "description": "Text: is, isNot, contains, doesNotContain, startsWith, doesNotStartWith, isBlank, isNotBlank. Numbers, dates and measures: is, isNot, lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual, isBlank, isNotBlank. doesNotContain, doesNotStartWith and isBlank keep (Blank), which also stands for related rows with no row in the field's table. is, isNot and comparisons treat (Blank) as DAX does, as 0, empty text or the date 1899-12-30: lessThan 1970 keeps it, isNot 0 drops it. A measure filter's is, isNot and comparisons never keep a blank measure. On a date and time, is and isNot compare the day." }, "value": { "type": [ "string", "number", "null" ] } }, "required": [ "operator", "value" ], "additionalProperties": false } }, "join": { "type": [ "string", "null" ], "enum": [ "and", "or", null ], "description": "and or or with two conditions; null with one." } }, "required": [ "conditions", "join" ], "additionalProperties": false }, { "type": "object", "properties": { "when": { "type": "string", "enum": [ "last", "this", "next" ], "description": "last and next count whole units before or after the current one; this is the current one. Weeks start on Monday." }, "count": { "type": [ "integer", "null" ], "description": "1 to 1000 with last and next; null with this." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "quarter", "year" ] } }, "required": [ "when", "count", "unit" ], "additionalProperties": false }, { "type": "null" } ], "description": "The filter's value for its kind; null shows all." }, "locked": { "type": "boolean", "description": "Viewers can't change it." }, "hidden": { "type": "boolean", "description": "It applies, but viewers don't see it." }, "label": { "type": [ "string", "null" ], "description": "Null uses the field's name." } }, "required": [ "filterUid", "fieldUid", "kind", "default", "locked", "hidden", "label" ], "additionalProperties": false }, "VisualState": { "type": "object", "properties": { "storageVersion": { "type": "integer" }, "id": { "anyOf": [ { "type": "string" }, { "type": "integer" } ], "description": "Visual UUID (or legacy number)." }, "type": { "type": "string", "enum": [ "declarativeChart", "dataTable", "matrix", "dataCard", "textBox", "shape" ] }, "pageId": { "type": "integer", "description": "Numeric page ID." }, "pageUid": { "type": "string", "format": "uuid", "description": "Page UUID (state and page-state responses)." }, "revision": { "type": "string", "description": "Pass as expectedRevision to update; a stale revision answers 409 visual_conflict." }, "data": { "type": "object", "properties": { "title": { "type": "string" }, "query": { "type": [ "object", "null" ], "description": "The visual query; null for a visual saved before visual queries." }, "legacySql": { "type": "string", "description": "The SQL of a visual saved before visual queries, read-only, for rebuilding it. InspectFilters reads the filters that apply to it." }, "customization": { "type": [ "object", "null" ], "description": "Appearance (the kind's appearance schema)." }, "rendererSpec": { "type": "object", "description": "declarativeChart: the Vega-Lite specification." }, "matrixSpec": { "type": "object", "description": "matrix: rows, measures and hierarchy." }, "columnConfig": { "type": "object", "description": "dataTable: column labels, visibility and formats; the columns follow the query." }, "text": { "type": "string", "description": "textBox: its text (the same as title)." } }, "description": "Authored state." }, "config": { "type": "object", "properties": { "customization": { "type": [ "object", "null" ] } }, "description": "Read-only mirror of data.customization kept for older clients." }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "zIndex": { "type": "integer" } } } }, "description": "A saved native visual." }, "AgentRun": { "type": "object", "properties": { "run_id": { "type": "string", "format": "uuid" }, "client_request_id": { "type": [ "string", "null" ] }, "datachat_id": { "type": "integer" }, "report_id": { "type": "string", "format": "uuid" }, "mode": { "type": "string", "description": "data_chat." }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ] }, "phase": { "type": "string", "description": "Finer progress: queued, thinking, tool, answering, ..." }, "status_message": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "attempt_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "description": "One assistant run. Keep polling while queued or running." }, "UnityReportDefinition": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "unity://schemas/report-definition.json", "title": "Unity report definition", "description": "A Unity report as one JSON document (GetReportDefinition). Lists keep the report's own order where it means something (pages, tables, columns, bindings, registrations, canvas order); filters and connections are ordered by id; object keys are sorted. The same state always serializes to the same bytes. It never carries a connection's settings or credentials.", "type": "object", "additionalProperties": false, "required": [ "unityReportDefinition", "report", "connections", "model", "pages", "filters" ], "properties": { "unityReportDefinition": { "const": 1, "description": "The document's version." }, "report": { "type": "object", "additionalProperties": false, "required": [ "reportId", "name" ], "properties": { "reportId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "instructions": { "type": "string", "description": "The report's saved instructions for agents; absent when none." } } }, "connections": { "type": "array", "description": "The connections the model uses, by connectionId.", "items": { "type": "object", "additionalProperties": false, "required": [ "connectionId", "name", "type" ], "properties": { "connectionId": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": [ "string", "null" ], "description": "SQLServer, Snowflake, Databricks, AnalysisServices, API or file." } } } }, "model": { "type": "object", "additionalProperties": false, "required": [ "sources", "entities", "fields", "relationships" ], "properties": { "sources": { "type": "array", "description": "The connections the model reads, by connectionId.", "items": { "type": "object", "additionalProperties": false, "required": [ "connectionId" ], "properties": { "connectionId": { "type": "integer" }, "description": { "type": "string" }, "sourceMode": { "enum": [ "tables", "custom_sql" ], "description": "tables: entities read whole tables; custom_sql: authored queries." } } } }, "entities": { "type": "array", "description": "Tables, in model order: a source table (a connection's table or SQL) or a calculated table (DuckDB SQL over other tables).", "items": { "type": "object", "additionalProperties": false, "required": [ "entityUid", "kind", "name", "primaryKey" ], "properties": { "entityUid": { "type": "string" }, "kind": { "enum": [ "source", "calculated" ] }, "name": { "type": "string", "description": "The table's name in report queries." }, "label": { "type": "string" }, "description": { "type": "string" }, "connectionId": { "type": "integer", "description": "A source table's connection." }, "table": { "type": "string", "description": "A source table's table in its source." }, "sql": { "type": [ "string", "null" ], "description": "A source table's source SQL, or a calculated table's DuckDB SQL." }, "reads": { "type": "array", "items": { "type": "string" }, "description": "The tables a calculated table reads." }, "primaryKey": { "type": "array", "items": { "type": "string" }, "description": "fieldUids of the key columns." } } } }, "fields": { "type": "array", "description": "Every field, by table in model order: columns (a direct column's description included), calculated fields, SQL measures and typed measures.", "items": { "type": "object", "additionalProperties": false, "required": [ "fieldUid", "entityUid", "kind", "name" ], "properties": { "fieldUid": { "type": "string" }, "entityUid": { "type": [ "string", "null" ] }, "kind": { "enum": [ "column", "calculatedField", "sqlMeasure", "typedMeasure" ] }, "name": { "type": "string" }, "type": { "type": "string", "description": "The canonical type (string, integer, decimal, date, ...)." }, "nativeType": { "type": "string" }, "typeMetadata": { "type": "object" }, "description": { "type": "string" }, "expression": { "type": "string", "description": "A calculated field's or SQL measure's DuckDB expression." }, "measureKind": { "enum": [ "composite", "share", "timeComparison", "runningTotal", "rank" ] }, "spec": { "type": "object", "description": "A typed measure's spec; it names fields by fieldUid." }, "format": { "type": "object", "description": "A calculated field's or measure's number format, as its definition has it (SaveModelDefinition)." } } } }, "relationships": { "type": "array", "description": "Joins between tables, from a column (the many end) to a key column, by fieldUid.", "items": { "type": "object", "additionalProperties": false, "required": [ "fromField", "toField", "active" ], "properties": { "fromField": { "type": [ "string", "null" ] }, "toField": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "relationshipName": { "type": "string" }, "crossFilter": { "enum": [ "single", "both" ], "description": "single when absent: filters flow from the key end to the from end; both: each way." } } } } } }, "pages": { "type": "array", "description": "Every page, in tab order; the first is the page the report opens on.", "items": { "type": "object", "required": [ "pageId", "kind", "name" ], "properties": { "pageId": { "type": "string", "format": "uuid" }, "kind": { "enum": [ "native", "html" ] }, "name": { "type": "string" } }, "oneOf": [ { "properties": { "pageId": true, "name": true, "kind": { "const": "native" }, "layout": { "type": "object", "description": "The canvas: lockedViewport (width, height, colors)." }, "visuals": { "type": "array", "items": { "$ref": "#/$defs/visual" } } }, "required": [ "layout", "visuals" ], "additionalProperties": false }, { "properties": { "pageId": true, "name": true, "kind": { "const": "html" }, "html": { "type": "string", "description": "The page's HTML." }, "datasets": { "type": "array", "items": { "$ref": "#/$defs/dataset" } }, "visuals": { "type": "array", "items": { "$ref": "#/$defs/htmlVisual" } }, "elementIds": { "const": true, "description": "The page's HTML carries element identities (data-unity-id), kept across edits." }, "legacyFilters": { "description": "Filters saved in the page before the report's filters (filters), kept as stored." } }, "required": [ "html", "datasets", "visuals" ], "additionalProperties": false } ] } }, "filters": { "type": "array", "description": "The report's, pages' and visuals' filters by filterUid, as designed. People's own values are not report content.", "items": { "oneOf": [ { "$ref": "#/$defs/placedFilter" }, { "type": "object", "description": "A filter that can't be read: it was saved in an older form.", "additionalProperties": false, "required": [ "filterUid", "scope", "target", "broken" ], "properties": { "filterUid": { "type": "string" }, "scope": { "enum": [ "report", "page", "visual" ] }, "target": { "type": [ "string", "null" ] }, "broken": { "type": "string" } } } ] } } }, "$defs": { "visual": { "type": "object", "description": "A native visual, in canvas order.", "additionalProperties": false, "required": [ "visualUid", "kind", "position" ], "properties": { "visualUid": { "type": "string" }, "kind": { "enum": [ "declarativeChart", "dataTable", "matrix", "dataCard", "textBox", "shape" ] }, "title": { "type": "string" }, "position": { "type": "object", "additionalProperties": false, "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "zIndex": { "type": [ "integer", "null" ] } } }, "query": { "type": "object", "description": "The visual query (groups, values, sort, top), fields by fieldUid." }, "legacySql": { "type": "string", "description": "A visual saved before visual queries: its SQL, read-only." }, "appearance": { "type": "object", "description": "The kind's appearance settings." }, "subtitle": { "type": "string" }, "shapeType": { "type": "string" }, "rendererSpec": { "type": "object", "description": "A chart's Vega-Lite specification over the query's output names." }, "matrixSpec": { "type": "object", "description": "A matrix's presentation by output name." }, "columnConfig": { "type": "object", "description": "A table's columns (output name, width, visibility, alignment), sort and column filters." } } }, "dataset": { "type": "object", "description": "An HTML page's registered dataset.", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "query": { "type": [ "object", "null" ], "description": "The dataset's visual query." }, "paging": { "type": "boolean" }, "filters": { "type": "array", "description": "The dataset's own filters (fixed: each applies its default).", "items": { "oneOf": [ { "$ref": "#/$defs/datasetFilter" }, { "type": "object", "description": "A dataset filter that can't be read: it was saved in an older form (saved: as stored).", "additionalProperties": false, "required": [ "filterUid", "broken", "saved" ], "properties": { "filterUid": { "type": [ "string", "null" ] }, "broken": { "type": "string" }, "saved": {} } } ] } }, "legacySql": { "type": "string", "description": "A dataset saved before visual queries: its SQL, read-only." }, "connectionId": { "type": "integer", "description": "A legacySql dataset's connection." }, "columns": { "description": "A legacySql dataset's columns, as stored." }, "columnMetadata": { "description": "A legacySql dataset's column metadata, as stored." }, "fields": { "description": "A legacySql dataset's fields, as stored." } } }, "htmlVisual": { "type": "object", "description": "An HTML page's registered visual; dataIds are the datasets it is bound to, the first its default.", "additionalProperties": false, "required": [ "id", "dataIds" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "html": { "type": "string" }, "css": { "type": "string" }, "script": { "type": "string" }, "dataIds": { "type": "array", "items": { "type": "string" } }, "bindings": { "description": "Bindings saved before dataIds, kept as stored." }, "filters": { "description": "Filters saved on the visual before dataset filters, kept as stored." } } }, "placedFilter": { "type": "object", "properties": { "filterUid": { "type": [ "string", "null" ], "description": "Null adds a filter; a filterUid changes that filter." }, "fieldUid": { "type": "string", "description": "The model field (InspectDataModel). Fixed once created." }, "kind": { "type": "string", "enum": [ "basic", "advanced", "relativeDate" ], "description": "basic: a checklist of values; advanced: one or two conditions; relativeDate: last, this or next N days, weeks, months, quarters or years, today in UTC. A measure takes advanced." }, "default": { "anyOf": [ { "type": "object", "properties": { "values": { "type": "array", "items": { "type": [ "string", "number", "boolean", "null" ] }, "description": "The values to keep; null is (Blank)." }, "exclude": { "type": "boolean", "description": "true keeps every value except these." } }, "required": [ "values", "exclude" ], "additionalProperties": false }, { "type": "object", "properties": { "conditions": { "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "is", "isNot", "contains", "doesNotContain", "startsWith", "doesNotStartWith", "isBlank", "isNotBlank", "lessThan", "lessThanOrEqual", "greaterThan", "greaterThanOrEqual" ], "description": "Text: is, isNot, contains, doesNotContain, startsWith, doesNotStartWith, isBlank, isNotBlank. Numbers, dates and measures: is, isNot, lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual, isBlank, isNotBlank. doesNotContain, doesNotStartWith and isBlank keep (Blank), which also stands for related rows with no row in the field's table. is, isNot and comparisons treat (Blank) as DAX does, as 0, empty text or the date 1899-12-30: lessThan 1970 keeps it, isNot 0 drops it. A measure filter's is, isNot and comparisons never keep a blank measure. On a date and time, is and isNot compare the day." }, "value": { "type": [ "string", "number", "null" ] } }, "required": [ "operator", "value" ], "additionalProperties": false } }, "join": { "type": [ "string", "null" ], "enum": [ "and", "or", null ], "description": "and or or with two conditions; null with one." } }, "required": [ "conditions", "join" ], "additionalProperties": false }, { "type": "object", "properties": { "when": { "type": "string", "enum": [ "last", "this", "next" ], "description": "last and next count whole units before or after the current one; this is the current one. Weeks start on Monday." }, "count": { "type": [ "integer", "null" ], "description": "1 to 1000 with last and next; null with this." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "quarter", "year" ] } }, "required": [ "when", "count", "unit" ], "additionalProperties": false }, { "type": "null" } ], "description": "The filter's value for its kind; null shows all." }, "locked": { "type": "boolean", "description": "Viewers can't change it." }, "hidden": { "type": "boolean", "description": "It applies, but viewers don't see it." }, "label": { "type": [ "string", "null" ], "description": "Null uses the field's name." }, "scope": { "type": "string", "enum": [ "report", "page", "visual" ], "description": "report (target null), page (target: the page's pageId) or visual (target: visualUid). Fixed once created." }, "target": { "type": [ "string", "null" ] } }, "required": [ "filterUid", "fieldUid", "kind", "default", "locked", "hidden", "label", "scope", "target" ], "additionalProperties": false }, "datasetFilter": { "type": "object", "properties": { "filterUid": { "type": [ "string", "null" ], "description": "Null adds a filter; a filterUid changes that filter." }, "fieldUid": { "type": "string", "description": "The model field (InspectDataModel). Fixed once created." }, "kind": { "type": "string", "enum": [ "basic", "advanced", "relativeDate" ], "description": "basic: a checklist of values; advanced: one or two conditions; relativeDate: last, this or next N days, weeks, months, quarters or years, today in UTC. A measure takes advanced." }, "default": { "anyOf": [ { "type": "object", "properties": { "values": { "type": "array", "items": { "type": [ "string", "number", "boolean", "null" ] }, "description": "The values to keep; null is (Blank)." }, "exclude": { "type": "boolean", "description": "true keeps every value except these." } }, "required": [ "values", "exclude" ], "additionalProperties": false }, { "type": "object", "properties": { "conditions": { "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "is", "isNot", "contains", "doesNotContain", "startsWith", "doesNotStartWith", "isBlank", "isNotBlank", "lessThan", "lessThanOrEqual", "greaterThan", "greaterThanOrEqual" ], "description": "Text: is, isNot, contains, doesNotContain, startsWith, doesNotStartWith, isBlank, isNotBlank. Numbers, dates and measures: is, isNot, lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual, isBlank, isNotBlank. doesNotContain, doesNotStartWith and isBlank keep (Blank), which also stands for related rows with no row in the field's table. is, isNot and comparisons treat (Blank) as DAX does, as 0, empty text or the date 1899-12-30: lessThan 1970 keeps it, isNot 0 drops it. A measure filter's is, isNot and comparisons never keep a blank measure. On a date and time, is and isNot compare the day." }, "value": { "type": [ "string", "number", "null" ] } }, "required": [ "operator", "value" ], "additionalProperties": false } }, "join": { "type": [ "string", "null" ], "enum": [ "and", "or", null ], "description": "and or or with two conditions; null with one." } }, "required": [ "conditions", "join" ], "additionalProperties": false }, { "type": "object", "properties": { "when": { "type": "string", "enum": [ "last", "this", "next" ], "description": "last and next count whole units before or after the current one; this is the current one. Weeks start on Monday." }, "count": { "type": [ "integer", "null" ], "description": "1 to 1000 with last and next; null with this." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "quarter", "year" ] } }, "required": [ "when", "count", "unit" ], "additionalProperties": false }, { "type": "null" } ], "description": "The filter's value for its kind; null shows all." }, "hidden": { "type": "boolean", "description": "It applies, but viewers don't see it." }, "label": { "type": [ "string", "null" ], "description": "Null uses the field's name." } }, "required": [ "filterUid", "fieldUid", "kind", "default", "hidden", "label" ], "additionalProperties": false } } } }, "responses": { "E400": { "description": "Invalid parameters or input; the payload says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E401": { "description": "Missing, invalid, expired or revoked credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E403": { "description": "Insufficient token scope, report access, or subscription; a browser-only operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E404": { "description": "The resource does not exist or is not visible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E409": { "description": "A revision, request-ID or conversation conflict: re-read the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E413": { "description": "The request or result is larger than allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E415": { "description": "The file or media type is not supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E422": { "description": "The input is well formed but cannot be applied (definition, contract, query or identity).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E503": { "description": "A dependency is unavailable, or a data read was stopped (code read_stopped).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }