2026.14 Public API / SDK Changes

4 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

tech Create Chat – clients can now create a chat for an assistant. Use this when you need a chatId up front (e.g. benchmarking)

Body

title (string, required) — chat title
assistantId (string, required) — assistant (space) id

Example

curl --location 'https://api.uat1.unique.app/public/chat/space/chat' \
  --header 'x-user-id: <user-id>' \
  --header 'x-company-id: <company-id>' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'x-app-id: <app-id>' \
  --header 'x-api-version: 2023-12-06' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Quarterly review",
    "assistantId": "<assistant-id>"
  }'

Benchmarking

Kong Plugin Upgrade Required

The benchmarking 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 Cluster-Multi-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.

tech Benchmarking – Process Data — upload an xlsx file to start a benchmarking run

Required Role CHAT_FEEDBACK_READ

Body (multipart/form-data)

file (file, required) — xlsx spreadsheet, max 10 MB
force (query param, boolean, optional) — force re-processing even if a run is already in progress

Response

benchmarkStatus.done (number) — completed items
benchmarkStatus.error (number) — errored items
benchmarkStatus.total (number) — total items

Example

curl --location 'https://api.uat1.unique.app/public/chat/benchmarking?force=true' \
  --header 'x-user-id: <user-id>' \
  --header 'x-company-id: <company-id>' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'x-app-id: <app-id>' \
  --header 'x-api-version: 2023-12-06' \
  --form 'file=@"benchmarking_data.xlsx"'

tech Benchmarking – Get Status — poll the current benchmarking run status

Required Role CHAT_FEEDBACK_READ

Response

done (number) — completed items
error (number) — errored items
total (number) — total items
filename (string) — uploaded file name
status (string) — current processing status
benchmarkId (string, optional) — benchmark run identifier

Example

curl --location 'https://api.uat1.unique.app/public/chat/benchmarking/status' \
  --header 'x-user-id: <user-id>' \
  --header 'x-company-id: <company-id>' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'x-app-id: <app-id>' \
  --header 'x-api-version: 2023-12-06'

tech Benchmarking – Download Results — download the processed benchmarking xlsx file

Required Role CHAT_FEEDBACK_READ

Response — binary xlsx file download

Example

curl --location 'https://api.uat1.unique.app/public/chat/benchmarking/action/download' \
  --header 'x-user-id: <user-id>' \
  --header 'x-company-id: <company-id>' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'x-app-id: <app-id>' \
  --header 'x-api-version: 2023-12-06' \
  --output benchmarking_result.xlsx

tech Benchmarking – Download Template — download a blank benchmarking template xlsx

Required Role CHAT_FEEDBACK_READ

Response — binary xlsx file download

Example

curl --location 'https://api.uat1.unique.app/public/chat/benchmarking/action/template-download' \
  --header 'x-user-id: <user-id>' \
  --header 'x-company-id: <company-id>' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'x-app-id: <app-id>' \
  --header 'x-api-version: 2023-12-06' \
  --output benchmarking_template.xlsx

Updates

tech Search – Qdrant Search Parameters

Added qdrantParams to the Search endpoint, enabling fine-grained control over Qdrant vector search behavior.

Path POST /search/search

Body

qdrantParams (optional) – Qdrant search configuration object:
- hnsw_ef (optional) – HNSW index search parameter; positive integer
- exact (optional) – Enable exact search for deterministic results; boolean
- quantization (optional) – Quantization settings object:
  - ignore (optional) – Ignore quantization; boolean
  - rescore (optional) – Rescore results; boolean
  - oversampling (optional) – Oversampling factor; number ≥ 1
- consistency (optional) – Read consistency level; valid values: "majority", "quorum", "all", or a positive integer

Example

curl --location 'https://api.uat1.unique.app/public/chat/search/search' \
--header 'x-user-id: <user-id>' \
--header 'x-company-id: <company-id>' \
--header 'Authorization: Bearer <api-key>' \
--header 'x-app-id: <app-id>' \
--header 'x-api-version: 2023-12-06' \
--header 'Content-Type: application/json' \
--data '{
  "searchString": "quarterly report",
  "searchType": "VECTOR",
  "limit": 10,
  "qdrantParams": {
    "hnsw_ef": 128
  }
}'

SDK

New Functions

tech Create a chat within a space - Open a chat tied to an assistant. Use this when you need a chatId up front (e.g. benchmarking)

Example

chat = unique_sdk.Space.create_chat(
    user_id=user_id,
    company_id=company_id,
    title="Support thread",
    assistantId=assistant_id,
)

tech Benchmarking - Upload, process, and download benchmarking xlsx workbooks. Use it to submit spreadsheets for automated evaluation, poll for completion, and retrieve results or blank templates.

Kong Plugin Upgrade Required

tech Download a blank template

template_path = unique_sdk.Benchmarking.download_template(
    user_id=user_id,
    company_id=company_id,
)

tech Upload a benchmarking spreadsheet

# Upload a benchmarking spreadsheet
with open("benchmark.xlsx", "rb") as f:
    data = f.read()

unique_sdk.Benchmarking.process_upload(
    user_id=user_id,
    company_id=company_id,
    file=data,
    filename="benchmark.xlsx",
    force=True,  # Re-queue even if already submitted
)

tech Check progress

status = unique_sdk.Benchmarking.get_status(
    user_id=user_id,
    company_id=company_id,
)
print(f"{status['done']}/{status['total']} done")

tech Download the processed result

result_path = unique_sdk.Benchmarking.download_processed(
    user_id=user_id,
    company_id=company_id,
)

tech Benchmarking Run Utility - End-to-end helper that uploads, polls until done, and optionally saves the result, all in one async call. Supports configurable polling (poll_interval, max_wait), check the docs for more details: https://unique-ag.github.io/ai/unique-sdk/latest/utilities/benchmarking_run/

import asyncio
from unique_sdk.utils.benchmarking_run import run_benchmarking_from_file

result = asyncio.run(run_benchmarking_from_file(
    user_id=user_id,
    company_id=company_id,
    path_to_file="./benchmark.xlsx",
    save_result_to="./benchmark_result.xlsx",  # Auto-saves when done
))
print(result["status"])

Updates

tech Search – Qdrant Search Settings

Configure Qdrant search parameters to control vector search behavior, including deterministic search mode.

Example

search = unique_sdk.Search.create(
    user_id=user_id,
    company_id=company_id,
    searchString="quarterly report",
    searchType="VECTOR",
    qdrantParams={
        "hnsw_ef": 128,     # Higher accuracy at cost of speed
    }
)

Author