HTTP API reference

The Unity HTTP API gives your application access to reports, model metadata, queries, visuals, and assistant runs. Authenticate with a personal API key and use resource IDs discovered from the API.

Start with the API quickstart to create a key and set UNITY_API_BASE and UNITY_API_KEY. The examples here use the same environment variables. All example IDs, names, and results are illustrative.

Authentication

Send this header with every private request:

Authorization: Bearer YOUR_UNITY_API_KEY

Use Content-Type: application/json when sending a JSON body. A bearer client does not need a browser cookie or CSRF token. The verified account is derived from the key. Omit caller fields such as userId; if supplied, they must match the authenticated account.

workspace:read permits GET and HEAD workspace requests. workspace:write is required for other methods, including POST endpoints that only read data. Keys with write access include read access. Account and token management, sharing grants, collaboration administration, and billing require a browser session.

The hosted base URL is https://unityapp-backend.azurewebsites.net. Replace it with your backend's origin for other deployments. These routes currently expose Unity's application API; they are not a versioned /api/v1 contract. Check the runtime documentation when developing against a different release.

List reports

GET /api/reports · workspace:read

Returns reports accessible to the token's account. No query parameters are required. The response is an array, with an empty array when there are no accessible reports.

curl --fail-with-body "$UNITY_API_BASE/api/reports" \
  -H "Authorization: Bearer $UNITY_API_KEY"

Example response, with some fields omitted:

[
  {
    "id": "YOUR_REPORT_ID",
    "reportName": "Sales overview",
    "accessLevel": "Owner",
    "activeConnection": {
      "id": 123,
      "name": "Sales warehouse",
      "serverType": "SQLServer",
      "isActive": true
    }
  }
]

activeConnection can be null. The response also includes owner and creation metadata. Use the workspace endpoint to discover the report's full working context.

Retrieve a workspace

GET /api/reports/{report_id}/workspace · workspace:read

Returns the authorized workspace, including pages, connections, and report state used by the application. A report outside the caller's access is rejected; a key does not grant access to an arbitrary report ID.

The response contains reportId, reportName, hasPermission, accessLevel, pages, and connections. Each page includes a numeric PageID and a stable PageUID. Use the numeric PageID for the Data Chat endpoints below; HTML tools use the stable UUID. Preserve the exact field names expected by each operation.

curl --fail-with-body \
  "$UNITY_API_BASE/api/reports/$UNITY_REPORT_ID/workspace" \
  -H "Authorization: Bearer $UNITY_API_KEY"

Search report resources

GET /api/reports/{report_id}/catalog · workspace:read

Search pages, visuals, and connections without loading every visual's details. Add detail=true when you need expanded matches.

curl --fail-with-body --get \
  "$UNITY_API_BASE/api/reports/$UNITY_REPORT_ID/catalog" \
  -H "Authorization: Bearer $UNITY_API_KEY" \
  --data-urlencode "kind=visual" \
  --data-urlencode "query=revenue" \
  --data-urlencode "detail=true" \
  --data-urlencode "limit=10"

The response includes items, total, offset, complete, nextOffset, and missingVisualKeys, with status: "success" on a successful request. While complete is false, request the next page using offset=nextOffset. Preserve returned resource identifiers rather than guessing IDs from titles.

Discover the data model

GET /api/connection-models/{connection_id}/catalog · workspace:read

Inspect queryable model entities, fields, and relationships. Pass reportId when using a connection through a report, especially a shared report. Connection-owner access and report-attached access are checked separately.

curl --fail-with-body --get \
  "$UNITY_API_BASE/api/connection-models/$UNITY_CONNECTION_ID/catalog" \
  -H "Authorization: Bearer $UNITY_API_KEY" \
  --data-urlencode "reportId=$UNITY_REPORT_ID" \
  --data-urlencode "kind=field" \
  --data-urlencode "query=revenue" \
  --data-urlencode "limit=20"

Use identifiers from the response in model-scoped SQL. The selected table-and-column schema is also available at GET /get-selected-schema/{report_id}?connectionId={connection_id}. The /get-selected-schema path has no /api prefix.

Model results include items, total, offset, complete, nextOffset, modelRevision, snapshotVersion, and missingFieldUids. While complete is false, pass nextOffset as the next request's offset.

Execute SQL

POST /api/sql/execute · workspace:write

