LLM APIs
Version: aju17f20mq
Use the reference below for request and response fields and operation-specific requirements.
Overview
Manage conversations, messages, tools and semantic memory through the native conversation API. Voice operations require separately enabled voice service, provider credentials and an available voice agent. See Voice availability. Native endpoints do not use the OpenAI wire protocol.
Authentication
User-facing calls act for the authenticated beneficiary. A backend sk_… key uses an authorized X-On-Behalf-Of selection with users:impersonate; a client pk_… key accompanies that user’s JWT from the configured issuer. Never expose a secret key in a client. Raw identity headers and recipient IDs are not authentication. See Authentication.
Tenant context comes from the authenticated request. Client-supplied X-Tenant-Id, X-User-Id or X-Project-Id do not grant authority. The current public integration uses the default project. Do not rely on project headers for separate project, test/live or customer isolation on this API.
A successful HTTP request can accept work that is still running, queued, awaiting client tools or failed. Inspect the run status and correlate it to the accepted runId; idle conversation state alone is not a terminal receipt for that request. Unknown or absent status means an unknown outcome, not success or proven ongoing execution.
Related guides: Conversations, Agent tools, Memory, Streaming availability
JSON conventions
Requests accept snake_case or camelCase field names; responses use camelCase. Ordinary default-valued scalars and empty repeated fields can be omitted. Explicitly present optional scalars, map values and well-known JSON types follow their own presence rules: an explicit false, 0 or empty value is not universally equivalent to absence. Decode each field according to its schema. 64-bit integers use JSON strings; preserve their precision. Unknown request fields are generally discarded before validation, so a typo can silently change behavior. This is not a guarantee that arbitrary fields or future client contracts are supported. See API conventions.
Threads
Conversation containers — create and list threads. See the Conversations guide for thread lifecycle, async generation, and configuration.
Messages
Send messages and trigger generation. See the Conversations guide for the full message lifecycle and async polling recipe.
- Send a message to a conversation
- Append a message without generating
- Send a message and wait for the result
Conversations
Conversation state, settings, and context management. See the Conversations guide.
- Update conversation settings
- Update prompt variables
- Update default generation config
- Update context management settings
- Compact a conversation
- Get full conversation state
Feedback
Rate assistant messages with a thumb or a 1–10 scale, and withdraw ratings. One rating is kept per rater per message; the rater comes from the authenticated caller.
Voice
Hosted-provider voice sessions; configured voice services and credentials are required.
Tool Approvals
Manage tool call approval workflows. See the Agent tools guide for the full approval flow.
Client Tools
Submit results from client-side tool executions. See the Agent tools guide for client-side tool patterns.
- Submit client-side tool execution results
- Submit client-side tool results and wait for the next segment
- List client-side tool calls awaiting a result
- Get a single tool call by ID
MCP Servers
Discover and introspect registered MCP servers. See the Agent tools guide.
MCP Tools
List and directly invoke MCP tools. See the Agent tools guide.
MCP Resources
MCP resource retrieval is not yet available. These endpoints currently return empty responses. See the Agent tools guide.
MCP Prompts
MCP prompt retrieval is not yet available. These endpoints currently return empty responses. See the Agent tools guide.
Memory
Semantic memory search and CRUD. See the Memory guide for how memories integrate with conversations.
- Semantic search over memories
- List user memories
- Get a specific memory
- Update a memory
- Delete a memory
Server 1
Travila API
X-API-Key
Project/service API key. Use pk_… only with a verified end-user JWT; backend sk_… calls that require a user use authorized on-behalf-of context. Management operations can have different requirements; consult the operation and authentication guide.
X-On-Behalf-Of
The end user this call acts for. Required with an sk_… key, because a secret key identifies your tenant and not a user; omitting it returns 401 authenticated user_id is required. The key needs the users:impersonate scope or the call fails with 403 insufficient_scope.
Authorization: Bearer
The end user's own JWT, issued by the OIDC provider configured on the publishable key. Required alongside a pk_… key, and supplies the user identity in place of X-On-Behalf-Of.
Authentication credentials
- API Key: apiKeyAuth
- API Key: onBehalfOf
- HTTP: bearerAuth
| Setting | Value |
|---|---|
| Security scheme type | apiKey |
| header parameter name | X-API-Key |
| Setting | Value |
|---|---|
| Security scheme type | apiKey |
| header parameter name | X-On-Behalf-Of |
| Setting | Value |
|---|---|
| Security scheme type | http |
| Scheme | bearer |
Operations
- Create a new conversation thread —
POST /api/v1/llm/create-thread - List conversation threads —
POST /api/v1/llm/list-threads - Send a message to a conversation —
POST /api/v1/llm/send-message - Append a message without generating —
POST /api/v1/llm/append-message - Rate an assistant message —
POST /api/v1/llm/rate-message - Withdraw your rating on a message —
POST /api/v1/llm/delete-message-rating - Send a message and wait for the result —
POST /api/v1/llm/send-message-sync - Update conversation settings —
POST /api/v1/llm/update-settings - Update prompt variables —
POST /api/v1/llm/update-prompt-variables - Update default generation config —
POST /api/v1/llm/update-default-generation-config - Update context management settings —
POST /api/v1/llm/update-context-management-settings - Compact a conversation —
POST /api/v1/llm/compact-conversation - Get full conversation state —
POST /api/v1/llm/conversation-state - Create a voice session (in progress) —
POST /api/v1/llm/create-daily-session - Mint a speech-to-text token (in progress) —
POST /api/v1/llm/stt-token - List pending tool approvals —
POST /api/v1/llm/list-pending-approvals - Approve or reject pending tool calls —
POST /api/v1/llm/submit-tool-approvals - Submit client-side tool execution results —
POST /api/v1/llm/submit-client-tool-results - Submit client-side tool results and wait for the next segment —
POST /api/v1/llm/submit-client-tool-results-sync - List client-side tool calls awaiting a result —
POST /api/v1/llm/list-pending-client-tools - Get a single tool call by ID —
POST /api/v1/llm/get-tool-call - List available MCP servers —
POST /api/v1/llm/mcp-list-available-servers - Get detailed MCP server info —
POST /api/v1/llm/mcp-get-server-info - List available MCP tools —
POST /api/v1/llm/mcp-list-tools - Execute an MCP tool —
POST /api/v1/llm/mcp-call-tool - List MCP resources —
POST /api/v1/llm/mcp-list-resources - Read an MCP resource —
POST /api/v1/llm/mcp-read-resource - List MCP prompt templates —
POST /api/v1/llm/mcp-list-prompts - Get an MCP prompt template —
POST /api/v1/llm/mcp-get-prompt - Semantic search over memories —
POST /api/v1/llm/search-memories - List user memories —
POST /api/v1/llm/list-memories - Get a specific memory —
POST /api/v1/llm/get-memory - Update a memory —
POST /api/v1/llm/update-memory - Delete a memory —
POST /api/v1/llm/delete-memory
Document ID: DOC-API-conversations-overview. Section identities and revisions.
| Section | Stable reference |
|---|---|
| Overview | DOC-API-conversations-overview#overview |
| Authentication | DOC-API-conversations-overview#authentication |
| JSON conventions | DOC-API-conversations-overview#json-conventions |
| Threads | DOC-API-conversations-overview#reference-group-1 |
| Messages | DOC-API-conversations-overview#reference-group-2 |
| Conversations | DOC-API-conversations-overview#reference-group-3 |
| Feedback | DOC-API-conversations-overview#reference-group-4 |
| Voice | DOC-API-conversations-overview#reference-group-5 |
| Tool Approvals | DOC-API-conversations-overview#reference-group-6 |
| Client Tools | DOC-API-conversations-overview#reference-group-7 |
| MCP Servers | DOC-API-conversations-overview#reference-group-8 |
| MCP Tools | DOC-API-conversations-overview#reference-group-9 |
| MCP Resources | DOC-API-conversations-overview#reference-group-10 |
| MCP Prompts | DOC-API-conversations-overview#reference-group-11 |
| Memory | DOC-API-conversations-overview#reference-group-12 |
| Server 1 | DOC-API-conversations-overview#reference-server-1 |
| X-API-Key | DOC-API-conversations-overview#authentication-apiKeyAuth |
| X-On-Behalf-Of | DOC-API-conversations-overview#authentication-onBehalfOf |
| Authorization: Bearer | DOC-API-conversations-overview#authentication-bearerAuth |