API Reference
Section ID: Guide/ja54mni2ot#api-reference
Use this reference when implementing a request or diagnosing a response. For a complete workflow, start with building a chat assistant, adding tools or receiving events, then follow the operation links for exact fields and errors.
Base URL
Section ID: Guide/ja54mni2ot#base-url
Example deployment base URL.
Request Format
Section ID: Guide/ja54mni2ot#request-format
Call the public API using these paths:
Use an HTTP POST with a JSON body and Content-Type application/json. Each operation has a capability-specific public path; use Send a message to a conversation for its exact path and request, rather than constructing a callable URL from the historical capability/operation placeholder.
For example:
Request example: Send a message to a conversation. Example identifiers and values are illustrative; substitute authorized values.
Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.
Send JSON request bodies. The sections below explain field names, omitted values and validation behavior.
Field names
Section ID: Guide/ja54mni2ot#field-names
Both spellings of a field name are accepted, so conversationKey and conversation_key are the same field. Responses always come back in camelCase.
Response fields carrying 64-bit integers use decimal JSON strings; preserve their precision when storing or comparing them. Ordinary default-valued scalars may be omitted. Explicitly present optional scalars and map values can retain false or 0; use each operation schema’s presence rules instead of applying one default to every missing field.
Unrecognized request fields
Section ID: Guide/ja54mni2ot#unrecognized-request-fields
The current public API can discard unknown field names before validation. Unknown enum names and internal unset values are invalid request choices: use a documented value, or omit an optional enum field to retain its defined default. Malformed JSON, wrong field types and missing required fields also fail. Validate against the specific operation schema rather than treating permissive handling of unknown fields as a compatibility guarantee.
A typo in a field name is therefore not reported as a typo. It is reported as whatever happens when that field is missing:
| The field you misspelled | What you get |
|---|---|
| One the endpoint requires | 400, naming the field it did not receive |
| One that is optional | 200 — the request succeeds and your value is ignored |
The second row is the dangerous one, and it is worth re-reading. If you send {"temperature": 0.2} as {"temperatur": 0.2}, the call succeeds and the model runs at the default temperature. Nothing failed, so nothing tells you.
Scalar fields make this harder to spot. For a plain string, number, or boolean, the platform cannot distinguish these three cases — all of them arrive as the field's default ("", 0, false):
The three source cases distinguish an unrecognized field named conversationKeyy, an explicitly empty conversationKey, and an omitted conversationKey. For an ordinary scalar without presence, an explicitly empty value and an omitted value collapse to the scalar default. Optional fields can retain explicit presence. These cases are illustrations, not one valid complete JSON request; the selected operation contract determines its actual requirements.
Fields with explicit presence, including optional scalars and message-valued fields (userMessage, overrideGenerationConfig, …), do not have this ambiguity — the platform can tell whether you sent the object at all. A missing object produces a 400 only when the field is marked required, such as userMessage on send requests. Optional objects such as overrideGenerationConfig may be omitted.
What this means in practice: when a call succeeds but the platform behaved as though you had not passed something, check the spelling of that field before anything else. Validate request bodies against the schemas on these pages, or import the Postman collection and let it fill the field names in.
Authentication
Section ID: Guide/ja54mni2ot#authentication
Every request must include one of:
| Method | Header | Use Case |
|---|---|---|
| Secret key | X-API-Key: sk_..., plus X-On-Behalf-Of: <user-id> for user-scoped calls | Backend-to-backend; follow the operation's scope |
| Publishable key + JWT | X-API-Key: pk_... + Authorization: Bearer <user-jwt> | Client apps |
A dashboard sign-in JWT is an account-administration credential, not an API credential — don't authenticate an application with one.
User impersonation
Section ID: Guide/ja54mni2ot#user-impersonation
| Header | Required | Description |
|---|---|---|
X-On-Behalf-Of: <user-id> | Required when a backend secret key (sk_*) acts on behalf of a specific user, including on create-thread | Scope users:impersonate must be granted to the key |
See Authentication reference for credential configuration, required headers, key limits and authentication errors. For a complete integration, follow the signed-in conversation recipe.
APIs
Section ID: Guide/ja54mni2ot#apis
Choose the API group for the work your application needs. Each group lists its operations, exact request paths, fields and errors.
| API group | Use it for |
|---|---|
| Conversations | Threads, messages, feedback, tools, memories and voice sessions. |
| End users | Profile self-service, location, locale, generation preferences and metadata. |
| Notifications | Push, inbox, preferences, topics, subscribers, workflows and providers. |
| Scheduled jobs | Cron, one-shot and recurring schedules, with execution history. |
| Webhooks | Outbound endpoints, subscriptions, delivery history and retries. |
| Agent profiles | Agent profiles and shared prompt fragments: create, version, delete and import. |
| Custom MCP servers | Register, update, remove and test your own HTTP MCP servers. |
| Project secrets | Store project credentials; retrieve their metadata without returning secret values. |
| Connected apps | App discovery, account connections, authenticated app API calls and offboarding. |
| Evaluations | Traces, scores, reviewer feedback, datasets, runs and annotation queues. |
| Storage | Upload and access application files using the storage operations. |
Use the Domain models index for reusable business types and their uses. Operation pages own their request and response bodies. The Event catalog links lifecycle events, payload fields, examples and receiver verification guidance.
Shared error support types include ErrorDetails, ErrorInfo, FieldViolation, HelpLink, ModelError, RetryInfo, RpcError, UpstreamError. Follow each model’s uses and the error fields on synchronous message results, synchronous client-tool results and generation completion. These structures are not a universal HTTP error envelope: authentication, other operations and upstream failures can return different bodies. Runtime event identity and scope are explained in the receiver verification guidance.
Idempotent requests
Section ID: Guide/ja54mni2ot#idempotent-requests
A timeout or disconnected client does not establish that a mutation failed. Do not blindly repeat a message send, tool action or other side effect.
The current public edge has not been qualified for a universal Idempotency-Key contract. Sending the header alone does not prove that a retry will return a saved result or avoid another charge. Use deduplication only where your deployment documents and verifies the exact endpoint, scope, payload matching rules and retention window.
For a qualified endpoint, keep one stable operation key and identical request payload across retries. A different action needs a new key. On an uncertain result, read the resource or operation status before submitting new work. If the endpoint cannot reconcile that operation, surface the uncertainty instead of claiming success or silently repeating it. A local request ledger helps your application track intent, but cannot by itself make a remote mutation atomic.
Deduplication scope and retention must be documented for the endpoint you call. Do not assume a key remains effective indefinitely or that support on one endpoint applies to another.
Keys in outbound callbacks
Section ID: Guide/ja54mni2ot#keys-in-outbound-callbacks
Scheduler callbacks carry Idempotency-Key: sched:{scheduleId}:{scheduledTimeMillis}, matching their JWT jti. For a deployment supporting this API version, webhook deliveries carry X-Convoy-Idempotency-Key: {event_id}:{endpoint_id}. Check it against the signed body’s ctx.event_id and your configured endpoint; the documented body HMAC does not authenticate arbitrary routing or idempotency header replacements. Authenticate the callback first and deduplicate durable acceptance in your receiver using the verified scope and payload digest. These identifiers do not automatically deduplicate a subsequent API call.
See callback verification and webhook deliveries for receiver requirements and the current event metadata and signature format.
Postman collection
Section ID: Guide/ja54mni2ot#postman-collection
Every endpoint above, ready to import:
-
Collection — one folder per API, 180 requests
-
Environment —
baseUrl,apiKey,jwt,onBehalfOf
Import both, select the Travila Platform environment, and set apiKey. Auth is configured once on the collection, so every request inherits it — set jwt as well when using a publishable (pk_*) key, and onBehalfOf when a secret key acts for a specific user. Both headers are only attached when their variable is non-empty.
Request bodies are generated from the same OpenAPI specs that produce this reference, so every field is present with a typed placeholder ("<string>", "<integer>") rather than a real value. These are scaffolding bodies, not validated executable fixtures: replace placeholders with correctly typed values, select valid oneof alternatives, and drop optional fields you don't need. For enum fields the placeholder doesn't name the allowed values — check the endpoint page here for the accepted set.
Note
The collection is regenerated from the specs on each docs build. Generation keeps operation identities aligned, but does not prove deployment availability or that a placeholder body satisfies every validation rule.
Use supported public operations
Section ID: Guide/ja54mni2ot#use-supported-public-operations
Use the documented connection-management operations to register, update and test your own tool servers. Availability and permissions depend on the API version and deployment you use.
Documentation scope
Section ID: Guide/ja54mni2ot#historical-publication-scope
These guides cover application workflows, API operations, event payloads and reusable domain models. Read each page’s prerequisites and availability before choosing a workflow.
Current contract
Section ID: Guide/ja54mni2ot#publication-status_definitions-current-contract
Describes the current API contract. Check the page’s prerequisites and the API version available in your deployment.
Preview
Section ID: Guide/ja54mni2ot#publication-status_definitions-preview
Preview behavior has the scope and limitations stated by the section. Check those limitations before depending on it.
Upcoming
Section ID: Guide/ja54mni2ot#publication-status_definitions-upcoming
Proposed behavior that is not yet available.
Mixed availability
Section ID: Guide/ja54mni2ot#publication-status_definitions-mixed
This page contains sections with different availability. Use the label on the specific section you need.
Deprecated contract
Section ID: Guide/ja54mni2ot#publication-status_definitions-deprecated-current-contract
This contract is deprecated. Follow its documented replacement and check whether existing use remains supported.
Report a documentation problem
Section ID: Guide/ja54mni2ot#publication-traceability
Include the page URL and visible section identifier when reporting a documentation problem. Name the operation or field involved and describe the behavior you expected.
Using the reference
Section ID: Guide/ja54mni2ot#publication-scope
Use the guides for complete workflows and the operation pages for exact requests, responses and errors. Feature availability can differ by deployment.
Finding related contracts
Section ID: Guide/ja54mni2ot#generated-reference-intent
Operation pages own their request and response formats. Domain models explain reusable business data. Event pages describe lifecycle payloads and link to the operations that produce or consume them. Follow field links to inspect nested values.
Total: 180 endpoints across 11 APIs
| API | Contract | Endpoints |
|---|---|---|
| Custom MCP Server APIs | Declared contract | 6 |
| Scheduler APIs | Declared contract | 10 |
| Eval APIs | Declared contract | 27 |
| Notification APIs | Declared contract | 48 |
| Third-Party Integrations APIs | Declared contract | 8 |
| Webhook APIs | Declared contract | 9 |
| Agent Profile APIs | Declared contract | 14 |
| End User APIs | Declared contract | 5 |
| Project Secret APIs | Declared contract | 4 |
| Storage APIs | Declared contract | 15 |
| LLM APIs | Declared contract | 34 |
Document ID: Guide/ja54mni2ot