Runs a single read-only SQL query against an authorized connection. It validates the authored SQL and the SQL produced by model compilation. It does not accept database writes, commands, or multiple statements. A successful query returns data; it does not save a report visual.

Example request body, assuming an orders entity with region and amount fields:

{
  "reportId": "YOUR_REPORT_ID",
  "connectionId": 123,
  "sqlQuery": "SELECT region, SUM(amount) AS revenue FROM orders GROUP BY region ORDER BY region",
  "rowLimit": 5
}

Save your request body as query.json and submit it:

curl --fail-with-body "$UNITY_API_BASE/api/sql/execute" \
  -H "Authorization: Bearer $UNITY_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @query.json

The result contains columns, rows, column metadata when available, limitApplied, and rowLimit. Row values correspond to the column order. rowLimit can be null when Unity did not add a limit. Decimal results may be strings. Inspect HTTP status and the error payload before treating a response as data.

Use the rowLimit option instead of adding SQL Server TOP (n) solely for previewing. The current limit rewriter does not consistently recognize the parenthesized form and can reject the rewritten query. A model-scope error usually means a physical table name was used where the semantic entity name was expected. Re-read the catalogue before changing the query.

See the quickstart for equivalent Python and JavaScript requests.

Inspect and update visuals

Use GET /api/visuals/capabilities?kind={kind} to discover the accepted definition for a visual type. Use GET /api/visuals/state?reportId={report_id}&type={type}&id={id} to retrieve a saved visual's state and revision.

Omit kind to list the available visual kinds. Repeat the kind query parameter for full definitions of up to three kinds per request. The response includes a schemaVersion and the requested kinds.

Supported visual capabilities are discoverable from the endpoint; the native family includes bar graphs, line graphs, scatter plots, pie charts, data tables, data cards, text boxes, shapes, and declarative charts. HTML pages and HTML visuals have their own operations in the directory below.

An update uses POST /api/visuals/update with workspace:write and report editing permission. Inspect first, then pass the returned revision as expectedRevision so a stale update can be rejected.

Example body for a title edit. Replace the IDs and revision with inspected values:

{
  "reportId": "YOUR_REPORT_ID",
  "type": "barGraph",
  "id": 456,
  "expectedRevision": "0x0000000000000003",
  "changes": { "title": "Revenue by region" },
  "refreshData": false
}

Save this as visual-update.json, then submit it. This request changes the saved visual.

curl --fail-with-body "$UNITY_API_BASE/api/visuals/update" \
  -H "Authorization: Bearer $UNITY_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @visual-update.json

POST /api/visuals/create creates a visual from reportId, type, pageId, connectionId, definition, and position. Use the capability endpoint to construct the exact definition for that visual type. Do not reuse the agent tool's JSON-string parameters as an HTTP body: the HTTP adapter accepts objects such as definition and changes directly.

Successful mutations return their operation results or receipts. A 409 response with code: "visual_conflict" includes currentRevision; re-inspect and reconcile the change before retrying. Invalid definitions and output contracts can return 422.

Create an agent run

POST /api/agent/runs · workspace:write

Ask Unity's assistant to perform work in an existing Data Chat. The request is queued and returns 202 Accepted. The assistant can inspect, query, and edit according to your request and permissions. An analytical question can execute SQL; a request to build or edit can save report changes.

Create a conversation

Use GET /api/datachats?reportId={report_id}&pageId={page_id} to find chats on a page, or create one with POST /api/datachats/add:

{
  "reportId": "YOUR_REPORT_ID",
  "activePage": 789,
  "name": "API exploration"
}

activePage is the required page ID for this endpoint. The create response is 201 and contains the new DataChatID. The run endpoint uses that value in a field named dataChatId. The page and conversation must belong to the supplied report.

Request body

The endpoint also accepts application conversation, attachment, selection, and layout context. For a basic external integration, use a regular data_chat run as shown below. Read the runtime continuity and visual-editing guides before implementing the advanced conversation scopes.

This complete Node.js example creates a chat, submits a question, polls the run, and reads the resulting conversation events. Set UNITY_REPORT_ID and UNITY_PAGE_ID to IDs discovered from the workspace. The request creates a conversation and runs the assistant.

import { randomUUID } from "node:crypto";
import { setTimeout as delay } from "node:timers/promises";

