# 2026.20 Public API / SDK Changes 5 min read **Heads Up – New API Version Coming Soon** We want to inform you that a new version of the Public API is currently in development. No action is required on your end at this time - we will provide full documentation and a clear adoption timeline ahead of any changes. **What's changing?** - Enforced role-based access control (RBAC) - Stricter request validation ## Public API ### **New Endpoints** **Analytics** **Kong Plugin Upgrade Required** The analytics endpoints are only available for clients who have upgraded to the latest Kong plugin ( >1.3.0). This is already the case for Single-Tenant (ST) and Multi-Tenant (MT) deployments. For Customer-Managed-Tenant (CMT) deployments this must be verified — and it will only work if the CMT avoids hair-pinning. CMTs that use hair-pinning will not be able to use these endpoints, because the endpoints are now protected by roles retrieved from Zitadel. **Required Role**: `chat.feedback.read` or `chat.data.admin` **Supported analytics types**: `ACTIVE_USER`, `CHAT_INTERACTION`, `CHAT_INTERACTION_DETAILED`, `REFERENCE_STAT`, `INGESTION_STAT`, `PRODUCT_METRICS`, `MODEL_USAGE`, `NPS`, `USER_CHAT_EXPORT` **Create Order** — create and start an analytics report order. **Body** - `type` (AnalyticsType enum, required) — report type (see supported types above) - `start_date` (string, required) — report start date in ISO 8601 format (e.g. `"2024-01-01"`) - `end_date` (string, required) — report end date in ISO 8601 format (e.g. `"2024-12-31"`) - `assistant_id` (string, optional) — filter the report to a specific assistant **Example** ``` curl --location 'https://api.uat1.unique.app/public/analytics/orders' \ --header 'x-user-id: ' \ --header 'x-company-id: ' \ --header 'Authorization: Bearer ' \ --header 'x-app-id: ' \ --header 'x-api-version: 2026-03-01' \ --header 'Content-Type: application/json' \ --data '{ "type": "CHAT_INTERACTION", "start_date": "2024-01-01", "end_date": "2024-12-31" }' ``` **List Orders** **—** list all analytics orders for the company. **Query** - `skip` (number, optional, default `0`) — number of orders to skip - `take` (number, optional, default `20`, max `100`) — number of orders to return **Example** ``` curl --location 'https://api.uat1.unique.app/public/analytics/orders?skip=0&take=20' \ --header 'x-user-id: ' \ --header 'x-company-id: ' \ --header 'Authorization: Bearer ' \ --header 'x-app-id: ' \ --header 'x-api-version: 2026-03-01' ``` **Get Order** — fetch a single order by ID; use this to poll for completion. **Example** ``` curl --location 'https://api.uat1.unique.app/public/analytics/orders/' \ --header 'x-user-id: ' \ --header 'x-company-id: ' \ --header 'Authorization: Bearer ' \ --header 'x-app-id: ' \ --header 'x-api-version: 2026-03-01' ``` **Download Results** — download the completed analytics report as a CSV file. The order must be in `DONE` state. Returns `422` if the order is still processing. **Example** ``` curl --location 'https://api.uat1.unique.app/public/analytics/orders//download' \ --header 'x-user-id: ' \ --header 'x-company-id: ' \ --header 'Authorization: Bearer ' \ --header 'x-app-id: ' \ --header 'x-api-version: 2026-03-01' \ --output analytics_report.csv ``` **Delete Order** — delete an analytics order by ID **Example** ``` curl --location --request DELETE 'https://api.uat1.unique.app/public/analytics/orders/' \ --header 'x-user-id: ' \ --header 'x-company-id: ' \ --header 'Authorization: Bearer ' \ --header 'x-app-id: ' \ --header 'x-api-version: 2026-03-01' ``` **Briefings** Briefings let integration partners attach a markdown narrative and a set of suggested prompts to an assistant. When the `FEATURE_FLAG_ENABLE_NARRATIVE_SUGGESTED_PROMPTS_UN_19396` flag is enabled, the chat web app renders the briefing on the chat welcome view of any assistant that has one attached. **Required Role**: `chat.admin` (briefing `READ`, `WRITE`, `DELETE`, `MANAGE`). `chat.user` and space admins have `READ` only. **Upsert Briefing** — create or update the briefing attached to an assistant. Sending a new `prompts` array fully replaces the previous one; the array order becomes the displayed order. **Path** - `assistantId` (string, required, max 255 chars) — identifier of the assistant the briefing should be attached to. Used as the briefing's external id. **Body** - `title` (string, optional, max 100 chars) — display title shown above the briefing in the chat UI. Omit to use the default copy ("Today's Briefing"). - `text` (string, required, max 4,000 chars) — markdown briefing body. - `generatedAt` (string, required, ISO-8601) — timestamp when the briefing was generated by the integration partner. - `prompts` (array, required, max 200 items) — full replacement set of suggested prompts. Each item has: - `title` (string, required, max 100 chars) - `body` (string, required, max 4,000 chars) **Example** ``` curl --location --request DELETE 'https://api.uat1.unique.app/public/briefings/' \ --header 'x-user-id: ' \ --header 'x-company-id: ' \ --header 'Authorization: Bearer ' \ --header 'x-app-id: ' \ --header 'x-api-version: 2026-03-01' ``` **Get Briefing** — fetch the briefing currently attached to an assistant. Returns `404` if no briefing is attached. **Path** - `assistantId` (string, required) — identifier of the assistant whose briefing should be returned. **Example** ``` curl --location 'https://api.uat1.unique.app/public/briefings/' \ --header 'x-user-id: ' \ --header 'x-company-id: ' \ --header 'Authorization: Bearer ' \ --header 'x-app-id: ' \ --header 'x-api-version: 2026-03-01' ``` **Detach Briefing** — detach the briefing from the assistant. The underlying briefing record is preserved when other assistants in the same tenant still reference it; the response confirms the per-assistant detach. Returns `404` if no briefing is attached. **Path** - `assistantId` (string, required) — identifier of the assistant whose briefing should be detached. **Example** ## SDK ### New Functions **unique_sdk.AnalyticsOrder.create** — create and start an analytics order (see supported types above in the beginning of the Public API section) **Example** ``` order = unique_sdk.AnalyticsOrder.create( user_id=user_id, company_id=company_id, type="CHAT_INTERACTION", startDate="2024-01-01", endDate="2024-12-31", ) ``` **unique_sdk.AnalyticsOrder.list** — list analytics orders for the company, sorted by creation date descending **Example** ``` orders = unique_sdk.AnalyticsOrder.list( user_id=user_id, company_id=company_id, skip=0, take=20, ) ``` **unique_sdk.AnalyticsOrder.retrieve** — fetch a single order by ID; use this to poll for status changes. **Example** ``` order = unique_sdk.AnalyticsOrder.retrieve( user_id=user_id, company_id=company_id, order_id="ord_abc123", ) ``` **unique_sdk.AnalyticsOrder.delete** — delete an analytics order by ID. **Example** ``` deleted = unique_sdk.AnalyticsOrder.delete( user_id=user_id, company_id=company_id, order_id="ord_abc123", ) ``` **unique_sdk.AnalyticsOrder.download** — download the CSV content of a completed order; order must be in `DONE` state. **Example** ``` csv_content = unique_sdk.AnalyticsOrder.download( user_id=user_id, company_id=company_id, order_id="ord_abc123", ) ``` **Analytics Order Run Utility** — `run_analytics_order` async helper handles the full create → poll → download workflow in one call **Example** ``` import asyncio from unique_sdk.utils.analytics_order_run import run_analytics_order async def main(): result = await run_analytics_order( user_id=user_id, company_id=company_id, type="CHAT_INTERACTION", start_date="2024-01-01", end_date="2024-12-31", save_csv_to="./report.csv", ) print(result["order"]["state"]) # "DONE" print(result.get("csv_path")) # "./report.csv" asyncio.run(main()) ```