Integration Guide

This guide is for developers who integrate an application with the service. It covers authentication, chatting with agents and the events your client has to handle.

All examples use placeholders in the form ${NAME}. Replace them with the values configured for your tenant and environment. You receive these values during onboarding.

Overview

The service offers two APIs:

API	Use it to	Typical use
Agent Runtime	Talk to deployed agents and teams	Embed an assistant in your application
Semantic Query Engine	Manage datasources, ingest documents and run semantic searches	Make your own documents available to agents. See Knowledge and Search.

Use both together when an assistant should answer based on your own data.

flowchart LR
    App[Your application] -->|chat| RT[Agent Runtime]
    App -->|ingest and search| SQE[Semantic Query Engine]
    RT -->|retrieval| SQE

The Agent Runtime offers two chat APIs:

API	When to use it
Chat completions	Default. OpenAI-compatible, with or without streaming. All examples in this guide use it.
Responses API	Optional alternative. Streaming only. Delivers reasoning, tool activity and citations as separate items, for rich chat interfaces.

Use this guide with AI coding assistants

Download the integration skill (ZIP). It contains this complete guide, including Knowledge and Search and Security and Access, in the Agent Skills format. Unpack it into the skills folder of your coding assistant, for example .github/skills/ or .claude/skills/ in your repository. The assistant then uses the guide when you ask it to build or change an integration.

The skill is generated from this documentation on every release, so download it again to get updates.

Prerequisites

You need the following values for your tenant:

Value	Description
`${TENANT_ID}`	Identifier of your tenant
`${TOKEN_ENDPOINT}`	OAuth 2.0 token endpoint of your tenant
`${RUNTIME_BASE_URL}`	Base URL of the Agent Runtime
`${SQE_BASE_URL}`	Base URL of the Semantic Query Engine
`${RUNTIME_AUDIENCE}` and `${SQE_AUDIENCE}`	Target audiences for access tokens
`${RUNTIME_CLIENT_ID}` and secret	Client for chat integration
`${INGESTION_CLIENT_ID}` and secret	Client for ingestion and retrieval

Request basics

Every authenticated request needs these headers:

Header	Value
`Authorization`	`Bearer ${ACCESS_TOKEN}`
`X-Tenant-ID`	`${TENANT_ID}`. Must match the tenant in the token.
`Content-Type`	`application/json` for JSON bodies

Both APIs publish an interactive API reference: ${RUNTIME_BASE_URL}/docs for the Agent Runtime and ${SQE_BASE_URL}/docs for the Semantic Query Engine.

Authentication

The service uses OAuth 2.0 with tenant isolation. Each API expects a token for its own audience. All token requests are form-encoded and go to the token endpoint of your tenant:

POST ${TOKEN_ENDPOINT}
Content-Type: application/x-www-form-urlencoded

Agent Runtime: act on behalf of a user

The runtime acts for a specific user, so that the user’s roles decide which agents may be used. This takes two token exchanges.

Step 1: get a token for the user.

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&client_id=${RUNTIME_CLIENT_ID}
&client_secret=${RUNTIME_CLIENT_SECRET}
&requested_subject=${USER_ID}
&scope=openid

${USER_ID} is the username or email of the user. The response contains an access_token, referred to below as ${IMPERSONATED_TOKEN}.

Step 2: exchange it for a token for the Agent Runtime.

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&client_id=${RUNTIME_CLIENT_ID}
&client_secret=${RUNTIME_CLIENT_SECRET}
&subject_token=${IMPERSONATED_TOKEN}
&scope=openid
&audience=${RUNTIME_AUDIENCE}

Use the returned access_token as ${RUNTIME_TOKEN}. It is valid for the time given in expires_in. Request a new token before it expires.

Semantic Query Engine: client credentials

Ingestion and retrieval use a service client:

grant_type=client_credentials
&client_id=${INGESTION_CLIENT_ID}
&client_secret=${INGESTION_CLIENT_SECRET}
&scope=openid
&audience=${SQE_AUDIENCE}

Use the returned access_token as ${SQE_TOKEN}.

In this section

Agent Runtime

Chat completions: list agents and send messages
Streaming events: progress, citations, guardrails and approval requests
Sessions: let the service keep the conversation state
External tools: let agents call functions in your application
Feedback: collect ratings for answers
Instance health: check that an agent is ready
Responses API: optional item-based streaming API for rich chat interfaces

Knowledge and Search

Datasources: concepts and datasource management
Ingesting documents: load, update and delete documents
Ingestion best practices: IDs, metadata and splitting
Search and filters: query datasources directly

Security and Access

Roles and permissions: roles, groups and access to agents and datasources
Data storage and retention: what is stored and how to delete it

General

Errors and limits: error format and retry strategy
Go-live checklist