Project and Agent API

The engine exposes its REST API under the /api path prefix (default port 9010). All endpoints return JSON and accept an optional JWT bearer token for identity-aware responses.

The endpoints on this page are the entry point of every client integration: they resolve which project the user is entering, how it is branded, whether sign-in is required and which agents may be run.

Authentication

Pass a JWT bearer token as a standard HTTP header or as a query parameter:

Authorization: Bearer <token>

or

/api/v2/project/my-project?authorization=<token>

Unauthenticated requests are permitted; the response omits user-specific data (starred agents) and may be restricted when a project requires identity (isIdentityRequired: true).

The process for getting a project with required identity is:

  1. Get project without authentication, receive limited set of properties.

  2. Prompt login according to received identity providers.

  3. Get project again with authentication, receive full project.

The complete authorization model — identity provider matching, external roles and agent state visibility — is specified in Consumer Security.

V2 Project Endpoints

The v2 project endpoints unify ID and ref lookup, support Preview-state agents for backoffice users, and include per-user agent groups (starred, recent).

GET /api/v2/project/{idOrRef}

Retrieve a project by its UUID or its ref slug.

Path Parameters

Parameter Type Description

idOrRef

String

Either a UUID (e.g. 550e8400-e29b-41d4-a716-446655440000) or a ref (e.g. myProject). The endpoint auto-detects the format: a value matching the UUID pattern is looked up by ID; all other values are looked up by ref.

Query Parameters

Parameter Required Type Description

authorization

No

String

JWT bearer token, for clients that cannot set the Authorization header. Accepted on every endpoint; see Authentication.

Response

Returns a Project object (see Project Object).

Behaviour varies by authentication state:

Condition Effect on response

Not authenticated, isIdentityRequired: false

Returns full project with published agents.

Not authenticated, isIdentityRequired: true

Returns project metadata only; agents and groups are null.

Authenticated, no backoffice ACL

Returns project with published agents; includes groups (Starred, Recent).

Authenticated, has backoffice ACL for the project

Returns project with published and preview agents; includes groups (Starred, Recent).

GET /api/v2/project?agentKey={agentKey}

Retrieve a project by the key of one of its agents. Required for when Client gets an agent link, as it still needs the whole project of the agent.

Query Parameters

Parameter Required Type Description

agentKey

Yes

String

Agent identifier. Supported formats:

  • Ref — acme-support

  • UUID — 661f9511-f30c-52e5-b827-557766551111

  • Ref + revision — acme-support.5 (looks up that exact revision regardless of publish state)

  • UUID + revision — 661f9511-f30c-52e5-b827-557766551111.5

When a revision suffix is absent the endpoint resolves the latest Published revision.

agentRef and agentId are accepted as aliases of agentKey and are resolved identically. Exactly one of the three must be present, otherwise the endpoint responds with 400 Bad Request.

Response

Identical to the response of GET /api/v2/project/{idOrRef} for the project that owns the resolved agent. See Project Object and the behaviour table in the previous section.

Agent Endpoints

GET /api/agent?grouping={grouping}

List agents for the current identity, grouped by a predefined criterion.

Parameter Required Type Description

grouping

Yes

String

One of Recent, Mine, Starred, Featured.

projectRef

No

String

Restricts the result to a single project. Without it, agents across all accessible projects are returned.

The request locale (Accept-Language) is taken into account when resolving localized agent properties. Unauthenticated requests receive the grouping evaluated without a user identity.

Returns an array of Agent objects (see Agent Object).

GET /api/agent/{key}

Retrieve a single agent by key.

Path Parameters

Parameter Type Description

key

String

Agent ref, optionally revision-qualified. A {setupName}:{ref} form is accepted — the part before the colon is ignored — so a pipeline key can be passed directly.

Returns an Agent object. Takes no query parameters.

GET /api/agents/{keys}

Retrieve several agents in one call.

Path Parameters

Parameter Type Description

keys

String

Comma-separated list of agent keys, e.g. acme-support,acme-sales.3.

Returns an array of Agent objects, in the order the keys resolve. Takes no query parameters.

PUT /api/agent/{ref}/_star and PUT /api/agent/{ref}/_unstar

Add or remove an agent from the authenticated user’s Starred group.

Path Parameters

Parameter Type Description

ref

String

Agent ref.

Both take no query parameters and no request body, and return true on success. They require an authenticated user — an anonymous request is rejected with 401 Unauthorized.

Response Objects

Project Object

Field Type Description

id

UUID string

Unique project identifier.

ref

String

Human-readable ref used to identify the project in URLs and API calls.

name

String

Display name of the project.

description

String

Short description of the project.

tenantName

String

Name of the tenant that owns this project.

tenantLogo

String | null

URL of the tenant’s logo image.

logo

String | null

URL of the project’s logo image.

terms

String | null

Terms of service text shown to users before they start a session.

primaryColor

String | null