const base = process.env.UNITY_API_BASE.replace(/\/$/, "");
const reportId = process.env.UNITY_REPORT_ID;
const pageId = Number(process.env.UNITY_PAGE_ID);

async function request(path, body) {
  const response = await fetch(base + path, {
    method: body === undefined ? "GET" : "POST",
    headers: {
      Authorization: `Bearer ${process.env.UNITY_API_KEY}`,
      ...(body === undefined ? {} : { "Content-Type": "application/json" }),
    },
    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
  });
  if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
  return response.json();
}

const chat = await request("/api/datachats/add", {
  reportId, activePage: pageId, name: "API exploration",
});
const accepted = await request("/api/agent/runs", {
  reportId,
  dataChatId: chat.DataChatID,
  user_input: "Inspect this report's data model and summarize what I can analyze. Do not edit the report.",
  mode: "data_chat",
  clientRequestId: randomUUID(),
});

const runId = accepted.run.run_id;
console.log("Run:", runId);
let run = accepted.run;
const deadline = Date.now() + 180_000;
while (["queued", "running"].includes(run.status) && Date.now() < deadline) {
  await delay(2000);
  ({ run } = await request(`/api/agent/runs/${runId}`));
}
console.log("Status:", run.status, run.error_message);
const feed = await request(`/api/agent/runs/${runId}/events?view=conversation&afterSequence=0`);
console.log(JSON.stringify(feed.events, null, 2));
// If still queued or running, resume polling with this runId later.
// The local deadline does not cancel the server-side run.

Example acceptance response, with timing and timestamp fields omitted:

{
  "created": true,
  "run": {
    "run_id": "YOUR_RUN_ID",
    "datachat_id": 101,
    "report_id": "YOUR_REPORT_ID",
    "mode": "data_chat",
    "status": "queued",
    "phase": "queued",
    "error_message": null
  }
}

The actual response also contains client_request_id, status messages, attempt count, timestamps, and timings. A repeated submission with the same deduplication identity can return created: false and the existing run. Keep the run ID after acceptance.

Retrieve progress and results

In this table, read and write mean workspace:read and workspace:write. Run states include queued, running, succeeded, failed, and cancelled. Keep polling while queued or running. succeeded means the run completed; inspect its events and saved results to understand what it produced.

Use view=conversation for durable polling, including a run that is still queued. Pass the last returned cursor as afterSequence on your next request. The detailed event endpoint is useful for tool activity after the run has initialized.

Stream events

curl --fail-with-body --no-buffer \
  "$UNITY_API_BASE/api/agent/runs/$UNITY_RUN_ID/stream?afterSequence=0" \
  -H "Authorization: Bearer $UNITY_API_KEY" \
  -H "Accept: text/event-stream"

The stream supports afterSequence and the Last-Event-ID header for resuming. Parse it as server-sent events, not one JSON document. If you receive data: {"fallback":true}, continue with the durable conversation-events endpoint. This can happen when a different worker serves the request or a run is historical. A browser's native EventSource cannot attach your bearer header; use a server-side client or a fetch-based SSE client.

Stop a run

curl --fail-with-body --request POST \
  "$UNITY_API_BASE/api/agent/runs/$UNITY_RUN_ID/stop" \
  -H "Authorization: Bearer $UNITY_API_KEY"

Stopping requests cancellation of future work. An operation already executing may finish. Stopping or revoking a key does not roll back saved report changes; use the supported change history and undo workflow when restoration is needed.

Retrieve runtime documentation

GET /api/agent/documentation · workspace:read

The response contains a content version, source, topic, and either documentation, a tool catalogue, or one tool's schema. Unknown topics or tool names return 400. Use the agent tool reference to browse every tool and its parameters, or download the documentation snapshot.

Errors and retries

Authentication errors have an error, message, and machine-readable code. Other operation errors may use error, message, or an operation-specific result. There is not yet a universal error envelope across all routes.

{
  "code": "insufficient_scope",
  "error": "This API token does not permit this operation.",
  "message": "This API token does not permit this operation."
}

There is no single published rate limit for all workspace endpoints. Avoid unbounded polling and automatic repeated mutations. If a create or update request times out, inspect whether it already completed before submitting it again. clientRequestId provides deduplication for agent-run submission; it is not a global idempotency key for all endpoints.

Keep API keys and connection secrets out of application logs. Log the method, path, status, resource ID, run ID, and redacted error information needed to diagnose a request.