Skip to main content
The TruGen REST API is how you programmatically create agents, manage templates, ground them in your data, register tools, and read session records. Everything you can do in the Developer Portal, you can do here.

​
Base URL

All responses are application/json unless otherwise noted.

​
Authentication

Every request must include an X-API-Key header. Create keys in the Developer Portal.
Your API key is server-only. Never embed it in browser or mobile client code. For client-side use, exchange the API key for a short-lived session token via the JS SDK Authentication or Python SDK Authentication flow.

​
Two-tier authentication model

TruGen uses two credentials, each with a different purpose: See JS SDK Authentication or Python SDK Authentication for the full pattern.

​
Resource model

The API is organized around a small set of resources:

​
Common patterns

​
Create an agent → embed it

  1. POST /v1/ext/agent: create the agent, get an agent_id
  2. Drop the widget or iframe with that ID
  3. Users interact: sessions are automatically tracked

​
Personalize per user

  1. Create an agent once with the shared prompt
  2. On each session, mint a session token with userId, userName, and context
  3. The agent sees this context and personalizes accordingly

​
Use a template across many agents

  1. POST /v1/ext/template: create the template with the shared config
  2. POST /v1/ext/agentbytemplate: spin up a new agent from the template

​
Access session results

  1. Handle the call_ended webhook: see Event Callbacks
  2. Fetch the conversation record with GET /v1/ext/conversation/{id}: includes chat_history, snippets, feedback, usage_json

​
Errors

Errors are returned as JSON with an error field:

​
Pagination

List endpoints use offset + perpage query parameters:
The response includes an X-Total-Count header with the total match count for the query. Additional filters vary per endpoint: check the individual endpoint page.

​
Versioning

The API is versioned in the URL path (/v1/…, /v2/…). Breaking changes ship as new versions. Non-breaking additions ship in place; watch the changelog for notice.

​
Documentation map

Video Agents

Create, fetch, update, and delete conversational agents.

Templates

Reusable persona blueprints.

Knowledge Base

Ground answers in your documents and URLs.

Conversations

Session records, transcripts, and speak commands.

Tools

Register callable actions for agents.

Guardrails

Safety-check rules agents can call mid-conversation.

Providers

List available STT, LLM, and TTS providers.

Avatars

Browse stock and custom avatars.

Text to Video

Async video generation from a script.
Each endpoint page includes the full request/response schema, an example, and cross-links to related concepts.