API Reference

Section: DOC-DX-api-compatibility#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: DOC-DX-api-compatibility#base-url.

https://api.travila.ai

Request Format

Section: DOC-DX-api-compatibility#request-format.

Call the public API using these paths:

POST /api/v1/<capability>/<operation>
Content-Type: application/json

For example:

curl -X POST https://api.travila.ai/api/v1/llm/send-message \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
  "conversationKey": "conv_abc",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "Hello"
      }
    ]
  }
}'

Reference: Send a message to a conversation · Request fields.

Send JSON request bodies. The sections below explain field names, omitted values and validation behavior.

Field names

Section: DOC-DX-api-compatibility#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: DOC-DX-api-compatibility#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):

{"conversationKeyy": "abc"}   // misspelled — value discarded
{"conversationKey": ""}       // sent explicitly as empty
{}                            // omitted entirely

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: DOC-DX-api-compatibility#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: DOC-DX-api-compatibility#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: DOC-DX-api-compatibility#apis.

API	Base Path	Endpoints	Description
LLM APIs	`/api/v1/llm/`	34	Threads, messages, message feedback, MCP tools, memories, voice sessions (in progress)
Storage APIs	`/api/v1/storage/`	15	Per-user file storage, upload/download URLs
End User APIs	`/api/v1/enduser/`	5	End-user profile self-service — location, locale, default generation config, metadata
Notification APIs	`/api/v1/notifications/`	48	Push, inbox, preferences, send, topics, subscribers, workflows, providers, change promotion
Scheduler APIs	`/api/v1/scheduler/`	10	Scheduled jobs — cron, one-shot, and recurring-interval schedules; execution history
Webhook APIs	`/api/v1/webhooks/`	9	Outbound webhooks — endpoints, subscriptions, delivery history and retries
Agent Profile APIs	`/api/v1/agent-profiles/`	14	Agent profiles and shared prompt fragments — create, version, delete, import
Custom MCP Server APIs	`/api/v1/mcp-servers/`	6	Bring-your-own HTTP MCP servers — register, update, delete, and test the connection
Project Secret APIs	`/api/v1/secrets/`	4	Project-scoped credentials — write-only; values go in, only metadata comes out
Third-Party Integrations APIs	`/api/v1/integrations/pipedream/`	8	Third-party app connections — app catalog, Connect links, connected accounts, an authenticated proxy to a connected app API, offboarding
Eval APIs	`/api/v1/evals/`	27	Traces and scores behind your LLM turns — reviewer ratings, comments, evaluation datasets, dataset runs, annotation queues

Total: 180 endpoints across 11 APIs.

For outgoing webhook event names, payload schemas and examples, use the Event catalog. Shared API types identifies cross-cutting support types and the operations and events that actually use them.

Idempotent requests

Section: DOC-DX-api-compatibility#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: DOC-DX-api-compatibility#keys-in-outbound-callbacks.

Scheduler callbacks carry Idempotency-Key: sched:{scheduleId}:{scheduledTimeMillis}, matching their JWT jti. Webhook deliveries carry X-Convoy-Idempotency-Key: {event_id}:{endpoint_id}. Check it against the signed body’s event_context.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.

Postman collection

Section: DOC-DX-api-compatibility#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: DOC-DX-api-compatibility#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.

Document ID: DOC-DX-api-compatibility. Section identities and revisions.

Base URL​

Request Format​

Field names​

Unrecognized request fields​

Authentication​

User impersonation​

APIs​

Idempotent requests​

Keys in outbound callbacks​

Postman collection​

Use supported public operations​