Engine Integration

Integrating with the engine means opening a conversation transport for the conversation itself, and calling REST endpoints under /api around it. Most applications use both. They are addressed against the same host and share one identity model, so a token that works for one works for the others — see Authentication. Who may see and run what is specified in Consumer Security, which governs the transports and the REST endpoints alike.

APIs

API Purpose Endpoints

Pipeline Socket

Run a conversation: stream audio or text and receive transcripts, speech and UI elements. This is the conversation itself. Also reachable without a socket library over the HTTP Pipeline Channel, and over the phone through Twilio.

/socket/io/pipeline, /socket/pipeline/{key}, /socket/twilio/{key}, /api/pipeline/{key}

Project and Agent API

Resolve the project, its branding, terms and identity providers, and the agents the user may run. Star and unstar them. The entry point of every client integration.

/api/v2/project, /api/v2/project/{idOrRef}, /api/agent, /api/agent/{key}, /api/agents/{keys}, star/unstar

Session API

Read past conversations and the turns they consist of.

/api/session, /api/session/{sessionId}, /api/session/{sessionId}/turn, /api/session/application/{applicationRef}

User API

Read and erase the user record, and register a device for push notifications.

/api/user, /api/user/fcmToken

Memory API

Snapshot, restore and erase the agent’s long-term memory of the user.

/api/memory, /api/memory/state, /api/memory/state/{stateId}

Navigation API

In-app entry points an agent may direct the user to. Rendered from the project payload, and pushed over the conversation transport and as a notification when one unlocks mid-session.

/api/navigation/status/{ref}

Feedback API

Structured surveys collected before or after a conversation, delivered with the project or over the conversation transport and submitted back over REST.

/api/feedback/specification, /api/feedback/submission/{definitionId}

Evaluation API

Show the user how a conversation went: evaluation status, insights and aggregations.

/api/evaluation/status, /api/v2/evaluation/status, /api/evaluation/insights, /api/evaluation/aggregations

Development Profile API

Read the user’s coaching summary — a coach’s note and the state and direction of each skill.

/api/development-profile

Visual API

Serve agent thumbnails, generated images and session recordings as binary content.

/api/visual/*, /api/recording/session/{sessionId}.

Integration API

Connect an agent to external systems, initiate telephony conversations, report problems and query instance metadata.

/api/oauth/, /api/mcpconnection/, /api/call/initiate, /api/slack/{key}, /api/report/**, /api/version, /api/time

A Typical Integration

  1. Resolve the project and its agents over REST, and render the branding, terms and agent list it returns.

  2. Authenticate the user when the project requires it, then request the project again to receive the full agent list. The rules are specified in Consumer Security.

  3. Open a conversation transport with the chosen agent’s pipeline key, wait for #ready, then send #intro or the user’s first input.

  4. Stream audio or text and render the returned transcripts, speech items and UI elements. End the session by sending #end.

  5. Optionally poll the evaluation status of that session and show the result.

Conventions

These hold across every /api endpoint. The REST endpoints live under the /api prefix (port 9010 in local development, HTTPS on the deployment host otherwise), and requests and responses are JSON unless noted otherwise.

Identifiers

id fields are UUID strings. ref fields are human-readable slugs unique within their scope. Endpoints that accept idOrRef auto-detect the format: a value matching the UUID pattern is looked up by ID, anything else by ref.

Polymorphic types

Objects that have several variants — navigation items, navigation conditions, evaluation definitions — carry a type discriminator as the first property of the object, named type. A client whose deserializer expects a different name sends that name in the X-Discriminator-Name request header; .NET and Unity clients typically send X-Discriminator-Name: $type. The header applies to the whole exchange, so a request carrying it must also use that name in its own body, and an unusable name is ignored. It affects the JSON bodies of the /api endpoints; the element streams of the conversation transports always use type.

Agent keys

An agent key is a ref or ID with an optional revision suffix (acme-support, acme-support.5). Without a suffix the latest Published revision is resolved; with a suffix the exact revision is resolved regardless of its state.

Authentication

A JWT bearer token, an API key or Basic credentials — see Authentication. Most endpoints also accept anonymous requests and return a reduced result.

Errors

Errors are returned with a standard HTTP status code. 404 responses carry a JSON body describing the missing entity; other failures use the framework’s error representation. Endpoints validating query parameters return 400 with a message (for example a non-positive limit).

Streaming

The engine is fully reactive. Endpoints returning collections may stream their result as it is produced rather than buffering it; treat the response as a stream when reading large result sets.

Wire Formats

Everything on the conversation transport — and on the HTTP channel — is the same element model in one of three encodings: TEXT, JSON or MSGPACK. Choose per connection and per direction; see Wire Formats.

Machine-Readable Schema

An OpenAPI 3 document covering every endpoint of the running instance — including internal ones — is served at:

GET /api/schema.json

The document is annotated with the bearer-JWT security scheme and with the authorization requirement of each endpoint. Use it to generate clients; use these pages for the semantics.