Primary brand colour in CSS hex format (e.g. #0057B7).

secondaryColor

String | null

Secondary brand colour in CSS hex format.

featuredAgentRef

String | null

Ref of the agent that is highlighted as the project’s primary agent.

idpRef

String | null

Ref of the identity provider that authenticated the current request, when any.

identityProviders

Array

List of identity provider configurations (see IdentityProvider Object). Empty array when the project does not require identity.

isIdentityRequired

Boolean

Whether users must authenticate before accessing the project and its agents.

isUsingExternalRoles

Boolean

Whether access to the project’s agents additionally requires a matching external role. See Consumer Security.

isBillingActive

Boolean | null

Whether the tenant’s billing subscription is currently active. null if billing information is unavailable.

navigationSpecifications

Array

Flat list of in-app navigation targets the agents of this project may direct the user to, nested through parentRef. See Navigation API for the field reference, the supported types and a full example.

agents

Array | null

List of agents belonging to this project (see Agent Object). null when the project requires identity and the request is unauthenticated. Agents in Preview state are included only for users with backoffice access.

groups

Object | null

Named agent groupings for the authenticated user (see Group Object). Keys are group names (Starred, Recent). null for unauthenticated requests.

userRoles

Array | null

ACL roles the authenticated user holds on this project or its tenant. null for unauthenticated requests.

Group Object

Field Type Description

name

String

Group name. One of: Starred, Recent.

agentRefs

Array of strings

Ordered list of agent refs belonging to this group for the authenticated user.

Agent Object

Field Type Description

id

UUID string

Unique agent identifier.

ref

String

Human-readable ref used to identify the agent.

key

String

Agent key (ref with optional revision).

name

String

Display name of the agent.

title

String

Short title or role label.

description

String

Longer description of the agent’s purpose and capabilities.

state

String

Publication state. One of: Draft, Preview, Published, Archived. Which states a caller can see is specified in Consumer Security.

gender

String | null

Perceived gender of the agent’s persona. One of: Male, Female, NonBinary.

locales

Array of strings

BCP 47 locale codes the agent supports (e.g. ["en-US", "cs-CZ"]).

revision

Integer

Current revision number of the agent.

changeNote

String | null

Description of changes in the current revision.

thumbnail

String | null

URL of the agent’s thumbnail image. When absent, render the agent’s visual through /api/visual/agent/{ref}.{format}.

visualProperties

Object

Visual rendering configuration for 3D/avatar clients: avatarRef, environmentRef and an optional cameraPreset. An avatarRef prefixed with live-avatar: denotes an externally rendered avatar.

animationDataType

String

Facial animation data delivered with speech items. One of Visemes, BlendShapes, None.

inputModalities

Object

What the agent accepts as input: image, video, audio, file, url (booleans) and audioSampleRate (Hz).

projectId

UUID string

UUID of the project this agent belongs to.

project

Object | null

The owning project, included when an agent is requested outside of a project response.

isEnabled

Boolean

Whether the agent is enabled and operational.

isStarred

Boolean

Whether the authenticated user has starred this agent. Always false for unauthenticated requests.

isSpeechProcessingEnabled

Boolean

Whether server-side speech post-processing (facial animation data generation) is active for this agent.

hasSessionEndSupport

Boolean

Whether the agent can end a session itself, i.e. whether the client should expect #sessionShouldEnd.

hasUserFacingEvaluations

Boolean | null

Whether conversations with this agent produce evaluation results intended to be shown to the user. See Evaluation API.

silenceTimeout

Integer

Silence timeout in milliseconds. Currently always 0.

anonymousMode

Boolean

When true sessions are associated with an anonymous identity derived from the session ID rather than the authenticated user.

hasMemory

Boolean

Whether the agent has persistent per-user memory enabled.

emotionalSet

Object

Emotional expression set used by the agent’s visual layer: happiness, sadness, fear, disgust, anger, surprise, other (each 0.0–1.0) and lastUpdated.

sttProperties

Object | null

Speech recognition hints for this agent, when configured.

realtimeConfigurationId

UUID string

Realtime (speech-to-speech) configuration the agent runs with. All-zero UUID when the deployment default applies.

order

Integer

Sort order within its grouping or project.

lastModified

Timestamp | null

When the agent revision was last modified.

lastModifiedBy

UUID string | null

User who last modified the agent revision.

Complete Response Example

An authenticated request to a project that requires identity, answered for a user who holds an Editor ACL role — so the response contains a Published and a Draft agent, both agent groups, the identity providers and the user’s roles. Optional fields are shown populated; a field that is not set is either null or absent.

{
  "id": "8e29b3d1-6a4f-4c2e-9d70-1f2a3b4c5d6e",
  "ref": "acme",
  "name": "ACME Customer Care",
  "description": "Support and sales agents for ACME customers.",
  "tenantName": "ACME Inc.",
  "tenantLogo": "https://cdn.example.com/acme/tenant-logo.png",
  "logo": "https://cdn.example.com/acme/project-logo.png",
  "terms": "By continuing you agree to the processing of your conversation for quality purposes.",
  "primaryColor": "#0057B7",
  "secondaryColor": "#FFD700",
  "featuredAgentRef": "acme-support",
  "idpRef": "acme-entra",
  "identityProviders": [
    { "ref": "acme-entra", "name": "Microsoft", "logo": "https://cdn.example.com/idp/ms.svg" },
    { "ref": "acme-google", "name": "Google", "logo": null }
  ],
  "isIdentityRequired": true,
  "isUsingExternalRoles": false,
  "isBillingActive": true,
  "navigationSpecifications": [
    {
      "type": "route",
      "ref": "accountAssistant",
      "parentRef": null,
      "image": null,
      "name": "Account assistant",
      "description": "Starts a conversation with the account assistant.",
      "order": 1,
      "disabledMessage": null,
      "route": "/a/accountAssistant"
    }
  ],
  "userRoles": ["Editor"],
  "groups": {
    "Starred": { "name": "Starred", "agentRefs": ["acme-support"] },
    "Recent":  { "name": "Recent",  "agentRefs": ["acme-support", "acme-sales"] }
  },
  "agents": [
    {
      "id": "661f9511-f30c-52e5-b827-557766551111",
      "ref": "acme-support",
      "key": "acme-support.5",
      "name": "Ada",
      "title": "Support specialist",
      "description": "Helps with orders, returns and appointments.",
      "state": "Published",
      "gender": "Female",
      "locales": ["en-US", "cs-CZ"],
      "revision": 5,
      "changeNote": "Reworded the greeting.",
      "thumbnail": "https://cdn.example.com/acme/ada.png",
      "visualProperties": {
        "avatarRef": "ada",
        "environmentRef": "office",
        "cameraPreset": "Dynamic"
      },
      "animationDataType": "BlendShapes",
      "inputModalities": {
        "image": true, "video": false, "audio": true, "file": false, "url": true,
        "audioSampleRate": 24000
      },
      "projectId": "8e29b3d1-6a4f-4c2e-9d70-1f2a3b4c5d6e",
      "project": null,
      "isEnabled": true,
      "isStarred": true,
      "isSpeechProcessingEnabled": true,
      "hasSessionEndSupport": true,
      "hasUserFacingEvaluations": true,
      "silenceTimeout": 0,
      "anonymousMode": false,
      "hasMemory": true,
      "emotionalSet": {
        "happiness": 0.6, "sadness": 0.0, "fear": 0.0, "disgust": 0.0,
        "anger": 0.0, "surprise": 0.1, "other": 0.0,
        "lastUpdated": "2026-09-01T09:14:22.031Z"
      },
      "sttProperties": {
        "terms": ["ACME", "Novak"],
        "textPrompt": null,
        "generalContext": [ { "key": "brand", "value": "ACME" } ],
        "finalTranscriptDelay": 200
      },
      "realtimeConfigurationId": "d4c3b2a1-9f8e-4d7c-8b6a-5f4e3d2c1b0a",
      "order": 1,
      "lastModified": "2026-09-01T09:14:22.031Z",
      "lastModifiedBy": "5c8a0f12-7d34-4e56-9a1b-2c3d4e5f6a7b"
    },
    {
      "id": "772a0622-041d-63f6-c938-668877662222",
      "ref": "acme-sales",
      "key": "acme-sales",
      "name": "Ben",
      "title": "Sales assistant",
      "description": "Explains plans and pricing.",
      "state": "Draft",
      "gender": "Male",
      "locales": ["en-US"],
      "revision": 2,
      "changeNote": null,
      "thumbnail": null,
      "visualProperties": {
        "avatarRef": "orb",
        "environmentRef": null,
        "cameraPreset": null
      },
      "animationDataType": "None",
      "inputModalities": {
        "image": false, "video": false, "audio": true, "file": false, "url": false,
        "audioSampleRate": 24000
      },
      "projectId": "8e29b3d1-6a4f-4c2e-9d70-1f2a3b4c5d6e",
      "project": null,
      "isEnabled": true,
      "isStarred": false,
      "isSpeechProcessingEnabled": false,
      "hasSessionEndSupport": false,
      "hasUserFacingEvaluations": false,
      "silenceTimeout": 0,
      "anonymousMode": true,
      "hasMemory": false,
      "emotionalSet": {
        "happiness": 0.0, "sadness": 0.0, "fear": 0.0, "disgust": 0.0,
        "anger": 0.0, "surprise": 0.0, "other": 0.0,
        "lastUpdated": "2026-08-20T11:02:00.000Z"
      },
      "sttProperties": null,
      "realtimeConfigurationId": "00000000-0000-0000-0000-000000000000",
      "order": 2,
      "lastModified": null,
      "lastModifiedBy": null
    }
  ]
}

An unauthenticated request to the same project returns everything above except agents, groups and userRoles, which are null.

IdentityProvider Object

Returned inside Project.identityProviders when the project has identity required.

Field Type Description

ref

String

Unique ref of this identity provider.

name

String

Display name shown on the sign-in button (e.g. Google, Microsoft).

logo

String | null

URL of the identity provider’s logo image.