# Find the right documentation Start with the [conversation quickstart](/managed-agents/conversations/quickstart) for a complete first flow. Use the [API reference](/api) for operations and payloads, and the [glossary](/glossary) for product terms. Check each capability’s availability and deployment prerequisites. --- URL: https://docs.travila.ai/overview # Platform Overview \{#platform-overview} Build an assistant that answers customers, looks up information, uses their connected apps and follows up on recurring work. Travila provides the conversation and tool workflows behind your application. Start with the [quickstart](/managed-agents/conversations/quickstart) for a first request, or choose a complete use case in [Build](#build). Each guide states its availability and current limits. ## Getting Started \{#getting-started} Get up and running quickly. | Page | Description | | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | [Quickstart](/managed-agents/conversations/quickstart) | Make a first authenticated conversation call | | [Authentication & API Keys](/core-platform/identity-access/authentication) | Authenticate requests and understand key and access limits | | [Development Setup](/developer-experience/local-tooling/development) | Send a controlled chat request in Postman, then compare it with your application | | [Giving feedback](/feedback) | Prepare an actionable report as a developer or coding agent | | [Testing](/developer-experience/local-tooling/testing) | Test requests and retries, run client tools, and use evaluation datasets | ## Guides \{#guides} Choose the problem you need to solve, then follow the linked workflow. | Page | Description | | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | [Conversations](/managed-agents/conversations) | Keep a chat conversation and get the result of each request | | [Streaming](/managed-agents/conversations/streaming) | Display replies as they arrive and recover a dropped connection | | [Model Routing](/managed-agents/model-controls) | Choose models that fit your task and cost constraints | | [Agent tools](/integrations/tools-connections) | Let an assistant use a service and ask before sensitive actions | | [Memory](/managed-agents/memory-knowledge) | Recall relevant user preferences in later conversations | | [Agent Profiles](/managed-agents/profiles-prompts) | Reuse an assistant’s instructions, model and tools across conversations | | [End Users](/core-platform/identity-access/end-users) | Apply the right language, location and defaults for each user | | [Storage](/core-platform/files-data) | Let users upload, organize and retrieve files | | [Notifications](/core-platform/notifications) | Notify users through their selected channels | | [Scheduled Jobs](/core-platform/scheduling) | Run a task once or on a recurring schedule | | [Webhooks](/integrations/webhooks) | Update your backend when conversation activity occurs | | [Connected apps](/integrations/tools-connections/connected-apps) | Let users connect their own SaaS accounts and give the model their tools | | [Evals](/insights/evaluation) | Compare assistant quality and review responses | | [Scopes & permissions](/core-platform/identity-access/scopes-permissions) | Choose access for your application and understand current enforcement limits | ## Build \{#build} Step-by-step guides for building complete features. | Page | Description | | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | [Build an AI chat assistant](/managed-agents/conversations/build-chat-assistant) | Auth, a full chat turn, files, and push — end to end | | [Build an agent that uses your tools](/managed-agents/delegation-approvals/build-agent-with-tools) | Client-side tools, approval gates, and connected apps | | [Automate recurring agent work](/core-platform/scheduling/build-scheduled-agents) | A scheduled job that drives an agent and reports back | ## API reference bundles \{#api-reference-bundles} Use the [API reference](/api) when implementing a recipe: it contains the exact request and response schemas, errors and supported options. The reference follows the same product lines and capabilities as these guides. Choose a customer workflow above before selecting individual operations. ## Find the right documentation \{#retrieval-header} Start with the [conversation quickstart](/managed-agents/conversations/quickstart) for a complete first flow. Use the [API reference](/api) for operations and payloads, and the [glossary](/glossary) for product terms. Check each capability’s availability and deployment prerequisites. --- URL: https://docs.travila.ai/feedback Identify the exact documentation section, explain the outcome you need, and understand which feedback interfaces are available. # Giving feedback \{#feedback-on-travila} Use feedback to report a problem with your integration, explain a use case the product does not cover, or point out instructions that led to the wrong result. Include what you were trying to do and the documentation section you followed so the report stays connected to that experience. Product and documentation feedback submission is upcoming and is not yet available. ## Report a documentation or product problem \{#documentation-feedback} > **Info: Upcoming — not yet available** > > The experience below describes product and documentation feedback. Its submission API and form are not available yet. Report an unclear instruction, an integration failure or a missing capability against the section that describes the task. The report stays linked to the wording and availability you read, including upcoming sections beside current instructions. You receive a receipt, can follow the status of reports you are permitted to read, and can withdraw an eligible submission. ### Identify the section you read \{#identify-section} **Status:** Upcoming — not yet available. Each section shows its section ID under its heading. Copy that ID or the page URL when preparing your report. Each documentation page has a stable document ID, and each section has a stable section ID. Together they identify the subject of your feedback. The section keeps that identity when its title changes, it moves to another page location or its planned behavior becomes available. The revision identifies the exact wording you read; it can change while the section ID stays the same. For this section, copy the section ID shown beneath its heading. Use the documentation manifest to obtain its canonical link, revision and availability. You do not need a repository path or knowledge of the implementation. ### Explain the problem and expected result \{#describe-feedback} **Status:** Upcoming — not yet available. Include the context needed to understand and reproduce the problem: * The document and section IDs, canonical link and revision you read. * Whether the section describes available, preview or upcoming behavior. * Your task, the result you expected and what happened instead. * A small relevant example, plus the API or SDK version and deployment when reporting an integration failure. For example, if a guide tells you how to reconnect to a conversation but your application displays the same reply twice, identify that section and describe the duplicate result. For an upcoming capability, explain the real workflow or constraint that our described solution does not address. A request to an unavailable interface is a feature request context, not evidence that a released API failed. Keep credentials, unrelated conversations and unnecessary personal data out of the report. ### Let your agent report an integration problem \{#agent-feedback} **Status:** Upcoming — not yet available. Today, an agent can prepare a report for the developer using the section ID, the [documentation manifest](/documentation-manifest.json), and the page’s Markdown copy. The submission interface described below is upcoming. An authorized agent submits the same section context and receives a receipt for the report. It separates observed failures from statements in the documentation and includes only the context you authorize. Reading a page does not authorize uploading a conversation. If the response is lost, the agent recovers the original submission instead of filing duplicates. Status remains linked to the original section and revision after the guide changes. Reports from another customer remain private. ### Follow the result of your feedback \{#proposal-feedback-loop} **Status:** Upcoming — not yet available. We use the reported task and expected result to assess a correction or product change. The original section and revision remain attached to the report, so a later rewrite does not erase what you read. Feedback can identify a missing use case, a defect in available behavior or a change needed in an upcoming experience. Upcoming documentation describes the experience we intend to deliver. A section becomes available after its implementation and release checks; its identity stays the same as its wording and status change. Publishing that description does not set a release date or commit us to every requested adjustment. --- URL: https://docs.travila.ai/managed-agents # Managed Agents \{#managed-agents} Build a customer support assistant in small, complete recipes. Start with a signed-in text conversation that the customer can leave and reopen; add an action or attachment only after that path works. **Recommended first recipe** 1. [Build the signed-in chat](/managed-agents/conversations/build-chat-assistant): authenticate the customer, create one thread and send the first question. 2. [Follow its accepted run](/managed-agents/conversations/generation) and [restore its history](/managed-agents/conversations/streaming/subscribing) after reconnect. The result is a usable conversation, not just an accepted request. 3. [Set the support defaults](/managed-agents/conversations/configuration) and test a representative reply. Reuse a [profile](/managed-agents/profiles-prompts) when the setup needs to serve several conversations. 4. Add one useful action with [the navigation recipe](/managed-agents/delegation-approvals/build-agent-with-tools) or answer a file question with [the report-summary recipe](/managed-agents/conversations/attachments). **Finished result:** the customer can ask, return to the same conversation and receive the outcome of an authorized action or file request. Keep pending, failed and unknown outcomes visible when a step cannot finish. | Next customer task | Recipe | | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Make the first authenticated call | [Quickstart](/managed-agents/conversations/quickstart) | | Keep a conversation across visits | [Returning support conversation](/managed-agents/conversations) | | Keep a reply current and render it once | [Updates](/managed-agents/conversations/streaming) and [message reconciliation](/managed-agents/conversations/streaming/payloads) | | Explain the setting on screen | [Client context](/managed-agents/conversations/client-context) | | Resume a long thread | [Compaction](/managed-agents/conversations/context-management) | | Review an action before it runs | [Tool approval](/managed-agents/delegation-approvals/using-tools) | | Let the user inspect remembered preferences | [Memory](/managed-agents/memory-knowledge) | | Choose a route for an image or document | [Model selection](/managed-agents/model-controls), [filters](/managed-agents/model-controls/filtering) and [worked examples](/managed-agents/model-controls/examples) | | Keep a model on chosen providers | [Provider routing](/managed-agents/model-controls/provider-pinning) | | Correct a rejected model request | [Selection recovery](/managed-agents/model-controls/errors) | | Populate a task card from an object response | [Structured summary](/managed-agents/model-controls/structured-output) | | Show optional reasoning beside a reply | [Reasoning panel](/managed-agents/model-controls/reasoning) | | Update instructions shared by several assistants | [Prompt fragments](/managed-agents/profiles-prompts/prompt-fragments) | | Add a spoken conversation | [Voice (Preview)](/managed-agents/voice-media) | | Delegate a contained repository fix | [Coding assistant](/managed-agents/coding-assistants) — upcoming | | Prepare and approve a website submission | [Computer use](/managed-agents/computer-use) — upcoming | | Handle a scoped safety decision or disputed block | [Safety](/managed-agents/safety) — upcoming | Use the [conversation API reference](/api/conversations) and [profile API reference](/api/agent-profiles) for exact request fields and errors. Each recipe states its current prerequisites, limitations and availability. --- URL: https://docs.travila.ai/managed-agents/conversations # Build a support conversation the user can return to \{#add-conversations-to-your-app} Give a customer a support conversation they can leave and reopen with its history intact. Create a thread only for a new conversation, send the first question, follow its reply and reuse that thread when the customer returns. This recipe uses backend requests for one authenticated user. Start with one unresolved turn at a time so the application can correlate the accepted run with its reply. ## Before you start \{#start-here} Have the deployment's backend secret key and the authenticated user represented by `X-On-Behalf-Of`. Derive the user from your application session; do not accept an arbitrary client-supplied identity. For browser/mobile credentials, follow [authentication](/core-platform/identity-access/authentication). In the requests below, replace `support-chat-001` with the [`threadId`](/api/models/schema-1i84dsgmg6#response-field-threadid) returned by creation. Keep that identifier in your application's conversation record. Use the [first-call quickstart](/managed-agents/conversations/quickstart) if credentials are not yet set up. ## Recipe: answer a support question, then reopen the same thread \{#conversation-lifecycle} The customer asks how to reset their password. Your app creates one thread, sends that question and displays the correlated answer. On a later visit, it lists the user's threads and loads the selected thread's state instead of creating a duplicate conversation. ### Step 1: Create the support thread once \{#1-create-a-thread} [Request example: Create a new conversation thread](/api/conversations/create-thread#example-cookbook-managed-agents-conversations-index-01-request). 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. The response returns `{ "thread": { "threadId": "", ... } }`. Use [`threadId`](/api/models/schema-1i84dsgmg6#response-field-threadid) as the [`conversationKey`](/api/conversations/send-message#request-field-conversationkey) on all subsequent requests on this thread. `X-On-Behalf-Of` is required when calling with a backend secret key. ### Step 2: Send the customer’s first question \{#2-send-a-message} Use the created thread ID in this request and retain the returned [`runId`](/api/conversations/send-message#response-field-runid). A lost response is an unresolved send; follow [retry and reconciliation](/api#idempotent-requests) before attempting it again. [Request example: Send a message to a conversation](/api/conversations/send-message#example-cookbook-managed-agents-conversations-index-02-request). 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. When no prior run is active, an accepted send follows this flow. If another run is active, the [interrupt policy](/managed-agents/conversations/configuration#interrupt-policy) may queue, reject, ignore or replace it: 1. The message is appended to the thread's history. 2. A **generation run** starts asynchronously; the HTTP response returns with a [`runId`](/api/conversations/send-message#response-field-runid). 3. The LLM processes the conversation history and generates a response. 4. If the model calls tools, tool execution happens automatically (or awaits approval). 5. The assistant response is appended to [`messageHistory`](/api/conversations/get-conversation-state#response-field-messagehistory), annotated with `generatedBy: `. If a prior run was still in progress and the thread's [`interruptPolicy`](/api/models/schema-ph6avse89k#request-field-interruptpolicy) is `INTERRUPT_POLICY_CANCEL_ONGOING` (cancel ongoing), [`send-message`](/api/conversations/send-message) also returns `"interruptedPriorRun": true` alongside the new [`runId`](/api/conversations/send-message#response-field-runid). To retrieve the completed assistant reply from an external client, poll [`conversation-state`](/api/conversations/get-conversation-state) — see [Async Generation](/managed-agents/conversations/generation#async-generation). ### Step 3: Display the reply for the accepted run \{#3-retrieve-state} [Request example: Get full conversation state](/api/conversations/get-conversation-state#example-cookbook-managed-agents-conversations-context-management-03-request). 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. Returns [`messageHistory`](/api/conversations/get-conversation-state#response-field-messagehistory), the run status fields, [`totalUsage`](/api/conversations/get-conversation-state#response-field-totalusage), settings, generation config, and context-management settings. While a run is in progress, [`activeRunning`](/api/conversations/get-conversation-state#response-field-activerunning) is `true` and [`activeRunId`](/api/conversations/get-conversation-state#response-field-activerunid) holds the run's ID; after activity stops, [`activeRunning`](/api/conversations/get-conversation-state#response-field-activerunning) is absent. Match any assistant reply by [`generatedBy`](/api/models/schema-1j3dcf7kvu#response-field-generatedby) and check the outcome for your run; a failed or queued request may have no completed reply. See [Async Generation](/managed-agents/conversations/generation#async-generation) for the full polling recipe. Render messages by stable identity and numeric 64-bit sequence. Keep the submitted operation pending or unknown until its outcome is correlated; missing [`activeRunning`](/api/conversations/get-conversation-state#response-field-activerunning) alone does not prove success. Offer a read/reconnect action when your bounded wait ends. ### Step 4: Reopen the conversation on the next visit \{#4-list-threads} When the user returns, list their threads, let them choose this support conversation and read its state with the selected thread ID. Send a follow-up with that same ID to continue the history. List the authenticated user’s conversations with default paging. [Request example: List conversation threads](/api/conversations/list-threads#example-conversations-listThreads-request). 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. Returns one page of the authenticated user's threads — 50 by default and up to 200 with [`limit`](/api/conversations/list-threads#request-field-limit) — ordered by [`lastMessageAt`](/api/models/schema-p16s9mefht#response-field-lastmessageat) descending, then [`threadId`](/api/models/schema-1i84dsgmg6#response-field-threadid) descending. Follow [`nextPageToken`](/api/conversations/list-threads#response-field-nextpagetoken) until a response has no token. See [`list-threads`](/api/conversations/list-threads) for the cursor and concurrency rules. **Finished result:** the customer sees the original question and its correlated reply, can reopen that thread, and adds follow-ups to its existing history. A short page of threads is not a complete inventory when a continuation token is present. ## Recover the same conversation when a reply is missing \{#core-concepts} After a lost connection, reload the existing thread with the same authenticated user. Keep its [`threadId`](/api/models/schema-1i84dsgmg6#response-field-threadid) as the [`conversationKey`](/api/conversations/send-message#request-field-conversationkey); a title is a display label, not the identity used for recovery. Merge [`messageHistory`](/api/conversations/get-conversation-state#response-field-messagehistory) by message ID and numeric sequence and render each message according to its role. Read current activity separately from the accepted question’s result. [`lastRunStatus`](/api/conversations/get-conversation-state#response-field-lastrunstatus) is the latest recorded outcome and can describe newer work, while an assistant message’s [`generatedBy`](/api/models/schema-1j3dcf7kvu#response-field-generatedby) can identify its run. Use [the reconnect recipe](/managed-agents/conversations/streaming/subscribing) for a pending or unknown turn, [tool approvals](/managed-agents/delegation-approvals/using-tools) when a decision is waiting, and [the state reference](/api/conversations/get-conversation-state) for exact fields. Reopening history does not require another create or send request. ## Related \{#related} * [Quickstart](/managed-agents/conversations/quickstart) — Make your first API call * [Authentication & API Keys](/core-platform/identity-access/authentication) — Keys, scopes, and acting on behalf of a user * [Conversation updates](/managed-agents/conversations/streaming) — Available update and recovery options * [Build an AI chat assistant](/managed-agents/conversations/build-chat-assistant) — End-to-end client integration * [Agent tools guide](/integrations/tools-connections) — Tool calling in conversations * [Memory Guide](/managed-agents/memory-knowledge) — Semantic memory for conversations * [LLM API Reference](/api/conversations) — Full endpoint reference --- URL: https://docs.travila.ai/managed-agents/conversations/configuration # Configure a support conversation that stays predictable \{#configure-how-your-agent-responds} Set up a support conversation with a chosen model, bounded replies and one unresolved turn at a time. Start with thread defaults and no active profile so each setting has one clear source. Then verify a real reply before adding profiles, tools or specialized input processing. **Finished recipe:** the conversation stores the intended defaults, rejects a competing send while a turn is active, and returns a correlated test reply or an explicit failure you can diagnose. ## Before you start: choose the configuration source \{#get-started} Create a thread with [the conversation recipe](/managed-agents/conversations) and keep its ID. Replace `support-chat-001` in the requests below with that ID. Use your backend secret plus the authenticated user's `X-On-Behalf-Of`, or the documented client credential pair. Use an unprofiled thread for the main recipe. If you already selected a profile, its configuration can replace thread defaults; either use the [profile variant](#agent-profiles) or create a separate unprofiled test thread. An empty profile selector cannot clear a prior selection. Choose an [allowed model](#available-models) for your account. The sample settings bound the answer length; they are not a promise of identical output or a total spending budget. ## Step 1: Set the model and answer length \{#generation-config} Use the request below to set this conversation’s model and a 2,048-token answer limit. Replace the model with one accepted by your account and keep the same [`conversationKey`](/api/conversations/send-message#request-field-conversationkey) through the recipe. [Request example: Update default generation config](/api/conversations/update-default-generation-config#example-cookbook-managed-agents-conversations-configuration-01-request). 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. Temperature and [`topP`](/api/models/schema-1h82h7ri5p#request-field-topp) tune sampling; they do not guarantee identical replies. The [GenerationConfig request fields](/api/models/schema-1h82h7ri5p#request) list every public field and its request validation rules. Use the [update operation reference](/api/conversations/update-default-generation-config) for the complete request and response. Generation configuration ### Set the support instructions with the generation defaults \{#system-prompt} Add your support instructions as [`defaultGenerationConfig.systemPrompt`](/api/models/schema-1h82h7ri5p#request-field-systemprompt) to the complete configuration from step 1, then resend that object through [update-default-generation-config](/api/conversations/update-default-generation-config). This operation replaces the stored generation defaults; sending only the prompt would drop the model and answer limit you just set. For an existing conversation, read its current defaults first and retain every setting you intend to keep. Keep the instructions focused on the assistant’s help; enforce permissions for account actions in your tools and application. ## Step 2: Keep one unresolved turn at a time \{#conversation-settings} Use `REJECT_NEW` for this first chat flow. Your UI can keep the submitted turn pending and offer reconnect while it resolves, rather than accepting another send whose queued outcome is harder to correlate. The configuration below also caps the generation loop. The request sets the interrupt policy and generation limit. Keep support instructions in [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig), as in step 1. [Request example: Update conversation settings](/api/conversations/update-settings#example-cookbook-managed-agents-conversations-configuration-02-request). 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. If a second send is rejected while a run is active, reconnect to the first run; do not treat that rejection as failure of the original question. ### Choose enough generations for the reply and any tools \{#max-loops} For a text-only test, one generation is enough. If you later add a lookup tool, allow at least the initial tool call and the following synthesis generation, then check [the actual outcome at the limit](/api/models/schema-ph6avse89k#overview). ## Step 3: Keep a long support thread within its context limits \{#context-management} For the first short test, use the default windowing strategy. Before supporting long customer histories, choose the [compaction recipe](/managed-agents/conversations/context-management) or a deliberate window size. Choose the strategy before persisting it: [the current update path rejects changing an explicit strategy to another one](/api/conversations/context-and-compaction#configuration-context-management). ## Step 4: Send a test question and verify the applied configuration \{#how-settings-combine} Read `conversation-state` to inspect the stored defaults and settings. Send one representative support question, retain the returned [`runId`](/api/conversations/send-message#response-field-runid), and follow [generation outcomes](/managed-agents/conversations/generation) until its result is known. If the response differs from the intended configuration, use [configuration precedence](/api/model-controls/configuration#configuration-how-settings-combine) to find the source that took precedence. **Finished result:** the stored conversation defaults and interrupt policy match your choices, and the test turn has a correlated outcome. Do not judge configuration success from an idle conversation or a saved settings response alone. Keep the conversation/run references when the result remains uncertain. ## Variant: reuse the same assistant setup across conversations \{#agent-profiles} Once the thread-default recipe works, [create and test a reusable profile](/managed-agents/profiles-prompts) for the same project. Profile management uses the backend secret alone; the conversation calls below still require the authenticated user. Select the saved profile when creating a conversation. The illustrations below use sample nutrition and escalation IDs; replace both with the enabled support profile you created, and choose a title for your support conversation. These names do not identify preinstalled platform profiles: [Request example: Create a new conversation thread](/api/conversations/create-thread#example-cookbook-managed-agents-conversations-configuration-json-01-request). Example identifiers and values are illustrative; substitute authorized values. For an existing conversation, select an enabled replacement on a send. This selection persists for later turns: [Request example: Send a message to a conversation](/api/conversations/send-message#example-cookbook-managed-agents-conversations-configuration-json-02-request). Example identifiers and values are illustrative; substitute authorized values. Read back the selected profile and inspect a later reply. [Recheck the intended tool selection](/api/agent-profiles/selection-and-versioning#configuration-agent-profiles) when changing profiles. ## Variant: personalize the profile for this customer \{#prompt-variables} Use profile variables for facts such as the customer's name or current plan tier. Declare the matching placeholders in the profile, set the actual values on this conversation, then send a new turn. [These values persist until changed](/api/agent-profiles/selection-and-versioning#configuration-prompt-variables); update them when the application fact changes. First set the customer’s name and current plan. When the plan changes later, use the second request to select only that variable in the update mask, then verify it on the next turn. [Request example: Update prompt variables](/api/conversations/update-prompt-variables#example-cookbook-managed-agents-conversations-configuration-03-request). 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. **Response:** `{"settings": {...}}` — the merged conversation settings. [Request example: Update prompt variables](/api/conversations/update-prompt-variables#example-cookbook-managed-agents-conversations-configuration-json-03-request). Example identifiers and values are illustrative; substitute authorized values. ### Check the next turn after a value changes \{#render-timing} After changing `planTier` to `enterprise`, send a new question on the same conversation and check that the reply uses the updated plan. [Variables render when the next turn starts](/api/agent-profiles/selection-and-versioning#configuration-render-timing); changing a value does not rewrite a reply already in progress. ### Change or clear only the intended variables \{#updatemask-semantics} For a plan change, keep `updateMask: "planTier"` so unrelated values such as the customer’s name stay unchanged. To clear a variable, include its name in the mask and omit its value from the update. Read the settings back before the next send. The [mask rules](/api/conversations/update-prompt-variables#overview) distinguish a selected-but-absent value from a variable that was not selected. ### Supply required values before sending \{#required-variables-and-defaults} For this existing-conversation recipe, inspect the selected profile’s variable definitions and set `userName` and `planTier` explicitly if required. Current sends do not repeat the required-variable check, so your application must verify the values before sending, especially after changing profiles or their definitions. When creating a thread with a selected profile, creation rejects a missing required variable without a nonempty default. A declared nonempty default suppresses that creation error but is not inserted into the prompt. [Set the intended values explicitly](/api/models/schema-1hkadmq6cl#overview), then verify the test reply. ### Recover a conversation whose profile is unavailable \{#when-the-active-profile-cannot-be-used} [Restore an enabled profile or select an enabled replacement](/api/agent-profiles/selection-and-versioning#configuration-when-the-active-profile-cannot-be-used) before sending the customer’s question again. Keep the original conversation and inspect any already accepted turn separately. ## Variant: choose what another send does during a run \{#interrupt-policy} Keep `REJECT_NEW` unless your application has a reason to [replace, queue or ignore competing messages](/api/conversations/messages-and-runs#configuration-interrupt-policy). Decide what the user sees before selecting a different policy; the queue and ignore paths do not mean that the new question produced a reply. ## Variant: add only the services this assistant needs \{#mcp-server-selection} For a support assistant that needs an account lookup, first connect and test the server using [agent tools](/integrations/tools-connections). [Select the server here](/api/tools/selection#configuration-mcp-server-selection), then repeat the send/tool/result recipe. A connected account alone does not add its tools to every conversation. ## Variants for particular inputs and response formats \{#advanced-generation-options} Start with the plain text recipe. Add the options below only for a concrete input or response requirement, and inspect the returned run outcome after each change. Use the [complete generation schema](/api/conversations/update-default-generation-config) for all accepted fields. ### Read a PDF or include web search \{#plugins} When the user supplies a PDF, select a supported parsing engine for that file. When the question needs web evidence, [configure the search plugin separately](/api/model-controls/configuration#configuration-plugins). Attach the source through the normal conversation request and inspect whether the answer actually received the needed content. ### Guide a bounded multi-step reply \{#turn-context-turncontext} For a reply that needs supporting tools, choose the [generation limit](#max-loops) first. [Turn context is enabled by default](/api/models/schema-1h5dj58uph#overview) and tells the model the generation number and remaining turns, with tool guidance based on that remaining allowance. Inspect whether the final reply explains unfinished work when the limit is reached. ### Fail the request when a required file is unavailable \{#file-resolution-fileresolution} For a report summary that cannot be useful without the report, use [the attachment recipe](/managed-agents/conversations/attachments#decide-whether-the-file-is-required) to select `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` before the send. If resolution fails, [the run fails before provider generation](/api/models/schema-1ftcunpmha#overview). Follow its correlated outcome: an asynchronous send can already have been accepted before the file failure occurs. ### Ask for replies in the customer’s chosen language \{#language-preference-languagepreference} Choose the customer’s language, [save the preference](/api/models/schema-1h82h7ri5p#overview) and send a representative question. Inspect the returned language instead of treating a saved setting as proof of the answer. ## Variant: show optional reasoning beside the answer \{#reasoning} Add a reasoning panel only when the product needs provider-exposed reasoning alongside the answer. Follow [the reasoning-panel recipe](/managed-agents/model-controls/reasoning), choose a model that supports the requested controls and keep the answer usable when reasoning is absent. Unsupported settings may be ignored or rejected. Returned `CONTENT_PART_TYPE_REASONING` content is provider-defined; it is not guaranteed access to full internal reasoning. Use the [generation configuration reference](/api/conversations/update-default-generation-config) for [`reasoning`](/api/models/schema-1h82h7ri5p#request-field-reasoning) fields, defaults and accepted values. ## Recover an unsupported model selection \{#available-models} Choose a model accepted for the account and suitable for the input. After [an explicit selection rejection](/api/model-controls/routing#configuration-available-models), correct the choice before submitting the task again. --- URL: https://docs.travila.ai/managed-agents/conversations/context-management # Resume a long conversation with a compacted history \{#manage-context-and-compaction} Help a customer continue a long support thread without sending all older messages verbatim on every turn. This recipe summarizes older messages, preserves the ten most recent messages and checks the compaction record before the next reply. Start with synchronous compaction when the next answer must wait for the summary. Use an existing thread with older messages beyond the preserved span, user-scoped credentials and permission for the summarizer call. Keep source records available when exact details matter: a summary can omit or distort them. Choose the strategy deliberately. Once an explicit strategy is stored, the current API rejects switching to a different strategy. Use a suitable separate test conversation if the existing one is locked to another strategy. ## Recipe: compact the older history, then continue the thread \{#get-started} Replace `support-chat-001` with the existing thread ID and keep that ID through all three steps: 1. **Set a compaction threshold** — configure the strategy and trigger on the thread. This example compacts synchronously at 80% of the model's context window, keeping the 10 most recent messages verbatim: [Request example: Update context management settings](/api/conversations/update-context-management-settings#example-cookbook-managed-agents-conversations-context-management-01-request). 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. 2. **Trigger a manual compaction** — compact the thread now rather than waiting for the threshold. Useful at app launch before a user resumes a long conversation: [Request example: Compact a conversation](/api/conversations/compact-conversation#example-cookbook-managed-agents-conversations-context-management-02-request). 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. **Response** (sync — blocks until done): [Response example: Compact a conversation](/api/conversations/compact-conversation#example-cookbook-managed-agents-conversations-context-management-json-01-response). Example identifiers and values are illustrative; substitute authorized values. [Treat the token counts as diagnostics](/api/conversations/compact-conversation#overview). Confirm the compaction outcome and inspect the follow-up answer before considering this recipe complete. 3. **Read the result** — poll `conversation-state` and inspect the [`compactions`](/api/conversations/get-conversation-state#response-field-compactions) array: [Request example: Get full conversation state](/api/conversations/get-conversation-state#example-cookbook-managed-agents-conversations-context-management-03-request). 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. **Response** (excerpt): See [Get full conversation state](/api/conversations/get-conversation-state#responses) for the full field contract. This excerpt illustrates the relevant choices; replace identifiers with your own authorized values. * `compactionInProgress`: boolean false. * `compactions[0].id`: text cmp\_a1b2c3d4. * `compactions[0].startSequence`: text 1. * `compactions[0].endSequence`: text 47. * `compactions[0].status`: text COMPACTION\_STATUS\_COMPLETED. * `compactions[0].triggerReason`: text COMPACTION\_TRIGGER\_REASON\_MANUAL. * `compactions[0].originalTokenCount`: number 48211. * `compactions[0].summaryTokenCount`: number 604. * `compactions[0].modelUsed`: text anthropic/claude-haiku-4. Response excerpt: [Get full conversation state](/api/conversations/get-conversation-state) · [Response fields](/api/conversations/get-conversation-state#responses). After the recorded compaction completes, send the customer's follow-up on the same thread and follow its [generation outcome](/managed-agents/conversations/generation). Inspect whether the reply retains the details needed for the support task. **Finished result:** the compaction record identifies the summarized message span, recent messages remain available verbatim, and the follow-up has a correlated outcome. The sample token counts illustrate a response; they are not a promised compression ratio, invoice saving or cache hit. ## Verify the summary that the next reply can use \{#watch-a-compaction-complete} Match the returned [`compactionId`](/api/conversations/compact-conversation#response-field-compactionid) to its record in `conversation-state.compactions`. [Check that it completed](/api/conversations/context-and-compaction#context-management-watch-a-compaction-complete) and that [`startSequence`](/api/models/schema-1fpqunnq41#response-field-startsequence) and [`endSequence`](/api/models/schema-1fpqunnq41#response-field-endsequence) cover the intended source messages. Retain the reported summarizer model and counts when investigating a changed answer; [the state reference](/api/conversations/get-conversation-state) describes the record fields. ### Variant: refresh the record from live updates (Preview) \{#realtime-events-preview} When your deployment supports [live compaction updates](/api/conversations/context-and-compaction#context-management-realtime-events-preview), use them to refresh the same compaction record. Keep the state-read path for reconnects and deployments without that transport. The compaction ID and recorded result remain the basis for deciding whether to continue the recipe. ## Recover when compaction fails before the reply \{#failure-behavior} Inspect the failed compaction and the original reply before deciding whether to submit anything again. Recover the existing work using [the linked failure behavior](/api/conversations/context-and-compaction#context-management-failure-behavior); do not resend the customer’s question simply to restart background summarization. ## Variant: keep a window or full history instead \{#choose-a-strategy} Choose windowing when older details are no longer needed. Select the strategy before saving the conversation setup and check [the supported changes](/api/conversations/context-and-compaction#context-management-choose-a-strategy) in the reference. Keep full history with `CONTEXT_STRATEGY_NONE` only while the assembled request fits the selected provider’s limits. Use compaction when older context still matters and an additional summarizer call is acceptable, remembering that summaries can omit or distort details. ## Tune the recipe for longer-running conversations \{#how-compaction-works} [Tune the recipe](/api/conversations/context-and-compaction#context-management-how-compaction-works) Tune the recipe only after inspecting a completed compaction and its follow-up answer: 1. **Keep enough recent context.** [`preserveRecent`](/api/models/schema-1hbvkcgu5m#request-field-preserverecent) counts messages, not turns. Keep the recent exchange the customer will refer to; those messages follow the summary verbatim. 2. **Leave headroom for the next request.** Choose an absolute-token or percentage threshold below the provider’s actual limit. Prompts, tools and other request processing can change the final size. 3. **Choose the summarizer when needed.** Supply a supported [`generationConfig`](/api/models/schema-1hbvkcgu5m#request-field-generationconfig) inside [`compactionConfig`](/api/models/schema-1hgrvsu34j#request-field-compactionconfig) to change its model or sampling options; otherwise the platform uses its default compaction model. 4. **Inspect the next answer and usage.** Change one setting at a time. A completed summary is marked cache-preferred, but provider reuse and lower total cost are not guaranteed. Use reported token estimates to choose context settings, not calculate an invoice. See [usage and cost](/insights/usage-cost) for measured and missing usage. ### Variant: let the current turn proceed while a summary is pending \{#sync-vs-async} Wait for the summary when the next answer needs it. Use [background compaction](/api/conversations/context-and-compaction#context-management-sync-vs-async) only when the current reply can work with the existing history, then check that reply and the summary separately. ### Resolve a compaction that stays pending \{#stale-pending-compactions} Refresh the existing compaction record and inspect its current outcome before requesting another summary. [A pending indicator alone does not prove work is still running](/api/conversations/context-and-compaction#context-management-stale-pending-compactions). ## Variant: omit a file or tool result that later replies no longer need \{#trim-content-selectively} After an attachment or lookup has served its purpose, exclude it from later model inputs only if later questions do not need the original content. The example drops images and tool-result payloads; [stored history is retained](/api/conversations/context-and-compaction#context-management-trim-content-selectively). Example — strip images and tool results, keep everything else: [Request example: Update context management settings](/api/conversations/update-context-management-settings#example-cookbook-managed-agents-conversations-context-management-04-request). 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. Exclude material only when later replies no longer need it. For example, removing a large image from later requests can reduce their size, but the model cannot re-inspect that image unless you provide it again. ## Related \{#related} * [Configure how your agent responds](/managed-agents/conversations/configuration) — model, sampling, system prompt, and windowing config * [Send messages and get replies](/managed-agents/conversations/generation) — the generation loop, polling, and sync mode * [Streaming availability](/managed-agents/conversations/streaming) — deployment-specific updates and state-read recovery --- URL: https://docs.travila.ai/managed-agents/conversations/generation # Get a customer’s reply and recover an interrupted send \{#send-messages-and-get-replies} Build the part of chat that turns one customer question into a visible answer. Use asynchronous send plus bounded state reads for the main recipe. Retain the accepted run so a disconnect does not cause another copy of the question to run. Before starting, create a thread and obtain its user-scoped credentials. Replace the example conversation ID with that thread's ID. Keep one unresolved send at a time for the initial integration; the current state response cannot correlate every queued or concurrent operation. The backend summary and context-only event recipes later in this guide use the same conversation with different completion needs. ## Recipe: send a question without holding the request open \{#async-generation} Use [`send-message`](/api/conversations/send-message) to release the connection after acceptance and retrieve the reply through [`conversation-state`](/api/conversations/get-conversation-state). Validation and context preparation happen before acceptance; the response does not wait for the newly admitted run’s model answer. Keep one unresolved turn for this first flow. ### Step 1: Send once and read the same conversation \{#worked-example} **Send the message:** [Request example: Send a message to a conversation](/api/conversations/send-message#example-cookbook-managed-agents-conversations-generation-01-request). 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. Response: [Response example: Send a message to a conversation](/api/conversations/send-message#example-cookbook-managed-agents-conversations-build-chat-assistant-json-03-response). Example identifiers and values are illustrative; substitute authorized values. **Read the same conversation with [`conversation-state`](/api/conversations/get-conversation-state):** [Request example: Get full conversation state](/api/conversations/get-conversation-state#example-cookbook-managed-agents-conversations-build-chat-assistant-04-request). 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. **Mid-generation response** (while generation is in progress): [Response example: Get full conversation state](/api/conversations/get-conversation-state#example-cookbook-managed-agents-conversations-generation-json-02-response). Example identifiers and values are illustrative; substitute authorized values. **Example settled response** (timing depends on the model, tools and load): [Response example: Get full conversation state](/api/conversations/get-conversation-state#example-cookbook-managed-agents-conversations-generation-json-03-response). Example identifiers and values are illustrative; substitute authorized values. In this isolated example, [`activeRunning`](/api/conversations/get-conversation-state#response-field-activerunning) is absent and the matching assistant message is present. In a busy conversation, [`lastRunStatus`](/api/conversations/get-conversation-state#response-field-lastrunstatus) describes the most recent outcome and may refer to another request; history can contain earlier turns. > **Caution: Retrying a send** > > A lost response does not prove the run failed. Repeating a send can create duplicate work; do not assume an idempotency header makes it safe. Follow [retry and reconciliation guidance](/api#idempotent-requests) before repeating a send. The finished chat turn needs both a reply associated with the retained run and a correlated terminal outcome. The sample is an isolated run; use the steps below when other work or a lost connection makes that correlation uncertain. ### Step 2: Finish or recover the accepted turn \{#polling-recipe} 1. Call [`send-message`](/api/conversations/send-message) once and retain the conversation and returned [`runId`](/api/conversations/send-message#response-field-runid). An accepted or queued response is not a completed reply. 2. Read [`conversation-state`](/api/conversations/get-conversation-state) with a bounded polling interval and overall deadline; two seconds between reads and a sixty-second UI deadline are example client choices, not completion SLAs. Honor throttling and back off. 3. Match assistant messages using [`generatedBy`](/api/models/schema-1j3dcf7kvu#response-field-generatedby) when it identifies the accepted run. Use [`activeRunning`](/api/conversations/get-conversation-state#response-field-activerunning) and [`activeRunId`](/api/conversations/get-conversation-state#response-field-activerunid) to describe current activity, not to infer the outcome of every prior request. An intermediate tool-round message does not finish the run. 4. Use [`lastRunStatus`](/api/conversations/get-conversation-state#response-field-lastrunstatus) only when you can establish that it describes the same run. The current state response does not provide a full per-request outcome lookup for all queued/concurrent cases. If correlation is missing or ambiguous, preserve an unknown/pending outcome and reconcile; do not report success from idle alone. 5. At your client deadline, stop automatic polling and offer a read/reconnect action. Do not send the mutation again to find out whether it succeeded. For a new single-user flow, avoid concurrent sends while one turn is unresolved. **Finished result:** your UI shows the answer for the accepted run, a recognized unsuccessful outcome, or an explicit unresolved state with a reconnect path. It never converts idle activity, an HTTP success response or an intermediate tool message into proof that this question was answered. Some older threads retain their last [`activeRunId`](/api/conversations/get-conversation-state#response-field-activerunid) after the run ends. Test activity through [`activeRunning`](/api/conversations/get-conversation-state#response-field-activerunning), and use the correlated result to decide completion. See [the state reference](/api/conversations/get-conversation-state) for the complete schema and [streaming availability](/managed-agents/conversations/streaming) for deployment-specific live updates. ## Separate recipe: wait for a backend summary in the response \{#synchronous-generation} For a backend task that needs a summary before continuing, configure the required object schema with [structured output](/managed-agents/model-controls/structured-output), then use [the bounded synchronous request below](/api/conversations/send-message-sync#overview). The prompt asks for a summary, but asking for JSON is not itself schema configuration. [Request example: Send a message and wait for the result](/api/conversations/send-message-sync#example-cookbook-managed-agents-conversations-generation-03-request). 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. **Response** — the generated messages, with token usage, returned directly: [Response example: Send a message and wait for the result](/api/conversations/send-message-sync#example-cookbook-managed-agents-conversations-generation-json-04-response). Example identifiers and values are illustrative; substitute authorized values. ### Accept the result only when the run has finished \{#interpret-the-outcome} HTTP `200` means the request returned a response, not that generation succeeded. Use the [run-outcome table](/api/conversations/messages-and-runs#generation-interpret-the-outcome) to interpret [`status`](/api/conversations/send-message-sync#response-field-status) and the messages separately. For the backend recipe, validate and consume the returned object only after the correct run completes. A queued, active or tool-wait result returns control to your application; retain the operation and continue recovery instead of substituting an empty summary. ### Recover a summary that failed or returned no explanation \{#failed-responses-and-diagnostics} [A failed run can return HTTP `200`](/api/conversations/messages-and-runs#generation-failed-responses-and-diagnostics) with a body such as: [Response example: Send a message and wait for the result](/api/conversations/send-message-sync#example-cookbook-managed-agents-conversations-generation-json-05-response). Example identifiers and values are illustrative; substitute authorized values. Keep the conversation ID and [`runId`](/api/conversations/send-message#response-field-runid) for investigation. When an evaluation backend is provisioned, [read traces and observations](/insights/evaluation/reading) for separate diagnostics such as [`statusMessage`](/api/models/schema-1ju9tclufp#response-field-statusmessage); locate the turn using the trace ID or conversation ID plus source user message ID, as described in [Addressing a turn](/insights/evaluation/reading#open-one-trace). Trace content is redacted, and an unprovisioned evaluation backend returns `424` — see [Evals](/insights/evaluation). These APIs are a separate diagnostic path, not a guarantee of an inline failure explanation. For JSON/structured replies, set [`responseFormat`](/api/models/schema-1h82h7ri5p#request-field-responseformat) in the [generation config](/managed-agents/conversations/configuration#generation-config). > **Caution: Retrying a send** > > A lost response does not prove the run failed. Repeating a send can create duplicate work; do not assume an idempotency header makes it safe. Follow [retry and reconciliation guidance](/api#idempotent-requests) before repeating a send. #### Explain why a summary failed \{#inline-failure-details} **Status:** Upcoming — not yet available. When a backend summary fails, the synchronous send and tool-result responses include an optional inline `error` from that same run. Use it as the first explanation, then follow the trace-recovery steps above if it is missing or you need more context. Details can still be unavailable: keep checking the run’s [`status`](/api/conversations/send-message-sync#response-field-status) and preserve its ID and any partial reply. A missing explanation does not turn a failed summary into a successful empty result. The [send reference](/api/conversations/send-message-sync) and [tool-result reference](/api/conversations/submit-client-tool-results-sync) define the proposed lookup limits. ## Separate recipe: record an onboarding event without another reply \{#append-a-message} When your application confirms onboarding, record that fact for later conversation context [without immediately asking the model to speak](/api/conversations/append-message#overview). Use the example event below only after the application has confirmed it; text in history cannot grant an entitlement. [Request example: Append a message without generating](/api/conversations/append-message#example-cookbook-managed-agents-conversations-generation-04-request). 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. **Finished result:** the event is present in thread history and no generation was started by this append. The next ordinary message can use stored history according to its context settings; the append does not change a provider request already in flight. --- URL: https://docs.travila.ai/managed-agents/conversations/streaming # Keep a chat reply current while the user waits \{#receive-conversation-updates} Keep your chat display up to date with conversation-state reads. If your deployment also provides live updates, use its connection instructions and refresh state after a disconnect. The native conversation operations do not use the OpenAI wire protocol. An OpenAI SDK cannot call them by changing its base URL alone. For the first implementation, choose asynchronous send plus state reads. You need an authenticated thread and the run ID retained from the send. Add deployment-specific live updates only after the same read/recovery path works. ## Recipe: update the reply and recover a dropped connection \{#get-replies-with-the-current-api} Use the [send-and-poll recipe](/managed-agents/conversations/generation#polling-recipe) to submit a turn and follow its outcome with the current API. Keep the returned conversation and turn identifiers so recovery reads the same work. After a dropped response, reconcile the original turn before sending again. A second send can create new work or invoke the configured concurrency policy. Streaming or live-view availability is deployment-specific; use the transport guidance below and confirm that the selected surface is enabled. ## Variant: add live updates available in your deployment \{#integrate-a-qualified-streaming-transport} Follow the deployment's connection instructions, load the current authorized state and use live updates to keep the view responsive. Retain the state-read path for reconnect and missing events. A snapshot plus a live subscription is not automatically gap-free. The public API reference does not provide a universal subscription URL or replay cursor. Use the state-read recovery flow in [receiving updates](/managed-agents/conversations/streaming/subscribing) and the field interpretation in [interpreting updates](/managed-agents/conversations/streaming/payloads). A deployment-specific subscription does not replace authoritative state reads. See [API conventions](/api) for the current native protocol and [conversation generation](/managed-agents/conversations/generation) for reply handling. ## Upcoming recipe: stream a reply through the client’s chosen protocol \{#native-and-compatible-streams} **Status:** Upcoming — not yet available. Choose native conversation run events when the client needs Travila run/tool status, or a supported OpenAI Responses or Chat Completions interface for an application using that protocol. A self-hosted deployment path supports these streaming workflows. 1. Start with that transport’s authentication and event contract. 2. Keep the accepted run and individual attempt distinct while displaying partial answer content provisionally. 3. Continue complete tool calls through the matching protocol. 4. Follow [the reconnection flow](/managed-agents/conversations/streaming/subscribing#resumable-subscriptions) after a disconnect and use [event identities and outcomes](/managed-agents/conversations/streaming/payloads#event-identities-and-outcomes) to reconcile the final result. **Finished result:** incremental output leads to a recognizable terminal outcome. Native and compatible payloads stay within their own protocol; provisional text does not complete the run. Each transport defines its own authentication, event schema, terminal outcomes, replay boundary and retention limits. Subscription URLs and SDK setup for these interfaces are not yet available. Current native REST operations retain their existing protocol. --- URL: https://docs.travila.ai/managed-agents/conversations/streaming/payloads # Show one correct chat history as updates arrive \{#interpret-conversation-updates} Show users whether their reply is still arriving, waiting for a tool or complete. Use the native API's conversation state and generation outcomes to keep each displayed message tied to the right run. Deployment-specific subscriptions can also provide updates, but their payloads are not interchangeable with the native response. This guide covers fields available through the [state endpoint](/api/conversations/get-conversation-state) and [generation operations](/managed-agents/conversations/generation). Use this recipe after [sending a question](/managed-agents/conversations/generation): keep its run identity, merge incoming or reloaded messages once, then mark the question complete only from a correlated outcome. You need the persisted history and the accepted run ID; a timestamp is not a replacement. ## Step 1: Keep the thread, run and messages separate \{#keep-identities-distinct} Store the conversation ID for future reads and the run ID for this submitted question. Merge messages using their stable identities and order them by numeric sequence. Use the [identity reference](/api/conversations/messages-and-runs#payloads-keep-identities-distinct) to choose the identifier for each part of that recipe. Preserve message sequence precision when merging the stored history. For example, reloading a message you already displayed updates the same item. A message from a later run can belong in the history while still being the wrong evidence for completion of the earlier pending question. ## Step 2: Display progress, then the correlated final outcome \{#render-and-reconcile} Display partial streamed text as provisional. [A model finish reason or a completed message](/api/conversations/messages-and-runs#payloads-render-and-reconcile) can end one model attempt while a tool round or run continues. Use the returned status and run identity to interpret the outcome; missing or unknown status does not mean success. The [generation outcome table](/managed-agents/conversations/generation#interpret-the-outcome) covers completed, failed, cancelled, timed-out and waiting states. Execute client tools only from complete pending calls and their current [`clientToolCursor`](/api/conversations/send-message-sync#response-field-clienttoolcursor), using the [client-tool protocol](/managed-agents/delegation-approvals/using-tools#client-side-tools). Do not execute incomplete argument fragments. Usage data may arrive later than text or be absent. Missing counters are not zero cost. Display optional [reasoning content](/managed-agents/model-controls/reasoning) separately from the answer. Send the next message to the same conversation; you do not need to assemble provider continuation data for the native API. **Finished result:** each persisted message appears once, provisional content stays provisional until resolved, and the pending question receives its own known outcome or an explicit unresolved state. Missing usage remains unknown, and a tool callback refers to a complete pending call rather than argument fragments. ## Upcoming recipe: merge replayed events without duplicating the reply \{#event-identities-and-outcomes} **Status:** Upcoming — not yet available. Use this flow when a live reply must survive replay without duplicating a message: 1. Keep the conversation, accepted run, attempt, persisted message and transport delivery identities distinct. Merge a repeated delivery by its event identity. 2. Retain the resume cursor for replay. A timestamp cannot replace the cursor or event identity. 3. Keep text and tool arguments provisional until the relevant item is complete; a finished message or tool round can still precede the run’s final outcome. 4. Correlate the terminal outcome with the accepted run. For an unrecognized event, refresh state and keep the outcome unresolved until understood. If two text chunks arrive before a run fails, leave those chunks visibly incomplete and show the failed outcome. Display optional reasoning separately. Late or missing usage stays late or missing, and attempt counters retain their measurement boundaries. **Finished result:** replay does not add another message, and received text cannot turn a failed stream into a successful answer. These event contracts are not yet available through the current state endpoint. Its existing fields are documented above. --- URL: https://docs.travila.ai/managed-agents/conversations/streaming/subscribing # Restore a chat after the connection drops \{#receive-updates-and-reconnect} Restore the user's conversation after a message is sent or a connection is lost. Read the native state endpoint, merge the returned history and reconcile the accepted run before offering another send. An additional subscription may be available for your deployment, but the public reference does not expose a universal streaming URL or replay cursor. Before a disconnect occurs, keep the conversation ID, the accepted run ID and the messages already displayed. Use the same authenticated user on reconnect. Start with state reads; a live transport is optional and deployment-specific. ## Step 1: Reload the original conversation \{#read-the-current-conversation} Keep the conversation key and the [`runId`](/api/conversations/send-message#response-field-runid) returned when the send is accepted. Reuse the same authorized scope when reading: [Request example: Get full conversation state](/api/conversations/get-conversation-state#example-cookbook-managed-agents-conversations-context-management-03-request). 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. Replace the key with your created thread. Follow [asynchronous generation](/managed-agents/conversations/generation#async-generation) for the complete send-and-read loop. Use the returned history to restore the display, then [reconcile the original accepted run](/api/conversations/messages-and-runs#subscribing-read-the-current-conversation). Keep its outcome unresolved when the latest state cannot identify it. Merge the returned history into the existing view rather than appending another copy of every message. Compare stable message identities and numeric 64-bit sequences; keep sequence strings intact in transport. ## Step 2: Resolve the turn or leave it visibly pending \{#completion-and-recovery} Poll with a finite deadline and a delay between reads. Respect any `Retry-After` response. When your wait expires, offer another state refresh without repeating the original message. A lost connection does not prove that generation or a remote tool stopped. If the result contains pending client tools, follow the [client-tool loop](/managed-agents/delegation-approvals/using-tools#client-side-tools). If a subscription reconnects with missing events, refresh authoritative state; receiving the next live event does not fill the gap. Stop reading and clear private local state on sign-out or scope changes. See [interpreting updates](/managed-agents/conversations/streaming/payloads) for the difference between message, activity and run state. **Finished result:** reopening the chat restores its permitted history and the known outcome of the original turn. If that outcome cannot be correlated, the user sees that it is unresolved and can refresh again. No duplicate send is needed to rebuild the view. For a mobile app returning from the background, run the same state read before trusting the previous spinner or showing a retry. On sign-out, stop reading and clear the private display even if remote work may continue. ## Upcoming recipe: resume a mobile chat from retained events \{#resumable-subscriptions} **Status:** Upcoming — not yet available. Restore a mobile chat after a lost connection without losing updates or repeating the user's message. The subscription connects an authorized snapshot to subsequent events and distinguishes a recoverable interruption from a gap beyond retained history. 1. Authenticate and select the authorized conversation. Its identifier alone does not grant access. 2. Load the snapshot with its replay boundary and subscribe from that boundary. 3. Retain the accepted run identity and merge events by stable identity, including duplicates and out-of-order arrivals. 4. Reconnect in the same scope with the transport's resume cursor, using a finite deadline and backoff. 5. If the cursor has expired, show the gap and reload permitted state without resending the original message. 6. Clear private local state on sign-out or scope change, and reauthenticate before resuming. For example, returning to a chat after a brief disconnect restores the same conversation from its saved cursor. After a longer interruption beyond retention, the client explains the gap and reloads history. Background suspension, cancellation and a lost connection remain distinct from confirmation that a remote action stopped. The cursor fields and subscription requests are not yet available. The polling recipe above remains the current recovery path; a plain snapshot followed by a live subscription does not guarantee continuity. **Finished result:** the client restores the same conversation from retained events, or explains an expired replay gap and reloads permitted history. It never resends the user's message just because the cursor expired. --- URL: https://docs.travila.ai/managed-agents/conversations/client-context # Explain the setting the customer is looking at \{#give-the-assistant-context-about-the-current-screen} Add a “help with this setting” conversation to your application. When a user asks from the notification settings page, send a small description of that screen with the question, then show the reply and refresh the context if the user moves elsewhere. The result is a screen-aware help exchange. Client context is descriptive data; it does not authenticate the user, authorize a settings change or prove the assistant used every value. ## Before you start \{#before-you-start} Create a thread and configure [authentication](/core-platform/identity-access/authentication). Use only context your application is entitled to send. Avoid credentials, full URLs containing tokens, and unnecessary personal data. Choose the few facts the help answer needs: a short page identifier, device type and locale are sufficient for the example. Read them from the current application view at send time; do not reuse an old page description after navigation. ## Step 1: Send the current settings page with the question \{#send-the-current-context} Use this body with [`send-message`](/api/conversations/send-message). Replace the conversation key with your created thread: See [Send a message to a conversation](/api/conversations/send-message#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `conversationKey`: text \. * `userMessage.role`: text ROLE\_USER. * `userMessage.content[0].type`: text CONTENT\_PART\_TYPE\_TEXT. * `userMessage.content[0].content`: text Help me understand this setting.. * `userMessage.clientContext.values.page`: text /settings/notifications. * `userMessage.clientContext.values.device`: text web. * `userMessage.clientContext.values.locale`: text en-US. Request example: [Send a message to a conversation](/api/conversations/send-message) · [Request fields](/api/conversations/send-message#request). Keep this map small and relevant to the current screen. Check [the reference limits](/api/models/schema-1i2sndrl93#overview) before adding more context. Retain the accepted run ID. The sample describes `/settings/notifications`; the map is not a snapshot of every setting or permission, so keep checks for actual changes in your application. ## Step 2: Show the answer and handle a stale-screen reply \{#handle-the-result} Follow the returned run using the [generation guide](/managed-agents/conversations/generation). If the connection drops, refresh that run's state before resending. If the answer refers to an old screen, send a new message with the current context and a clear correction. Do not assume that client context reduces cost or latency. See [profile prompt variables](/managed-agents/profiles-prompts/prompt-fragments) for reusable template inputs and [API conventions](/api) for JSON presence rules. **Finished result:** the user can ask about the visible screen and receive a correlated answer. If the answer addresses an earlier screen, correct the context in a new user message after reconciling the previous run. Do not silently execute a proposed settings change from descriptive context. ## Step 3: Refresh context when the user changes screens \{#understand-when-it-applies} For a follow-up from a different screen, rebuild the map from that screen and attach it to the new message. This is the recommended path; appending a context-only message is [not a persistent setting for future sends](/api/conversations/context-and-compaction#client-context-understand-when-it-applies). Treat context as descriptive data, not an instruction that grants permissions. Check the assistant's proposed action against the actual current page and the user's permissions; its answer does not confirm that every context value was used. --- URL: https://docs.travila.ai/managed-agents/conversations/attachments # Summarize a customer’s uploaded report \{#attach-a-stored-file-to-a-conversation} Build a report-summary flow in which the customer uploads a file, asks for a summary and sees either a completed answer or a clear file/generation failure. Require the report for this recipe so a missing file cannot silently become an answer based only on the prompt. Before starting, create the customer's thread, configure user-scoped authentication and select a model/provider supporting the file type. You need permission to store the file and disclose its content to that provider. A file ID identifies a stored file; it does not grant access to another user's data. ## Step 1: Upload the report and keep its registered ID \{#upload-and-register-first} Follow the [file upload guide](/core-platform/files-data/files): request an upload URL, upload with the returned headers, then register the file. Keep the returned [`fileId`](/api/storage/generate-upload-url#response-field-fileid). Issuing an upload URL alone does not make a file available to the conversation. Keep the returned file ID with this upload in your application. If upload or registration fails, resolve that step before offering “summarize”; do not present an issued upload URL as a completed attachment. ## Step 2: Require the report for this answer \{#decide-whether-the-file-is-required} Use [the fail-generation mode](/api/conversations/messages-and-runs#attachments-decide-whether-the-file-is-required) already included in the request below. An answer to “summarize the attached report” would be misleading without the report. Choose content skipping only for another workflow where the omitted attachment is truly optional. A successful URL resolution does not prove that the provider fetched or understood the file. Check run status, provider errors and the returned answer. MIME metadata is not content validation, and model citations are not proof of correct interpretation. ## Step 3: Ask for the summary in the same conversation \{#send-the-file-reference} Use this body with [`send-message`](/api/conversations/send-message), authenticated for the user entitled to read the file: See [Send a message to a conversation](/api/conversations/send-message#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `conversationKey`: text \. * `userMessage.role`: text ROLE\_USER. * `userMessage.content[0].type`: text CONTENT\_PART\_TYPE\_TEXT. * `userMessage.content[0].content`: text Summarize the attached report.. * `userMessage.content[1].type`: text CONTENT\_PART\_TYPE\_FILE\_ID. * `userMessage.content[1].content`: text \. * `overrideGenerationConfig.fileResolution.failureMode`: text FILE\_RESOLUTION\_FAILURE\_MODE\_FAIL\_GENERATION. Request example: [Send a message to a conversation](/api/conversations/send-message) · [Request fields](/api/conversations/send-message#request). The platform resolves the file to a signed provider-fetchable URL. Treat signed URLs as credentials and avoid copying them into chat text, logs or shared links. A URL can expire while a provider is fetching it; a stable ID does not promise that the underlying file exists forever. Retain the returned run ID and follow [generation outcomes](/managed-agents/conversations/generation). Read the answer only for that run. **Finished result:** the customer receives the report summary with its actual completion status, or sees why the report could not be used. Review content accuracy; successful URL resolution is not proof that the provider understood the file. ## Recover the upload or the accepted summary request \{#recover-from-failures} For a missing file, verify registration and the selected user/project. For unsupported content, select a supported provider or transform the file through a separately authorized flow. Reconcile an accepted run before sending the original message again. See [generation outcomes](/managed-agents/conversations/generation) and [storage management](/core-platform/files-data/managing). If the response is lost after send acceptance, keep the existing file and run references while reconciling. Uploading another copy or sending the question again is not a status lookup. If later questions need a file that expired, use the supported storage flow to make an authorized file available before a new request. --- URL: https://docs.travila.ai/managed-agents/conversations/build-chat-assistant # Build a signed-in support chat that survives reconnects \{#build-an-ai-chat-assistant} Build a chat assistant that a signed-in user can ask a question, return to for the reply, and use with files and notifications. Start with one complete turn through the native REST API, then add the optional steps as your app needs them. Use the account and application credential pair provisioned for your deployment. The [authentication guide](/core-platform/identity-access/authentication) explains backend and client credentials. Start with text chat only: sign in, create a thread, send one question and reopen its reply. Verify that complete path before adding attachment upload or push notifications. The optional sections extend the same conversation; they are not prerequisites for the first working chat. ## Prerequisites \{#prerequisites} * A **publishable key** (`pk_…`) configured for client use with the required user authentication and intended permissions. Before distributing the app, qualify the allowed operations and restrict key-management access: the key's class alone does not establish a complete management-access boundary. See the current [Publishable Key Restrictions](/api/authentication#publishable-key-restrictions). * An identity provider configured for the publishable key. This walkthrough uses Firebase as an optional example; other configured identity providers can be used instead. * For the optional push step, a device or simulator with a supported push token. ## Step 1: Sign in the customer and authenticate requests \{#step-1-set-up-authentication} Client apps send **two credentials on every request**: | Header | Value | Identifies | | --------------- | ----------------------------- | ---------------------- | | `X-API-Key` | your publishable key (`pk_…`) | your app / tenant | | `Authorization` | `Bearer ` | the signed-in end user | The Firebase ID token carries user identity — the platform derives `userId`, memory scope, and per-user data from it. You do **not** put a user ID in request bodies. ### Sign in the user \{#sign-in-the-user} For the optional Firebase sign-in flow, use Firebase Authentication configured for your tenant. Sign in the end user, obtain their ID token from the Firebase SDK, and use the [list-threads credential check](/api/conversations/list-threads#request) to verify the credentials before building the chat flow. ### Verify credentials with your first call \{#verify-credentials-with-your-first-call} Confirm your key and token work together by listing threads — [an empty list is the expected response on a fresh account](/api/conversations/list-threads#overview): [Response example: List conversation threads](/api/conversations/list-threads#example-cookbook-managed-agents-conversations-build-chat-assistant-json-01-response). Example identifiers and values are illustrative; substitute authorized values. ## Step 2: Start one support conversation \{#step-2-create-a-thread} A thread is a conversation container with its own message history. Create one before sending messages — you only need to do this once per conversation. [Request example: Create a new conversation thread](/api/conversations/create-thread#example-cookbook-managed-agents-conversations-build-chat-assistant-02-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: pk_your_publishable_key`; `Authorization: Bearer `; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** [Response example: Create a new conversation thread](/api/conversations/create-thread#example-cookbook-managed-agents-conversations-build-chat-assistant-json-02-response). Example identifiers and values are illustrative; substitute authorized values. Save the [`threadId`](/api/models/schema-1i84dsgmg6#response-field-threadid) — you'll pass it as [`conversationKey`](/api/conversations/send-message#request-field-conversationkey) in every subsequent request on this conversation. ## Step 3: Send the question and wait for its own reply \{#step-3-send-a-message-and-poll-for-the-reply} Sending a message is asynchronous: retain the returned [`runId`](/api/conversations/send-message#response-field-runid) and follow [the bounded polling and correlation recipe](/managed-agents/conversations/generation#polling-recipe). Model/tool latency varies. A queued response and an idle conversation do not establish this request's success. ### Send the message \{#send-the-message} [Request example: Send a message to a conversation](/api/conversations/send-message#example-cookbook-managed-agents-conversations-build-chat-assistant-03-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: pk_your_publishable_key`; `Authorization: Bearer `; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. Do not retry a send after a lost response until you have reconciled it. A repeated send can create duplicate work; see [API retries](/api#idempotent-requests). **Response:** [Response example: Send a message to a conversation](/api/conversations/send-message#example-cookbook-managed-agents-conversations-build-chat-assistant-json-03-response). Example identifiers and values are illustrative; substitute authorized values. ### Poll conversation state \{#poll-conversation-state} Poll within a bounded deadline and correlate the result with the accepted run, following the [generation guide](/managed-agents/conversations/generation). Stop on a recognized terminal outcome for that run. An idle conversation alone does not prove that your request completed: [Request example: Get full conversation state](/api/conversations/get-conversation-state#example-cookbook-managed-agents-conversations-build-chat-assistant-04-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: pk_your_publishable_key`; `Authorization: Bearer `; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response (generation still running):** [Response example: Get full conversation state](/api/conversations/get-conversation-state#example-cookbook-managed-agents-conversations-build-chat-assistant-json-04-response). Example identifiers and values are illustrative; substitute authorized values. **Response (this run completed — matching [`generatedBy`](/api/models/schema-1j3dcf7kvu#response-field-generatedby) and terminal status):** [Response example: Get full conversation state](/api/conversations/get-conversation-state#example-cookbook-managed-agents-conversations-build-chat-assistant-json-05-response). Example identifiers and values are illustrative; substitute authorized values. See [Async Generation](/managed-agents/conversations/generation#async-generation) for the full polling recipe and backoff guidance. Streaming and polling availability are deployment-specific; reconnect and outcome correlation still apply with push updates — see [Stream conversation activity](/managed-agents/conversations/streaming). ## Step 4: Restore the chat display from stored history \{#step-4-render-the-conversation} Render [`messageHistory`](/api/conversations/get-conversation-state#response-field-messagehistory) by stable identity and numeric [`sequence`](/api/models/schema-1j3dcf7kvu#response-field-sequence). Use [`activeRunning`](/api/conversations/get-conversation-state#response-field-activerunning) for activity only; [keep a separate pending/unknown state](/api/conversations/messages-and-runs#build-chat-assistant-step-4-render-the-conversation) for the operation you submitted. An absent activity flag means no run is currently active; it does not identify the outcome of your earlier send. For structured output (a JSON plan, a form, a classification), use [`send-message-sync`](/managed-agents/conversations/generation#synchronous-generation) for a bounded wait and inspect its returned status before consuming a final answer. A queued run, pending client tool or expired wait can return before completion. An `Idempotency-Key` alone does not establish duplicate prevention; follow the [retry and reconciliation guidance](/api#idempotent-requests). Close and reopen your chat view, then read the same conversation ID. Merge the returned messages instead of appending duplicate bubbles. Keep the pending run identity separately while its outcome is unresolved. ## Finish the first text-chat recipe \{#run-it} Use the thread created above to complete this customer journey: 1. Sign in, send one question and keep the returned conversation/run identifiers. 2. Display the stored user message and the assistant reply only when it belongs to that run. 3. Leave the chat view and reopen the same thread. The existing messages appear once, in numeric sequence order. 4. Send a follow-up in that thread after the earlier turn is resolved. **Finished result:** the signed-in user can ask, leave, return and continue without a duplicate conversation or duplicated reply. If the wait ends before the outcome is known, keep the turn unresolved and offer a state read/reconnect. The completed-state example in step 3 shows the result to match. Use the recovery section below for credentials and interrupted work. ## Recover after reconnect, backgrounding or sign-out \{#client-lifecycle-and-recovery} Keep request authentication and token refresh in a shared client layer. Use your identity provider's SDK for refresh; coalesce concurrent refreshes and clear the shared task on both success and failure. Every waiting request must resolve, including failed refreshes. Token expiry decoded locally is a scheduling hint, not signature validation. Retry reads with a bounded deadline and backoff. On `401`, refresh once only when the error indicates an expired renewable session; a disabled key, wrong audience or revoked account needs different recovery. `429` may carry `Retry-After` as seconds or an HTTP date. Honor it within the overall deadline. An uncertain mutation must be reconciled before another send; see [API retry limits](/api#idempotent-requests). Merge history by stable message identity and numeric 64-bit sequence. A snapshot followed by a live subscription is not gap-free without a replay cursor or buffering contract. See [reconnecting to updates](/managed-agents/conversations/streaming/subscribing). Register a changed push token while authenticated, retry registration with a bounded policy and reconcile after reconnect. Unregister the current device on sign-out and clear its local private state; do not delete every persistent schedule. See [push delivery](/core-platform/notifications/push) for device and logout handling. Log request/operation IDs and sanitized errors for diagnosis. Never log API secrets, bearer tokens, signed URLs or private message bodies as routine diagnostics. ## Keep the signed-in session working as tokens expire \{#step-7-handle-token-refresh} [Firebase ID tokens expire after approximately one hour](https://firebase.google.com/docs/auth/admin/manage-sessions). Cache the token and refresh it **before** it expires — do not request a new token on every API call. * Parse `exp` from the token payload and treat the token as expired approximately **5 minutes early** to absorb clock skew and in-flight requests. * When within that buffer, force a refresh (`getIDToken(forcingRefresh: true)`) and coalesce concurrent refreshes so a burst of requests triggers **one** refresh, not many. Keep a shared in-flight refresh task so concurrent callers can await the same result. Refresh once when the error identifies an expired renewable user token; a revoked key or wrong issuer/audience needs different recovery. Retry only when the original request was rejected before execution or the endpoint explicitly documents safe repetition. Reconcile uncertain mutations before another send. Clear the shared refresh task on success and failure so waiting callers receive the result. ### Choose recovery from the actual authentication error \{#handling-error-responses} | Status | What it means | What to do | | ------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **401** | Authentication rejected | Inspect the reason. Refresh once for an expired renewable user token; do not refresh-loop on a revoked key or wrong issuer/audience. Reconcile uncertain mutations. | | **429** | Request throttled | Honor retry headers with bounded backoff and an overall deadline. Do not automatically repeat an uncertain send. See [Rate Limiting](/api/authentication#rate-limiting). | ## Variant: let the customer ask about a file \{#step-5-upload-a-file-optional} When the customer asks about a report, extend the working text chat with the [attachment recipe](/managed-agents/conversations/attachments): 1. Request a signed upload URL, upload the bytes and register the file through [file storage](/core-platform/files-data/files). 2. Retain the registered [`fileId`](/api/storage/generate-upload-url#response-field-fileid) and add it to a question in the existing thread. 3. Require the file when an answer without it would be misleading, then follow the same run/result checks as text chat. **Finished result:** the customer receives the file-aware answer or a visible upload, file or generation failure. An issued URL or successful registration alone is not that answer. Signed URLs expire, and a stable file ID does not guarantee perpetual retention or access. The older inline small-file upload remains a legacy option; use the signed upload flow for this recipe and larger files. ## Variant: bring the user back when a notification arrives \{#step-6-register-for-push-notifications} Add push only after the text-chat path works. Register the authenticated device, handle a notification as a prompt to reload the relevant application state, and unregister on logout. Device registration is not proof that a future notification was delivered. [Request example: Register a push notification device](/api/notifications/register-push-device#example-cookbook-managed-agents-conversations-build-chat-assistant-05-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: pk_your_publishable_key`; `Authorization: Bearer `; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** [Response example: Register a push notification device](/api/notifications/register-push-device#example-cookbook-managed-agents-conversations-build-chat-assistant-json-06-response). Example identifiers and values are illustrative; substitute authorized values. On logout, unregister the device: [Request example: Unregister a push notification device](/api/notifications/unregister-push-device#example-cookbook-managed-agents-conversations-build-chat-assistant-06-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: pk_your_publishable_key`; `Authorization: Bearer `; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. ### Connect the real-time inbox \{#connect-the-real-time-inbox} For an in-app notification feed, call `get-inbox-session` to get a WebSocket URL and token, then connect for live badge and feed updates. If the socket drops, fall back to polling `get-inbox-unseen-count` every \~30 seconds. See [Build an in-app inbox](/core-platform/notifications/inbox#real-time-inbox-updates) for the full connection recipe. ## Upcoming: application project setup \{#first-project-setup} **Status:** Upcoming — not yet available. Create a support application's project, choose a supported data region and follow setup until the project is ready. Issue the client credentials as a separate action. Reloading setup returns to the same project without creating another project or secret. If setup needs attention, inspect the unfinished step before making the first call. The [first-project setup guide](/managed-agents/conversations/quickstart#first-project-setup) describes that journey. This walkthrough currently starts with your provisioned account and key. Continue using those credentials until the new setup flow is available. --- URL: https://docs.travila.ai/managed-agents/conversations/quickstart # Complete your first support-chat turn \{#send-your-first-agent-message} Complete your first chat turn: create a thread, send a question and read the reply for that accepted run. Use the credentials configured for your deployment and save the conversation identifier so the user can continue the same conversation. Use this recipe from your backend with one test user and one new conversation. The goal is a visible reply for the run you started, not just four successful HTTP calls. Keep the same user and returned thread ID throughout. ## Prerequisites \{#prerequisites} Start with the account and application credentials provisioned for your deployment. Use the [authentication guide](/core-platform/identity-access/authentication) to choose the credential type for your integration. The current public path uses the legacy `default` project; arbitrary project headers do not create or select another project. * A secret key (`sk_*`) carrying the `users:impersonate` scope (created in your Travila dashboard). See the [API Key Integration Guide](/core-platform/identity-access/authentication), or request one from your account admin — ask for that scope explicitly. * A user id to act as. Any stable identifier from your own system works; the examples below use `user_123`. > **Info: Every call needs a user** > > A secret key identifies your tenant, not a person. Most endpoints act on a specific user's data, so each request below passes `X-On-Behalf-Of`. Leave it off and the call fails with `401 authenticated user_id is required` — see [Acting as a user](/api/authentication#acting-as-a-user--x-on-behalf-of). > > Using a publishable key (`pk_*`) instead? Drop `X-On-Behalf-Of` and send `Authorization: Bearer ` — the user comes from the JWT. ## Step 1: Confirm the test user’s credentials \{#step-1-list-threads} Check that your API key works by listing your conversation threads. [Response example: List conversation threads](/api/conversations/list-threads#example-cookbook-managed-agents-conversations-build-chat-assistant-json-01-response). Example identifiers and values are illustrative; substitute authorized values. The [`threads`](/api/conversations/list-threads#response-field-threads) key can be absent instead of `[]`; treat an absent list as empty (see [Body encoding](/developer-experience/local-tooling/development#body-encoding)). On an existing account, a nonempty list is also valid. If authentication fails, correct the credential pair before creating a thread. This read verifies that the intended user scope is usable without starting paid generation. ## Step 2: Start one conversation for that user \{#step-2-create-a-thread} A thread is a conversation container with its own message history and settings. It belongs to the user named in `X-On-Behalf-Of`, and only that user's requests can reach it. [Request example: Create a new conversation thread](/api/conversations/create-thread#example-cookbook-managed-agents-conversations-build-chat-assistant-02-request). 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. **Response:** [Response example: Create a new conversation thread](/api/conversations/create-thread#example-cookbook-managed-agents-conversations-build-chat-assistant-json-02-response). Example identifiers and values are illustrative; substitute authorized values. Use the returned [`threadId`](/api/models/schema-1i84dsgmg6#response-field-threadid) as the [`conversationKey`](/api/conversations/send-message#request-field-conversationkey) value in subsequent requests on this thread. Copy the returned ID into both later requests. The UUID shown in the example is illustrative; using it unchanged does not select the thread you just created. ## Step 3: Ask one question and save the run ID \{#step-3-send-a-message} Send a message and the platform will generate an AI response asynchronously. [Request example: Send a message to a conversation](/api/conversations/send-message#example-cookbook-managed-agents-conversations-build-chat-assistant-03-request). 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. **Response** — retain this accepted generation run's [`runId`](/api/conversations/send-message#response-field-runid): [Response example: Send a message to a conversation](/api/conversations/send-message#example-cookbook-managed-agents-conversations-build-chat-assistant-json-03-response). Example identifiers and values are illustrative; substitute authorized values. > **Info: Responses are async** > > `send-message` returns immediately. The assistant reply is produced in the background; timing depends on the model, tools and load. Retrieve it by polling `conversation-state` — see [Async Generation](/managed-agents/conversations/generation#async-generation) for the full recipe. Send this question once. If the response is lost, follow [retry and reconciliation](/api#idempotent-requests) rather than posting it again to see whether anything happened. Keep the UI pending until the original operation is understood. ## Step 4: Read the reply for that run \{#step-4-check-conversation-state} Retrieve the full conversation state, including messages, settings, and generation status. [Request example: Get full conversation state](/api/conversations/get-conversation-state#example-cookbook-managed-agents-conversations-build-chat-assistant-04-request). 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. **Response** — this successful first-turn example has a matching assistant reply and completed status: [Response example: Get full conversation state](/api/conversations/get-conversation-state#example-cookbook-managed-agents-conversations-build-chat-assistant-json-05-response). Example identifiers and values are illustrative; substitute authorized values. While generation is still in progress, [`activeRunning`](/api/conversations/get-conversation-state#response-field-activerunning) is `true`, [`activeRunId`](/api/conversations/get-conversation-state#response-field-activerunid) equals the [`runId`](/api/conversations/send-message#response-field-runid) from the previous step, and the assistant message has not yet been appended. In this isolated first-turn example, the matching reply appears after completion. In queued or concurrent flows, idle and [`lastRunStatus`](/api/conversations/get-conversation-state#response-field-lastrunstatus) can describe a different run; retain an unknown outcome until you can correlate the request. See [Async Generation](/managed-agents/conversations/generation#async-generation) for the polling recipe. **Finished result:** the state contains the question, an assistant reply whose [`generatedBy`](/api/models/schema-1j3dcf7kvu#response-field-generatedby) matches the retained run, and a correlated completed outcome. A failed result is a completed attempt at this recipe with a visible failure, not an empty successful answer. Read with a delay and an overall deadline. If the deadline arrives first, stop automatic polling and offer another state refresh. Once the turn is resolved, send a follow-up using the same conversation ID to continue. ## Extend the working conversation \{#whats-next} Keep this first working thread as your baseline. Add one capability at a time and repeat the send/result check so a file, tool or profile change has an observable outcome. | I want to... | Go to | | ------------------------------------------------- | -------------------------------------------------------------------------- | | Understand auth methods, scopes, and key rotation | [Authentication & API Keys](/core-platform/identity-access/authentication) | | Learn how conversations and threads work | [Conversations Guide](/managed-agents/conversations) | | Use MCP tools in conversations | [Agent tools guide](/integrations/tools-connections) | | Upload and manage files | [Storage Guide](/core-platform/files-data) | | Browse all API endpoints | [API Reference](/api/conversations) | ## Upcoming recipe: set up the project before issuing credentials \{#first-project-setup} **Status:** Upcoming — not yet available. For a new support application, create the project before issuing its first credentials: 1. Enter the application name and choose a supported data region. 2. Follow the project’s pending, ready or needs-action outcome. Resolve unfinished dependencies before the first call. 3. Once ready, deliberately issue the credentials for the application. 4. On reload, return to the same setup rather than creating another project or secret. **Finished result:** one ready project and separately issued credentials. Project creation, readiness and credential creation are separate actions. The quickstart above currently uses your provisioned account and legacy `default` project. The new project-creation API and setup flow are not yet available. --- URL: https://docs.travila.ai/managed-agents/delegation-approvals/using-tools # Approve a tool action and finish the conversation \{#use-and-approve-tools-in-conversations} Build an assistant that can search for information but waits for a person before sending an email or performing another reviewed action. Use the platform-run approval recipe first: configure the gate, submit a request, show the pending action, send the decision and follow the same run to its result. If your application executes the action itself, use the separate [client-tool recipe](#client-side-tools). Client tools do not pass through the platform approval queue; your application validates arguments, checks permission and obtains the required confirmation before executing them. ## Before you start: choose the tool and its review policy \{#tool-execution-policy} You need an authenticated conversation, a selected server whose tools have been discovered, and the exact names of the tools your assistant can call. Use [tool discovery](/integrations/tools-connections) and inspect the server/tool names before writing approval patterns. The example below uses illustrative search and email patterns; adapt them to your discovered names. For this recipe, allow ordinary lookup calls and [require a decision](/api/tool-execution/policies#using-tools-tool-execution-policy) before the chosen sending action. Keep the same conversation and accepted run when listing and deciding on approvals. ## Step 1: Add the approval gate to the send \{#worked-example} Add this policy to the user’s normal send request after adapting `send_email` to the discovered sending tool. This is the policy portion, not a complete message. It allows a 30-second approval wait and a finite overall run budget. See [Send a message to a conversation](/api/conversations/send-message#request) for the full field contract. This excerpt illustrates the relevant choices; replace identifiers with your own authorized values. * `conversationKey`: text support-chat-001. * `overrideGenerationConfig.toolPolicy.requireApprovalToolNamePatterns[0]`: text send\_email. * `overrideGenerationConfig.toolPolicy.approvalMode`: text APPROVAL\_MODE\_MIXED. * `overrideGenerationConfig.toolPolicy.approvalTimeoutMs`: number 30000. * `overrideGenerationConfig.toolPolicy.timeouts.overallMs`: number 600000. Request excerpt: [Send a message to a conversation](/api/conversations/send-message) · [Request fields](/api/conversations/send-message#request). Send the user’s request once and retain its run ID. If the model does not request the gated action, no approval appears; read the actual reply rather than manufacturing a pending decision. Use the [send reference](/api/conversations/send-message) for the complete [`toolPolicy`](/api/models/schema-1h82h7ri5p#request-field-toolpolicy) schema. ## Step 2: Show the action awaiting a decision \{#checking-pending-approvals} Read the pending calls for the conversation and present the action that needs a decision. Keep its tool-call ID so the decision applies to that call. [Request example: List pending tool approvals](/api/conversations/list-pending-approvals#example-cookbook-managed-agents-delegation-approvals-using-tools-01-request). 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. Present the pending action for review before asking for a decision. Keep its [`toolCallId`](/api/models/schema-1i4kndhs46#request-field-toolcallid) tied to that action; do not reuse a decision for an unrelated later call. An empty pending list means there is no current approval to submit, not that the run completed. ## Step 3: Submit the decision and inspect the outcome \{#submitting-approvals} After the user decides, submit the decision for the pending [`toolCallId`](/api/models/schema-1i4kndhs46#request-field-toolcallid). The example approves the call. Continue following the run afterward: an approval decision is not confirmation that the tool or the full task succeeded. [Request example: Approve or reject pending tool calls](/api/conversations/submit-tool-approvals#example-cookbook-managed-agents-delegation-approvals-using-tools-02-request). 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. Continue reading the same run through [generation outcomes](/managed-agents/conversations/generation). Approval authorizes execution of the held call; it does not confirm that execution succeeded. Show a rejected, failed, timed-out or still-unknown tool result accurately. **Finished result:** the person reviewed the pending action, the decision referred to that call ID, and the conversation shows its actual result and correlated run outcome. If the decision response is lost, read the pending/call state before deciding again; do not resend the original user message to recover. ## Variant: decide which calls wait together \{#approval-patterns} Keep `APPROVAL_MODE_MIXED` when [independent auto-approved lookups may proceed](/api/models/schema-1h2ji21uc4#overview) while the sending action waits. Choose `APPROVAL_MODE_BLOCK_ALL` when the entire batch must wait for every gated decision. ## Current limit: tool-policy retries are not applied \{#retries} [Tool-policy retry settings](/api/models/schema-1h2ji21uc4#overview) are accepted and stored, but current execution does not apply their patterns, error filters or backoff. Setting them does not cause a failed lookup to retry. Inspect the failed call and show its actual outcome. Initiate another lookup only when it can safely be repeated. Reconcile an uncertain external write before any new attempt; a stored retry policy does not establish that repetition is safe. ## Variant: bound the assistant’s supporting lookups \{#parallel-calls-and-budgets} Set [a finite lookup budget](/api/models/schema-1h2ji21uc4#overview) for the task. Allow parallel calls only when those lookups are independent. Inspect whether the reply contains the needed evidence. Show partial work as partial; reaching a budget limit does not establish that every requested lookup completed. ## Recover when the run or review deadline expires \{#run-time-budget} Choose [a finite duration](/api/models/schema-1gu5od417l#overview) for the task and show a timeout or unfinished result honestly. Inspect any external action separately before retrying it. Approval and client-tool deadlines bound those individual waits; they are separate from the overall run budget and from a provider spending limit. ## Current limit: stop-on-failure rules are not enforced \{#stop-on-failure-rules} Configured [stop-on-failure rules](/api/models/schema-1gstrgb39r#overview) are stored but do not currently stop a run after a tool error. Do not depend on this setting to prevent later model or tool steps. If a later application action depends on the failed action succeeding, check the original outcome in your application before allowing that action. Inspect the tool and run outcomes separately; neither a failure nor a stopped run undoes an external effect that already occurred. ## Client tools executed by your application \{#client-side-tools} For a tool that opens a page or performs another application action, follow [the client-tool recipe](/managed-agents/delegation-approvals/build-agent-with-tools). This page focuses on approval policy; approving a call and executing it in your app are separate actions. ### Set the client answer window \{#client-tools} Choose a finite answer window long enough to validate and perform the requested action. Retain the returned deadline and use it during recovery; after expiry, inspect the terminal outcome instead of submitting a late success. Approval does not prove the application action ran. ### Client-tool flow \{#the-loop} [Synchronous client tool handoff](/diagrams/1qk1t3b6hm) shows the handoff. The [tool recipe](/managed-agents/delegation-approvals/build-agent-with-tools#step-2-send-a-message-and-receive-the-call) carries the full request and result examples. ### Receive the pending call \{#turn-1--the-model-asks} Retain the pending call’s ID, name, arguments and deadline. Follow [receiving a complete call](/managed-agents/delegation-approvals/build-agent-with-tools#step-2-send-a-message-and-receive-the-call) before executing anything. ### Validate and return the outcome \{#turn-2--you-answer} Validate untrusted arguments and authorize the requested action in your application. Return the result for the same pending call only after inspecting what happened; see [executing and answering the call](/managed-agents/delegation-approvals/build-agent-with-tools#step-3-return-the-result-and-get-the-reply). ### Recover the original call \{#if-the-connection-drops} Recover the pending call and inspect its status before sending another result or repeating the business action. Follow [client-tool recovery](/managed-agents/delegation-approvals/build-agent-with-tools#if-you-cant-hold-a-connection). Do not resend the original user message to recover a lost response. ## Client tools from a worker \{#client-side-tools-async} A worker can use the asynchronous send path and recover pending calls without keeping the send request open. Follow [the worker and recovery path](/managed-agents/delegation-approvals/build-agent-with-tools#if-you-cant-hold-a-connection) and [Asynchronous client tool handoff](/diagrams/1qmo5rvpk0). ### Discover a pending call \{#knowing-a-call-is-waiting} Use the enabled event-delivery surface or poll for pending client tools, then read the call before acting. A notification alone is not an authorization decision or proof that execution is still permitted. The [recovery recipe](/managed-agents/delegation-approvals/build-agent-with-tools#if-you-cant-hold-a-connection) explains the same-call checks. ### Choose synchronous or asynchronous handoff \{#which-style-to-use} Keep the request open when the caller can wait for the model’s handoff. Use asynchronous send and recovery for a worker that cannot hold that connection. Both paths must reconcile the original call and its deadline before acting. ### Inspect terminal outcomes \{#two-rules-for-clients} A reply that asks for a client tool is an intermediate handoff. After returning the result, inspect the continuing run and its terminal outcome. A failed, cancelled or timed-out call is not a successful application action. --- URL: https://docs.travila.ai/api/tool-execution/policies # Tool policy resolution and lifecycle \{#overview} The effective generation configuration selects the tool policy. Read [approval and call limits](/api/models/schema-1h2ji21uc4), [run timeouts](/api/models/schema-1gu5od417l) and [current stop-rule limitations](/api/models/schema-1gstrgb39r) on their models; this page explains precedence and how clients observe the resulting work. ## Tool execution policy \{#using-tools-tool-execution-policy} [`toolPolicy`](/api/models/schema-1h82h7ri5p#request-field-toolpolicy) (a `ToolExecutionPolicy` object) on `GenerationConfig` configures approval, waiting and supported tool-call limits during a generation run. Retry, ordering, per-loop cap and stop-on-failure settings are accepted and stored but are not currently enforced; see the [tool policy model](/api/models/schema-1h2ji21uc4#overview) for the boundary of each control. Because it lives on the generation config, the same field works as a per-request override, on an agent profile, or as the conversation default — resolved most-specific-first, see [Which policy applies](/api/tool-execution/policies#policy-precedence). [`ConversationSettings.toolPolicy`](/api/models/schema-ph6avse89k#request-field-toolpolicy) is the deprecated predecessor. It still works as the final fallback, but it is thread-only and cannot be set on a profile or an override. ## Observing client-tool waits \{#using-tools-knowing-a-call-is-waiting} When your integration observes the [declared tool-call-started lifecycle](/api/events/u22bdqd1kd), inspect the embedded [ToolCall](/api/models/schema-1it6mqsqoo#response). It can represent begun execution or a wait for human approval. Use [`isClientTool`](/api/models/schema-1it6mqsqoo#response-field-isclienttool) to identify client execution, match the tool name against [the client tools you declared](/api/models/schema-1h82h7ri5p#request-field-clienttools), and enforce [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat) when submitting a client result. For approval waits, inspect [`status`](/api/models/schema-1it6mqsqoo#response-field-status) and [`requiresApprovalAt`](/api/models/schema-1it6mqsqoo#response-field-requiresapprovalat) and reconcile pending approvals before dispatching an action. This deadline is not the time the call started waiting. No separate approval-required Event is declared by the selected catalog. Poll the pending-client-tools operation to reconcile work on reconnect or when no event observation is available. Choose an interval within your [client tool timeout](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms); zero or omission selects the five-minute default answer window. A ten-minute polling interval can miss that entire wait. A result submitted after its deadline is rejected. Read the deadline and pending state before retrying. ## Run status and model finish reason \{#using-tools-two-rules-for-clients} * **Treat unknown [`status`](/api/conversations/send-message-sync#response-field-status) values as an unknown outcome.** `COMPLETED`, `FAILED`, `CANCELLED` and `TIMED_OUT`, with the `AGENT_STATUS_` prefix, are recognized terminal run outcomes. Run status has no `SUCCESS` alias; that legacy alias belongs only to tool execution status. An unknown value means the outcome is not understood; reconcile it rather than declaring success, failure or indefinite activity. * **Read [`finishReason`](/api/models/schema-1j3dcf7kvu#response-field-finishreason) on the assistant message** if you want to know why the model stopped. It is an open string that preserves provider values; examples include `stop`, `tool_calls`, `length`, `content_filter` and `error`, and historical messages can leave it empty. Preserve unfamiliar values instead of treating this illustrative list as a closed enum. It answers a different question from [`status`](/api/conversations/send-message-sync#response-field-status) — [`status`](/api/conversations/send-message-sync#response-field-status) is what the run is doing, [`finishReason`](/api/models/schema-1j3dcf7kvu#response-field-finishreason) is why the model stopped talking. ## Policy precedence \{#policy-precedence} Put new rules on the generation configuration that owns the task. A per-turn [`overrideGenerationConfig.toolPolicy`](/api/models/schema-1h82h7ri5p#request-field-toolpolicy) takes precedence, followed by the active profile's policy, the conversation's [`defaultGenerationConfig.toolPolicy`](/api/models/schema-1h82h7ri5p#request-field-toolpolicy), and finally the deprecated [`conversationSettings.toolPolicy`](/api/models/schema-ph6avse89k#request-field-toolpolicy) fallback. An explicitly empty policy selects no rules and stops that fallback. When testing a sensitive action, inspect the effective configuration for the actual agent and turn; a rule saved on the thread does not prove that a more specific policy requires approval. --- URL: https://docs.travila.ai/managed-agents/memory-knowledge # Use remembered preferences in a returning user’s conversation \{#remember-users-across-conversations} Help a returning user continue with relevant preferences or context from earlier conversations. When memory is enabled, search for the records relevant to the new question, review their freshness and correct outdated information. Treat remembered statements as fallible records, since they can be stale or inaccurate. **Access limitation:** complete ownership checks for by-ID reads and changes are not yet established for every deployment. Use isolated test data for those operations until your operator confirms they are safe for your intended users. Travila must enforce that boundary; an ID or memory setting cannot supply the missing protection. **Recipe:** let a returning user review the preferences available to the assistant, correct an outdated record and continue the conversation with relevant context. Start with controlled records in one authorized user scope. This recipe cannot remove the by-ID access limitation above; use those operations only in an operator-qualified deployment or isolated test data. You need the user's authenticated scope, enabled memory service and permission for the retrieval/extraction you select. Keep correction and deletion controls visible to the user instead of treating memory as unquestionable truth. ## Choose a small recall-and-review flow \{#get-started} Use a small recall-and-review flow: | Step | Your application does | The user can check | | -------- | ------------------------------------------------------------ | ---------------------------------------------------- | | Recall | Search for preferences relevant to the question. | The returned statements and their freshness. | | Review | Offer correction or removal where by-ID access is qualified. | Whether each remembered statement is still accurate. | | Continue | Retrieve context only for the permitted audience. | A reply grounded in relevant, reviewed context. | | Extract | Obtain permission for later memory extraction. | What the application will remember next. | An empty search can mean no matches or a handled search-provider failure; it does not establish that no memories exist. It is not a reason to invent a preference. A relevant result is still a fallible statement, and a high relevance score is not proof that it is true. ## Before the first lookup: select the authenticated user \{#user-impersonation} Derive the intended user from your authenticated application session. For the search request below, use a backend API key with `users:impersonate` and set `X-On-Behalf-Of` to that user. Keep the same authorized scope through the recipe. A changed header or memory ID is not permission to access someone else’s records. This header does not remove the by-ID limitation stated above. ## Step 1: Find the preferences relevant to the question \{#searching-memories} For a meal-planning follow-up, search for dietary preferences. Show the retrieved statements with their available timestamps so the user can recognize stale or incorrect information. Choose [a bounded number of relevant matches](/api/conversations/search-memories#overview) for the review screen, then inspect the [returned memory records](/api/models/schema-1k63a85bkp) and their freshness. Search dietary preferences. [Request example: Semantic search over memories](/api/conversations/search-memories#example-memory-search-request). 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. **Response:** Illustrative dietary preferences returned. [Response example: Semantic search over memories](/api/conversations/search-memories#example-memory-search-response). Example identifiers and values are illustrative; substitute authorized values. | Result | What to do next | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | Relevant records | Show the statements and timestamps; let the user correct stale information. | | Empty result | Continue with user-supplied context. Do not conclude that no memories exist: a handled provider failure can also return an empty result. | | Request error | Tell the user recall is unavailable and continue only with context they supply. | ## Step 2: Let the user review the stored records \{#listing-memories} A search returns relevant matches, not an inventory. For a review screen, list records in the authenticated user’s scope and let the user inspect the returned statements. Explain that [this capped list may not be the complete memory inventory](/api/conversations/list-memories#overview) before offering a review or deletion workflow. [Request example: List user memories](/api/conversations/list-memories#example-cookbook-managed-agents-memory-knowledge-index-02-request). 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. ### Inspect the selected record before changing it \{#getting-a-specific-memory} Use the selected record ID only where by-ID ownership checks are qualified. Read the record the user wants to correct, confirm that it is the intended statement, then use the update or deletion step. On an unqualified deployment, keep this to isolated records and use the operator's supported correction route for real users. [Request example: Get a specific memory](/api/conversations/get-memory#example-cookbook-managed-agents-memory-knowledge-index-03-request). 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. ## Step 3: Correct an outdated preference \{#updating-a-memory} After the user confirms the replacement wording, update that record. The example adds a preference to the existing statement; it is a user-declared record, not medical advice or a verified diagnosis. [Request example: Update a memory](/api/conversations/update-memory#example-cookbook-managed-agents-memory-knowledge-index-04-request). 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. Read the record back in the qualified scope to confirm the stored text. If the write response is lost, inspect the existing record before repeating it; keep the correction unresolved until its outcome is known. ## Alternative: remove a statement the user no longer wants \{#deleting-memories} Use single-record deletion for a selected memory. Treat account erasure as a separate request: deleting one match or one list page cannot establish that every retained or derived copy is gone. ### Remove the selected record \{#delete-a-single-memory} [Request example: Delete a memory](/api/conversations/delete-memory#example-cookbook-managed-agents-memory-knowledge-index-05-request). 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. Keep the selected record and request context until its outcome is known. Do not report account erasure from this operation; the bulk-removal limitation below still applies. ### Deleting every memory at once \{#deleting-every-memory-at-once} There is no public bulk-delete endpoint. Deleting the IDs returned by one search or list does not confirm account erasure: other memories or pending extraction can remain. For an account-erasure request, contact your account administrator or support using the [privacy request guidance](/core-platform/governance-privacy). Ask for the scope and completion status; Travila is responsible for coordinating its retained and derived copies. ## Step 4: Include relevant memory in later replies \{#configure-memory} After the recall-and-review flow works for the authorized scope, apply [the memory settings](/api/models/schema-1g8iadjcu1#overview) with `update-default-generation-config` for the selected conversation, then send a representative question through [generation](/managed-agents/conversations/generation). Enable this only when retrieval and asynchronous extraction are permitted for the data and audience. [Request example: Update default generation config](/api/conversations/update-default-generation-config#example-cookbook-managed-agents-memory-knowledge-index-json-02-request). Example identifiers and values are illustrative; substitute authorized values. **Finished result:** the user can inspect and correct the allowed records, and the selected conversation has a correlated reply using the configured retrieval path. Review the reply rather than assuming every returned memory influenced it. Generation success does not confirm that later extraction completed. ## Understand missing or delayed memories after a reply \{#how-memory-flows-through-a-turn} When a preference is missing or delayed, first review the records returned by the lookup. Follow the original conversation to its outcome before checking whether new memories have appeared. Keep the user’s correction separate from confirmation that background extraction completed. [Retrieval and extraction lifecycle](/api/memory/lifecycle#how-memory-flows-through-a-turn). ### Variant: share only within an approved audience \{#cross-conversation-memory-sharing} [`agentIdOverride`](/api/models/schema-1g8iadjcu1#request-field-agentidoverride) selects a memory namespace within an authorized scope. It must not grant access to another user or project. Share only within an audience the user has authorized, and confirm the deployment supports that audience before enabling it. Changing this setting cannot grant access to another user's memories. ### Current limit: the exposure flag does not add a tool \{#explicit-memory-search-tool} Use the search endpoint from your application for a controlled lookup. [Confirm an actual discovered tool exists](/api/models/schema-1g8iadjcu1#overview) before asking the model to use it. ## Variant: show when a remembered statement was recorded \{#memory-timestamp-injection} Keep timestamps enabled for this meal-preference recipe so the assistant receives when a statement was remembered and, when applicable, updated. Show the available record dates on the user’s review screen too. The date explains the record’s age; it does not certify the preference is still true. If a different flow does not need timestamps in the model context, set `injectMemoryTimestamps: false` in the [`mem0`](/api/models/schema-1h82h7ri5p#request-field-mem0) block on the thread default or per-turn override. This changes the injected annotation, not the stored fact or its truth. ## Choose automatic retrieval or application-controlled search \{#memory-and-conversations} Keep application-controlled `search-memories` when the user must review records before the reply. Use automatic retrieval with [`mem0.enabled`](/api/models/schema-1g8iadjcu1#request-field-enabled) once the audience and retrieval/extraction permissions are established. If using discovered MCP memory tools, inspect what is actually enabled through [tool discovery](/integrations/tools-connections); setting [`exposeAsMcpTool`](/api/models/schema-1g8iadjcu1#request-field-exposeasmcptool) does not add one. No choice here removes the by-ID isolation gap. ## Upcoming recipe: move permitted memories to a local provider \{#memory-providers} **Status:** Upcoming — not yet available. For a coaching application moving recall to supported local infrastructure, first identify the permitted records, their audience and the target provider. Retrieval of existing records and extraction of new ones have separate permissions. 1. Inspect the records, corrections and deletion state included in the move. 2. Run the migration to the supported provider. 3. Review whether migration, export and any cleanup completed before using the target for recall. 4. Continue the user’s recall-and-correction flow on the selected provider. **Finished result:** migrated records preserve permitted provenance, ownership, audience and correction history; erased facts stay erased. Inspection, export and erasure show incomplete work and cleanup outcomes. Portable providers and these controls are not yet available through the current configuration block. The by-ID access and deletion limitations above still apply. ## Upcoming recipe: answer a follow-up that needs earlier context \{#model-directed-memory-search} **Status:** Upcoming — not yet available. For a returning user asking “What else have I tried?”, give the agent a finite memory-search budget within that user’s permitted audience. 1. Retrieve records relevant to the follow-up. 2. Inspect whether the evidence is complete, partial, empty or unavailable. 3. Answer from the available evidence or explain what is missing. Do not repeatedly search or broaden the audience to force an answer. **Finished result:** the user receives an evidence-based follow-up or an explicit missing-evidence outcome within the search budget. The same consent and spending limits apply as for automatic retrieval. The current [`exposeAsMcpTool`](/api/models/schema-1g8iadjcu1#request-field-exposeasmcptool) setting has no effect. This retrieval tool and its activation path are not yet available; use the search endpoint or automatic retrieval for current integrations. ## Related \{#related} * [Conversations Guide](/managed-agents/conversations) — How memories integrate with conversations * [Agent tools guide](/integrations/tools-connections) — Memory as MCP tools * [LLM API Reference](/api/conversations) — Full endpoint reference --- URL: https://docs.travila.ai/api/memory/lifecycle # Memory retrieval and extraction \{#overview} Memory retrieval prepares a generation with stored context. Extraction updates memory after the run and has a separate completion and failure lifecycle. [Memory configuration](/api/models/schema-1g8iadjcu1) defines the supported controls and ignored legacy flags. ## Retrieval and extraction lifecycle \{#how-memory-flows-through-a-turn} Use this sequence when the user asks why a just-mentioned preference has not appeared yet or why a later reply uses an earlier record. Separate retrieval, model generation and asynchronous extraction when explaining the outcome. Memory integration runs in three phases around generation: 1. **Before generation** — the platform searches the user's memory store using the last user message (or [`searchQueryOverride`](/api/models/schema-1g8iadjcu1#request-field-searchqueryoverride)) and retrieves the top [`searchTopK`](/api/models/schema-1g8iadjcu1#request-field-searchtopk) results above [`searchThreshold`](/api/models/schema-1g8iadjcu1#request-field-searchthreshold). 2. **Attached to the latest user message** — the current path inserts retrieved memories as a context block in the latest user message, despite the legacy [`injectAsSystemContext`](/api/models/schema-1g8iadjcu1#request-field-injectassystemcontext) name. Relationship output is available only where supported by the deployment; [`enableGraph`](/api/models/schema-1g8iadjcu1#request-field-enablegraph) alone does not ensure it will be returned. A memory block can look like: Memory output illustration. * \[Relevant memories about this user:] * User is vegetarian and avoids gluten (remembered: Feb 15, 2025 at 10:00 AM UTC) * User prefers meals under 500 calories (remembered: Feb 20, 2025 at 2:30 PM UTC, updated: Mar 1, 2025 at 9:00 AM UTC) * \[Known relationships about this user:] * User → prefers → plant-based diet These dietary preferences, dates and relationships are a historical fictional output illustration, not observed facts about a person or a live response. 3. **After generation** — the run's messages are passed to the extraction pipeline, which derives new facts and updates existing ones. The current extraction path is asynchronous. Its completion or success is not implied by a successful generation, and configured extraction still needs the appropriate data and spending permission. [Memory retrieval and extraction lifecycle](/diagrams/1qq2a9383f) The platform retrieves relevant memories before generation and starts asynchronous extraction from run messages after returning the reply. ```mermaid sequenceDiagram accTitle: Memory retrieval and extraction lifecycle accDescr: The platform retrieves relevant memories before generation and starts asynchronous extraction from run messages after returning the reply. participant C as Client participant P as Platform participant M as Memory store C->>P: send-message (user turn) P->>M: search memories (query = last user message) M-->>P: top-K memories above threshold Note over P: attach memory context to latest user message P->>P: generation with injected memories P-->>C: assistant reply P-)M: async extraction (new facts from run messages) ``` --- URL: https://docs.travila.ai/managed-agents/model-controls # Choose models for a document or image assistant \{#control-which-models-serve-a-request} Choose a permitted model for the material the customer provides, then follow the request to a usable answer or an explicit selection failure. Start with named candidates whose availability your account supports; add a filter for the capability the task requires. For an image question, require image input. For a long research thread, require a suitable context window and separately manage the actual history size. Price filters narrow known per-token catalog prices; they are not a total spending budget. ## Recipe: answer with a model suited to the input \{#start-here} Before starting, have an authenticated thread, the customer input and permitted model candidates for your account and data-handling requirements. 1. Check the candidates against [the accepted model rules](#allowed-models) and your provider/account availability. 2. Choose the [image or long-context filter](/managed-agents/model-controls/filtering) that matches the actual request. Keep every required constraint when using a per-send filter. 3. Send one representative request and retain its run ID. If no model is eligible, [correct the selection error](/managed-agents/model-controls/errors) before another send. 4. Follow the accepted run to its outcome and inspect the answer. A metadata match does not prove the provider honored the requested capability. 5. Compare actual usage and result quality before using the same setup for more traffic. **Finished result:** the application follows the selected candidates to a correlated answer or a selection/generation failure. Check that the answer meets the task's requirements, and do not infer zero cost from missing usage. Use [the worked recipes](/managed-agents/model-controls/examples) for a long research thread, a price-filtered summary or a structured task summary. ## Step 1: select candidates accepted for the account \{#allowed-models} Use the [model catalog](/available-models) to compare capabilities, then obtain an exact permitted model ID for your account and deployment. Catalog presence is not permission to select a model. **Undecided** means no platform selection decision is recorded for that entry. Confirm eligibility with your deployment operator before configuring it. Follow [model selection and routing limits](/api/model-controls/routing#allowed-models) and verify the chosen model with a permitted request. ## Follow the candidates through validation and fallback \{#how-it-works} Choose candidates that meet the customer’s input, capability and data-handling needs. Use the reference to investigate [a rejected candidate or unexpected fallback](/api/model-controls/routing#how-it-works). If a fallback answers, inspect the actual returned model and outcome rather than assuming the first candidate served the request. An initial send failure and a later generation failure need different recovery; retain the response you actually received. ## Upcoming recipe: summarize a document without hosted inference \{#local-model-serving} **Status:** Upcoming — not yet available. Use this path when the document must remain on supported local infrastructure. 1. Select a locally supported model with the required capability, capacity and suitable model-weight licence. 2. Configure the local deployment and keep hosted fallback disabled for this workflow. 3. Submit the authorized document and follow generation and structured-output validation when applicable. 4. Inspect the result and accounting. If local capacity is unavailable, keep the outcome unavailable instead of sending the document to another provider. **Finished result:** a locally processed document response or an explicit unavailable outcome, with no silent hosted fallback. Model selection, generation, validation and accounting stay on the selected local path. Local serving and its setup/compatibility instructions are not yet available. Passing today's allowlist does not establish local runtime compatibility. Use the current request patterns above for the interface available now. ## Related \{#related} * [Provider routing](/managed-agents/model-controls/provider-pinning) — Keep a model on the providers you choose * [Conversations](/managed-agents/conversations) — Thread lifecycle and generation config * [Configuration](/managed-agents/conversations/configuration) — The full generation config * [LLM API Reference](/api/conversations) — Full endpoint reference --- URL: https://docs.travila.ai/managed-agents/model-controls/errors # Recover when no model can serve the request \{#handle-routing-errors} For a customer image or summary request rejected before generation, keep the input, identify the failed selection step and correct the configuration. Use this recipe for an explicit rejection; a lost send response or an already accepted run requires [generation recovery](/managed-agents/conversations/generation) instead. The public send path checks explicit model IDs against [the allowlist](/managed-agents/model-controls#allowed-models) first. **Any disallowed ID in [`model`](/api/models/schema-1h82h7ri5p#request-field-model) or [`models`](/api/models/schema-1h82h7ri5p#request-field-models) rejects the whole request**, even when another supplied candidate is allowed. It is not silently removed. After that check, conversation preparation resolves candidate metadata and applies the routing filter. A successful metadata lookup that leaves no candidates produces a different rejection. Neither rejection starts a new generation run for that request; show the error rather than waiting for its reply. ## Step 1: identify a rejected request that never started \{#error-payload} For example, suppose the candidate IDs are `anthropic/claude-sonnet-5` and `anthropic/claude-sonnet-4.6`, and the resolved metadata for both falls below the context window your task requires. Both IDs pass the current allowlist. The following illustrates the resulting RPC error; it does not assert either model’s current catalog availability or context size: Model filtering terminal error. This example is an excerpt. Use the linked operation or model for its full format; error bodies can differ by operation and failure type. * `code`: text ERROR\_CODE\_INVALID\_ARGUMENT. * `message`: text all candidate models were filtered out: \[anthropic/claude-sonnet-5 anthropic/claude-sonnet-4.6]. * `isTerminal`: boolean true. * `details.errorInfo.reason`: text MODEL\_FILTERED\_OUT. * `details.errorInfo.domain`: text conversation. The two rejections do not share a payload shape. The example above is the metadata/filter rejection, which carries a structured reason. **The allowlist rejection is a `403` that carries its reason in the message text instead:** Model allowlist denial. This example is an excerpt. Use the linked operation or model for its full format; error bodies can differ by operation and failure type. * `code`: number 403. * `message`: text \[403] policy denied (suspension\_state=NONE): model\_access/MODEL\_NOT\_ALLOWED: model "openai/gpt-5" is not allowed. Match on the `MODEL_NOT_ALLOWED` token and the disallowed ID quoted after it. The `for action \"...\"` clause is present only on endpoints that name one, so do not rely on it. On the send path a request that is refused this way never starts a generation run. Keep the returned error and candidate/filter configuration. [This aggregate metadata error](/api/model-controls/routing#errors-error-payload) does not provide a per-candidate explanation of catalog absence versus filter mismatch. Inspect the available metadata and requirements before changing the request. Allowlist acceptance alone is not proof that a model is available or suitable. ## Step 2: correct the selection, then send the original task \{#handling-the-response} 1. Confirm you received an explicit pre-generation rejection, rather than losing a response or observing a later run failure. 2. For `MODEL_NOT_ALLOWED`, correct or remove every disallowed model explicitly supplied by the request. Choose replacements from the accepted set that can serve the task. 3. For `MODEL_FILTERED_OUT`, inspect catalog resolution and the requested constraints. Select other permitted candidates, or relax a filter only if the task’s capability, cost and data-handling requirements still hold. 4. Send the corrected task once and follow the newly accepted run to its outcome. | Outcome | What to do | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `403`, reason `MODEL_NOT_ALLOWED` | Fix the explicit disallowed ID. An allowed fallback does not bypass this check. | | `400`, reason `MODEL_FILTERED_OUT` | Correct the candidate/filter combination after inspecting resolved metadata. No new generation run started for this rejection. | | Accepted response with a [`runId`](/api/conversations/send-message#response-field-runid) | Retain the ID and follow [generation outcomes](/managed-agents/conversations/generation). Acceptance is not a completed reply. | Once the gateway allowlist check passes, metadata resolution can omit individual candidates and continue with eligible survivors. That behavior does **not** apply to an explicitly disallowed ID, and an unavailable metadata check does not prove every constraint was checked. **Finished result:** the customer’s input is retained while the configuration is corrected, then the new request is followed to its actual reply, failure or unresolved outcome. No duplicate send is used as a status lookup. --- URL: https://docs.travila.ai/managed-agents/model-controls/filtering # Route an image question to a capable model \{#filter-candidate-models} Let a customer ask what is in an uploaded image and require image-capable candidates for that request. Use a per-send filter for this occasional attachment; keep a thread default for workloads that always have the same requirement. The recipe finishes with a correlated answer from the accepted run or a clear selection failure. Catalog metadata filters candidate models; it does not validate the image or guarantee correct interpretation. ## Before you start \{#get-started} Use an existing authenticated conversation, permitted image content and named model candidates available to your account. Replace `research-001` and `` with the actual thread and input. Wait for any unresolved turn to settle. The current queue path does not retain [`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig), so an override-dependent image request must not be queued behind an active run. If the thread already has a routing filter, copy every constraint this image request must keep into the per-send filter. That filter replaces the whole base filter; adding image support alone does not preserve a prior context or price constraint. ## Choose the filter’s lifetime \{#where-to-set-the-filter} The per-send recipe below serves one image request. Use [the persistent research-thread variant](#1-thread-level-default) when every turn has the same requirement. A per-send filter replaces the entire base filter, so include every constraint the current request must keep. ## Step 1: send the image with its required capability \{#2-per-message-override} Set via [`send-message`](/api/conversations/send-message) in [`overrideGenerationConfig.modelRoutingFilter`](/api/models/schema-1h82h7ri5p#request-field-modelroutingfilter). Applies to a single message only. [Request example: Send a message to a conversation](/api/conversations/send-message#example-cookbook-managed-agents-model-controls-filtering-01-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: $API_KEY`; `Authorization: Bearer $JWT`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. > **Note: The override merges — it does not replace** > > [`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig) is merged field-by-field onto the config the thread would otherwise use. Send only what you want to change; everything you leave out is inherited. > > The granularity is the **top-level** config field. A field you do set replaces the base value wholesale rather than merging into it, so a partial [`modelRoutingFilter`](/api/models/schema-1h82h7ri5p#request-field-modelroutingfilter) in an override replaces the thread's filter entirely — it does not combine with it. > > Two details worth knowing: > > * **Explicit zeros count.** Scalars are presence-aware, so `"temperature": 0` overrides the base rather than reading as "unset". > > * **Empty lists do not.** Repeated and map fields have no presence, so an empty list is indistinguishable from an absent one and inherits instead. `clearTools: true` clears inherited static [`tools`](/api/models/schema-1h82h7ri5p#request-field-tools) only when the override's own [`tools`](/api/models/schema-1h82h7ri5p#request-field-tools) list is empty; a non-empty list replaces the inherited list. It never clears [`clientTools`](/api/models/schema-1h82h7ri5p#request-field-clienttools). When MCP discovery returns a result, it replaces [`tools`](/api/models/schema-1h82h7ri5p#request-field-tools) after the merge, including when discovery returns no tools. Discovery normally runs even with no configured servers; it is skipped for a profile that disables default tools and has no nonblank server references. The flag therefore does not disable MCP discovery or guarantee a turn without tool calls. Retain the returned run ID. If all candidates are rejected, show [the routing error](/managed-agents/model-controls/errors); do not quietly drop the image requirement to obtain an answer. ## Step 2: inspect the accepted run and its answer \{#how-filters-combine} Follow [generation](/managed-agents/conversations/generation) to a correlated outcome, then inspect the image answer and actual returned model. [Use these rules](/api/model-controls/routing#filtering-how-filters-combine) to diagnose why a candidate or constraint was selected. **Finished result:** the request either has a completed image answer for its accepted run or a visible failure. If the user asks a later text-only question, omit this per-send override to use the thread's default configuration again. ## Variant: keep a capability requirement for a long research thread \{#1-thread-level-default} Set via [`create-thread`](/api/conversations/create-thread) in [`defaultGenerationConfig.modelRoutingFilter`](/api/models/schema-1h82h7ri5p#request-field-modelroutingfilter). Applies to every message in the thread. [Request example: Create a new conversation thread](/api/conversations/create-thread#example-cookbook-managed-agents-model-controls-filtering-02-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: $API_KEY`; `Authorization: Bearer $JWT`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. Keep the returned thread ID and send the research material to that thread. Inspect the first run and later context size; requiring a 128k catalog window does not make an arbitrarily long history fit. Use [compaction](/managed-agents/conversations/context-management) when the material grows. ## Choose the additional constraints the task needs \{#modelroutingfilter-fields} Add a constraint only when it serves the customer task, then repeat the request and inspect its outcome. For a longer answer, require the needed output capacity. For a tool-using structured answer, require the supported parameters. [Multiple constraints are ANDed](/api/models/schema-1ga4tjqqg1#overview); every specified requirement must pass. For price constraints, use the variant below and track actual usage separately. ## Variant: narrow catalog prices while tracking actual cost \{#price-filters-are-not-spending-budgets} Use [catalog-price filters](/api/models/schema-1ga4tjqqg1#overview) to narrow candidates, then track the task’s actual usage. Set separately enforced spending limits before increasing paid traffic. --- URL: https://docs.travila.ai/managed-agents/model-controls/provider-pinning # Keep a model on the providers you choose \{#pin-providers} Some models are served by more than one provider. Left alone, a request for such a model may be served by a different provider from one time to the next. Name the providers you want when that consistency matters more than availability. This page shows a preference, a restriction, where each can be set, and one limit to know before relying on either. ## Before you start \{#before-you-start} You need a model that more than one provider serves and the provider identifiers for the ones you want. A base identifier such as `together` matches every variant that provider offers for the model; an identifier with a suffix such as `baseten/fp8` names one variant. The examples use `deepseek/deepseek-v4.1-flash` with `together` and `baseten/fp8`. Replace `support-001` with your conversation's ID. ## Prefer providers \{#prefer-providers} Set [`provider.order`](/api/models/schema-1gg690bhqh#request-field-order) to try providers in the order you list them. This is a preference, not a guarantee: fallback stays on, so when none of the listed providers can serve the request it is routed to another provider that can. Use it when you want a usual provider but would rather get an answer than a failure. Set the preference for one message in the body of [`send-message`](/api/conversations/send-message): Request example: [Send a message to a conversation](/api/conversations/send-message) · [Request fields](/api/conversations/send-message#request). See [Send a message to a conversation](/api/conversations/send-message#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `conversationKey`: text support-001. * `userMessage.role`: text ROLE\_USER. * `userMessage.content[0].type`: text CONTENT\_PART\_TYPE\_TEXT. * `userMessage.content[0].content`: text Summarize the last three messages from this customer.. * `overrideGenerationConfig.model`: text deepseek/deepseek-v4.1-flash. * `overrideGenerationConfig.provider.order[0]`: text together. * `overrideGenerationConfig.provider.order[1]`: text baseten/fp8. ## Restrict providers \{#restrict-providers} Set [`provider.only`](/api/models/schema-1gg690bhqh#request-field-only) to allow only the providers you list. The request is routed with that restriction, so no other provider is eligible. If none of them can serve it, expect the run to end in a failure you can inspect, not an answer from elsewhere. [`only`](/api/models/schema-1gg690bhqh#request-field-only) and [`order`](/api/models/schema-1gg690bhqh#request-field-order) can be combined: [`only`](/api/models/schema-1gg690bhqh#request-field-only) sets who is eligible, [`order`](/api/models/schema-1gg690bhqh#request-field-order) sets who is tried first among them. Set the restriction for one message in the body of [`send-message`](/api/conversations/send-message): Request example: [Send a message to a conversation](/api/conversations/send-message) · [Request fields](/api/conversations/send-message#request). See [Send a message to a conversation](/api/conversations/send-message#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `conversationKey`: text support-001. * `userMessage.role`: text ROLE\_USER. * `userMessage.content[0].type`: text CONTENT\_PART\_TYPE\_TEXT. * `userMessage.content[0].content`: text Summarize the last three messages from this customer.. * `overrideGenerationConfig.model`: text deepseek/deepseek-v4.1-flash. * `overrideGenerationConfig.provider.only[0]`: text together. * `overrideGenerationConfig.provider.only[1]`: text baseten/fp8. ## Choose where to set it \{#where-to-set-it} The same [`provider`](/api/models/schema-1h82h7ri5p#request-field-provider) object can be set in three places: * **One message:** [`overrideGenerationConfig.provider`](/api/models/schema-1h82h7ri5p#request-field-provider) on [`send-message`](/api/conversations/send-message). Applies to that message only. * **Every message in a thread:** [`defaultGenerationConfig.provider`](/api/models/schema-1h82h7ri5p#request-field-provider) on [`create-thread`](/api/conversations/create-thread). * **Every thread that uses an agent profile:** [`profile.generationConfig.provider`](/api/models/schema-1h82h7ri5p#request-field-provider) on [`create-agent-profile`](/api/agent-profiles/create-agent-profile) or [`update-agent-profile`](/api/agent-profiles/update-agent-profile). A per-message [`provider`](/api/models/schema-1h82h7ri5p#request-field-provider) is applied over the configuration the thread would otherwise use: the active agent profile's if the thread has one, otherwise the thread default. It replaces the whole inherited [`provider`](/api/models/schema-1h82h7ri5p#request-field-provider) object; it does not merge into it. Repeat any [`only`](/api/models/schema-1gg690bhqh#request-field-only) list you still need. Set a restriction as a thread default: Request example: [Create a new conversation thread](/api/conversations/create-thread) · [Request fields](/api/conversations/create-thread#request). See [Create a new conversation thread](/api/conversations/create-thread#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `title`: text Support thread. * `defaultGenerationConfig.model`: text deepseek/deepseek-v4.1-flash. * `defaultGenerationConfig.provider.only[0]`: text together. * `defaultGenerationConfig.provider.only[1]`: text baseten/fp8. Set a preference in an agent profile: Request example: [Create an agent profile](/api/agent-profiles/create-agent-profile) · [Request fields](/api/agent-profiles/create-agent-profile#request). See [Create an agent profile](/api/agent-profiles/create-agent-profile#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `profile.profileId`: text support\_assistant. * `profile.name`: text Support Assistant. * `profile.description`: text Order and account questions.. * `profile.whenToUse`: text Use when the user asks about an order or their account.. * `profile.enabled`: boolean true. * `profile.generationConfig.model`: text deepseek/deepseek-v4.1-flash. * `profile.generationConfig.systemPrompt`: text You are a support assistant. Be concise and practical.. * `profile.generationConfig.provider.order[0]`: text together. * `profile.generationConfig.provider.order[1]`: text baseten/fp8. ## Know the fallback limit \{#fallback-limit} Setting [`allowFallbacks`](/api/models/schema-1gg690bhqh#request-field-allowfallbacks) to `false` does not turn fallback off today; the request is still sent with fallback allowed. To keep a request inside a set of providers, use [`provider.only`](/api/models/schema-1gg690bhqh#request-field-only). The API does not currently return which provider served a request. ## Related \{#related} * [ProviderPreferences](/api/models/schema-1gg690bhqh#overview) — Provider routing fields * [GenerationConfig](/api/models/schema-1h82h7ri5p#overview) — The configuration that carries them * [Route an image question to a capable model](/managed-agents/model-controls/filtering) — Filter candidate models * [Recover when no model can serve the request](/managed-agents/model-controls/errors) — Correct a rejected selection --- URL: https://docs.travila.ai/managed-agents/model-controls/structured-output # Turn a task description into a validated summary object \{#request-a-structured-answer} Create a summary your application can place in a task card without parsing prose for field names. Send the task description with an object schema, wait for the run outcome and validate the exact answer your application will use. Start with one `summary` string and a bounded synchronous wait. Add fields only when the application needs them. Schema validation checks shape and types; it does not establish factual correctness, units, provenance or permission to act. ## Before you start \{#before-you-start} Use a model and provider route that supports the requested structured format. The native conversation API accepts the configuration below. See [model selection](/managed-agents/model-controls) and [generation](/managed-agents/conversations/generation). Create a thread, keep its ID and use the normal user-scoped credentials. Wait for any prior turn to resolve: per-send overrides are not retained for queued messages. The example uses a controlled task description; replace it with content the user is entitled to send. ## Step 1: send the task with its object schema \{#configure-an-object-response} Use this body with [`send-message-sync`](/api/conversations/send-message-sync) and the thread ID you created. It requests [a bounded wait](/api/conversations/send-message-sync#overview); inspect the returned status before consuming the object: See [Send a message and wait for the result](/api/conversations/send-message-sync#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `conversationKey`: text \. * `userMessage.role`: text ROLE\_USER. * `userMessage.content[0].type`: text CONTENT\_PART\_TYPE\_TEXT. * `userMessage.content[0].content`: text Summarize this task: Prepare the support onboarding guide and have it reviewed.. * `overrideGenerationConfig.responseFormat.schemaName`: text summary. * `overrideGenerationConfig.responseFormat.jsonSchema.type`: text object. * `overrideGenerationConfig.responseFormat.jsonSchema.properties.summary.type`: text string. * `overrideGenerationConfig.responseFormat.jsonSchema.required[0]`: text summary. * `overrideGenerationConfig.responseFormat.jsonSchema.additionalProperties`: boolean false. * `overrideGenerationConfig.responseFormat.validate`: boolean true. * `overrideGenerationConfig.responseFormat.maxValidationRetries`: number 1. Request example: [Send a message and wait for the result](/api/conversations/send-message-sync) · [Request fields](/api/conversations/send-message-sync#request). For a recurring task-card flow, move the same [`responseFormat`](/api/models/schema-1h82h7ri5p#request-field-responseformat) into its conversation default or profile after testing it. Keep the schema used by the application with the request; the schema name alone does not identify an immutable version. ## Step 2: populate the task card only from a completed valid answer \{#read-and-validate-the-result} If the bounded response is still active, queued or waiting for a tool, retain its run ID and use [generation recovery](/managed-agents/conversations/generation). Once it completes, [parse the answer and validate it](/api/models/schema-1ho1lk4ndj#overview) against the exact schema above. A refusal, truncated response, invalid JSON, missing required field or provider error is not a typed success. Handle it explicitly instead of substituting an empty object. A [`healed`](/api/models/schema-1ho1lk4ndj#response-field-healed) value of false or its absence is not reliable evidence about whether provider repair occurred. **Finished result:** the card receives one validated `summary` string whose content you checked against the source task. For refusal, truncation, invalid output or failure, show the failure or unresolved state and leave the card unfilled; do not substitute an empty object and continue. ## Variant: show provisional text while waiting for validation \{#treat-streaming-separately} Streamed fragments can reach your client before validation finishes, and a validation retry can replace the attempted answer. Keep that text provisional and do not execute actions from it. Wait for a completed result, parse it and validate it before using it; a visible fragment is not a validated answer. Confirm that the selected model supports the requested output format. Application-level validation remains necessary even when a model supports a strict schema. See [model errors](/managed-agents/model-controls/errors) for failure handling. ## Upcoming recipe: use the same validated-summary flow through a compatible client \{#compatible-structured-output} **Status:** Upcoming — not yet available. Use a supported OpenAI-compatible interface when your application already uses that protocol. 1. Supply the task and a supported object schema through the compatible request. 2. Choose validation before display for a task card that cannot consume partial data. 3. Wait for the distinct validated, refused, incomplete or failed outcome. 4. Populate the card only from the validated object. A failed provisional stream remains incomplete rather than becoming a replacement successful answer. **Finished result:** a validated task summary or an explicit unsuccessful outcome, without an empty summary standing in for success. Compatible interfaces, supported schemas and client versions are not yet available. The native configuration and current streaming limitations above still apply; changing an SDK base URL does not make native endpoints OpenAI-compatible. See [native and compatible streams](/managed-agents/conversations/streaming#native-and-compatible-streams). --- URL: https://docs.travila.ai/managed-agents/model-controls/reasoning # Add an optional reasoning panel to a chat reply \{#show-reasoning-alongside-replies} If you are building a chat interface, you can show a model's returned reasoning text in a separate, optional panel beside its answer. Your app should still work when the model returns only an answer. Reasoning text can help a reader understand the response, but it is not a complete record of the model's internal reasoning or proof that the answer is correct. Use the small order-total question below to build the display: the answer belongs in the chat bubble and any returned reasoning belongs in a separate collapsed panel. You need an authenticated thread, a supporting model and the normal send/result loop. The panel is optional; the application must finish a reply when no reasoning is returned. ## Step 1: request the answer and optional reasoning \{#request-reasoning} Start with a conversation configured to use [a model that supports reasoning controls](/api/models/schema-1gi26i7r89#overview). In a [send-message request](/api/conversations/send-message), use [`overrideGenerationConfig.reasoning`](/api/models/schema-1h82h7ri5p#request-field-reasoning) to request reasoning for that turn. This example asks for medium effort and allows reasoning text in the response: See [Send a message to a conversation](/api/conversations/send-message#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `conversationKey`: text your\_conversation\_id. * `userMessage.role`: text ROLE\_USER. * `userMessage.content[0].type`: text CONTENT\_PART\_TYPE\_TEXT. * `userMessage.content[0].content`: text Two items cost $15 each and shipping is $5. What is the total?. * `overrideGenerationConfig.reasoning.effort`: text EFFORT\_MEDIUM. * `overrideGenerationConfig.reasoning.exclude`: boolean false. Request example: [Send a message to a conversation](/api/conversations/send-message) · [Request fields](/api/conversations/send-message#request). Replace `your_conversation_id` with your conversation's ID. See [send and receive a reply](/managed-agents/conversations/generation#worked-example) for authentication, the HTTP request and retrieving the result. Wait for the current turn to settle before sending this example: per-turn overrides are not retained for queued messages. ## Step 2: render by content type, not array position \{#display-answer-and-reasoning} An assistant message can contain both reasoning and answer text. For example, this message excerpt includes both kinds of content: See [Message](/api/models/schema-1j3dcf7kvu#response) for the full field contract. This excerpt illustrates the relevant choices; replace identifiers with your own authorized values. * `content[0].type`: text CONTENT\_PART\_TYPE\_REASONING. * `content[0].content`: text I will add the price of both items, then include shipping.. * `content[1].type`: text CONTENT\_PART\_TYPE\_TEXT. * `content[1].content`: text The total is $35.. Message excerpt: [Message fields](/api/models/schema-1j3dcf7kvu#response). For a text chat, display `CONTENT_PART_TYPE_TEXT` parts as the assistant's reply. Put nonempty `CONTENT_PART_TYPE_REASONING` parts in a separate panel labeled **Reasoning**, collapsed by default. If there are several parts of the same type, retain their order. If no reasoning text is returned, omit the panel and show the reply normally. Use each part's [`type`](/api/models/schema-1hqi9r2bhh#response-field-type) rather than assuming the first part is the answer. Display its [`content`](/api/models/schema-1hqi9r2bhh#response-field-content) as text, or with your app's safe Markdown renderer; [`metadata`](/api/models/schema-1hqi9r2bhh#response-field-metadata) is not display copy. Other content types, such as images, need their own renderer. Check the display with both outcomes: reasoning plus answer, and answer only. For the controlled question above, the stated prices total $35; compare the answer with that known result rather than treating the presence of reasoning as evidence of correctness. ## Step 3: finish the turn and continue with a follow-up \{#continue-conversation} Receiving reasoning text does not mean the reply is complete. Keep the [`runId`](/api/conversations/send-message#response-field-runid) returned by `send-message` and follow the [polling recipe](/managed-agents/conversations/generation#polling-recipe) before marking that turn finished. This guide describes reading conversation state; see [streaming availability](/managed-agents/conversations/streaming) before building a live token display. For a follow-up such as “What if I buy three?”, send a new [`userMessage`](/api/conversations/send-message#request-field-usermessage) with the same [`conversationKey`](/api/conversations/send-message#request-field-conversationkey). Travila builds the model's context from the stored conversation and its configured history settings. Your app does not need to reconstruct provider messages or copy the reasoning panel into the next user message. See [conversation context](/managed-agents/conversations/context-management) for controlling which history is included. **Finished result:** the chat shows the completed answer normally, offers the reasoning panel only when nonempty reasoning was returned, and sends the follow-up in the same thread. An interrupted or failed run remains visibly unresolved or unsuccessful even if reasoning text already arrived. --- URL: https://docs.travila.ai/api/model-controls/configuration # Configuration precedence and plugins \{#overview} Generation configuration can come from a profile, conversation defaults and a per-send override. This reference defines their precedence and the plugin configuration passed into generation. ## System prompt \{#configuration-system-prompt} Set [`defaultGenerationConfig.systemPrompt`](/api/models/schema-1h82h7ri5p#request-field-systemprompt) through `update-default-generation-config`, or supply it in the per-turn generation override. `update-default-generation-config` replaces the complete stored configuration, so read and retain the existing model, limits and other defaults before adding the prompt. A per-send override has different merge behavior. `settings.systemPrompt` is not a recognized field and is ignored. The selected profile and per-turn overrides can replace the thread’s prompt; see [configuration precedence](/api/model-controls/configuration#configuration-how-settings-combine). ## Generation configuration precedence \{#configuration-how-settings-combine} The platform resolves a final `GenerationConfig` for each generation call by merging three layers: [Generation configuration precedence](/diagrams/1qs69e3kcq) Profile or thread defaults form the base; populated per-send fields override that base, and a platform default model fills an unset model. ```mermaid flowchart TD accTitle: Generation configuration precedence accDescr: Profile or thread defaults form the base; populated per-send fields override that base, and a platform default model fills an unset model. A["Profile config\n(if active — its rendered systemPrompt wins)"] --> M B["Thread defaultGenerationConfig\n(fallback when no profile)"] --> M M["Merge base"] --> C["Per-send overrideGenerationConfig\n(merges field-by-field — any populated field replaces)"] C --> D["Platform default model\n(fallback if nothing sets model)"] ``` **Resolution rules:** * **systemPrompt**: per-send override wins > active profile > thread default. The active profile's prompt is first rendered with the current prompt variables. * **Memory config**: if the active profile omits [`mem0`](/api/models/schema-1h82h7ri5p#request-field-mem0) config entirely, the thread default's [`mem0`](/api/models/schema-1h82h7ri5p#request-field-mem0) config is inherited (special case — other fields are not inherited this way). * **Model**: if nothing in the chain sets a model, the platform substitutes its own default. * **Per-send fields**: [`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig) merges **field-by-field** — set a field to override it for that send; omit it to keep the base value. * **MCP servers**: follow the three-tier replacement rule described in [MCP server selection](/api/tools/selection#configuration-mcp-server-selection), not field-by-field merging. ## Plugins \{#configuration-plugins} [`plugins`](/api/models/schema-1h82h7ri5p#request-field-plugins) is a list of `PluginConfig` objects that activate pre/post-processing behaviour. Two built-in plugins: **PDF parsing** — attach a [`pdf`](/api/models/schema-1g5jvg1icc#request-field-pdf) block to configure the extraction engine: See [GenerationConfigInput](/api/models/schema-1h82h7ri5p#request) for the full field contract. This excerpt illustrates the relevant choices; replace identifiers with your own authorized values. * `plugins[0].id`: text file-parser. * `plugins[0].pdf.engine`: text mistral-ocr. Configuration excerpt: [GenerationConfig fields](/api/models/schema-1h82h7ri5p#request). Engines: `pdf-text` (default, text extraction), `mistral-ocr` (OCR via Mistral), `native` (provider-native parsing). **Web search** — attach a [`web`](/api/models/schema-1g5jvg1icc#request-field-web) block: See [GenerationConfigInput](/api/models/schema-1h82h7ri5p#request) for the full field contract. This excerpt illustrates the relevant choices; replace identifiers with your own authorized values. * `plugins[0].id`: text web-search. * `plugins[0].web.engine`: text native. * `plugins[0].web.maxResults`: number 5. * `plugins[0].web.searchPrompt`: text Find recent news about.... * `plugins[0].web.webSearchOptions.searchContextSize`: text medium. Configuration excerpt: [GenerationConfig fields](/api/models/schema-1h82h7ri5p#request). [`searchContextSize`](/api/models/schema-1g1r4lmi7m#request-field-searchcontextsize) accepts `low`, `medium`, or `high`. --- URL: https://docs.travila.ai/api/model-controls/routing # Model routing and selection \{#overview} Explicit model IDs must pass platform validation. Metadata filters narrow eligible candidates, while provider availability and run outcomes determine whether generation succeeds. ## Model selection failures \{#errors-error-payload} **First, distinguish an ID rejected by policy.** If the send explicitly names `invalid/model-xyz`, the gateway refuses it with HTTP `403` and a message carrying `model_access/MODEL_NOT_ALLOWED` and the disallowed ID. Both `send-message` and `send-message-sync` perform this check before dispatching to the conversation. Correct every disallowed ID in the supplied primary/fallback list; adding an allowed fallback does not rescue the request. **Then distinguish a metadata-filter rejection.** An allowed ID can still be absent from the resolved catalog or fail the required capability/price filter. When resolution succeeds but returns no eligible candidates, conversation preparation reports `MODEL_FILTERED_OUT`. > **Note: A later generation failure needs different recovery** > > If metadata resolution itself fails, preparation can continue without that validation and leave checking to the provider path. A later selection failure can use `ERROR_CODE_MODEL_INVALID` with reason `ALL_MODELS_FILTERED` and per-model reasons in its message. Follow the accepted run’s outcome; do not treat this as the earlier gateway rejection. ## Filter precedence \{#filtering-how-filters-combine} | Situation | Behaviour | | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No [`modelRoutingFilter`](/api/models/schema-1h82h7ri5p#request-field-modelroutingfilter) set | No metadata filtering. Model-ID validation still runs. | | Filter set, all fields zero/unset | No filtering — the same as not setting one | | Filter on [`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig) | Applies to that message only; the next message reverts to the thread default | | A single [`model`](/api/models/schema-1h82h7ri5p#request-field-model), no [`models`](/api/models/schema-1h82h7ri5p#request-field-models) array | The filter applies to that one model. If it fails, you get an immediate error. | | [`model`](/api/models/schema-1h82h7ri5p#request-field-model) plus [`models`](/api/models/schema-1h82h7ri5p#request-field-models) | The filter applies to the merged candidate list — [`model`](/api/models/schema-1h82h7ri5p#request-field-model) first, then [`models`](/api/models/schema-1h82h7ri5p#request-field-models) | ## Allowed models \{#allowed-models} Choose an exact model ID permitted for your account and deployment. Use the [model catalog](/available-models) to compare capabilities, but confirm eligibility before selecting an entry; catalog presence and provider support do not establish permission. A request that names a disallowed model can fail with `MODEL_NOT_ALLOWED`. Confirm the selected ID, provider restrictions and required capabilities before retrying. The catalog’s **Undecided** status means a platform selection decision has not been recorded. ## Candidate resolution and fallback \{#how-it-works} You can give the platform several candidate models instead of one, and constrain which of them may be used. Explicit model IDs are validated before generation starts. When candidate metadata is available, capability and price filters narrow that list during preparation. A metadata lookup failure can leave those checks to the later generation path; an accepted request is not proof that every constraint was checked. Set [`models`](/api/models/schema-1h82h7ri5p#request-field-models) for a fallback chain, and [`modelRoutingFilter`](/api/models/schema-1h82h7ri5p#request-field-modelroutingfilter) to require capabilities — a minimum context window, image input or a per-token price filter. Candidates that fail are dropped; generation proceeds with whatever survives. If a successful metadata lookup leaves no eligible candidates, the request is rejected before generation. Follow an accepted run to its outcome for failures discovered later. Setting no filter is a valid choice and changes nothing about how a thread behaves. [Model candidate routing](/diagrams/1qu1c53eo4) Eligible candidates proceed to generation. Failed attempts try remaining candidates; exhaustion ends in an error. An empty eligible set also produces an error. ```mermaid flowchart LR accTitle: Model candidate routing accDescr: Eligible candidates proceed to generation. Failed attempts try remaining candidates; exhaustion ends in an error. An empty eligible set also produces an error. A["Request\n(models list + filter)"] --> B["Filter candidates\n(capabilities, cost)"] B --> C{"Any survivors?"} C -- "yes" --> D["Generation\n(selected candidate)"] D --> E{"Success?"} E -- "yes" --> F["Response"] E -- "no" --> I{"Candidate remaining?"} I -- "yes" --> G["Next candidate\n(fallback chain)"] G --> D I -- "no" --> J["Generation failed\nRead returned error"] C -- "no" --> H["No eligible model\nRead returned error"] ``` ## Available models \{#configuration-available-models} The [model catalog](/available-models) compares reported provider capabilities. It is not the deployment’s allowed-model list. Obtain the permitted exact IDs from your account or deployment operator before applying the [selection rules](#allowed-models). An **Undecided** catalog entry has no recorded platform selection decision. --- URL: https://docs.travila.ai/managed-agents/model-controls/examples # Build a research, bulk-summary or structured-summary flow \{#model-routing-recipes} Choose a model filter for the task, then inspect the accepted run and its result. Replace sample model IDs with models supported for your account, and use a thread ID returned by `create-thread`. See [authentication](/core-platform/identity-access/authentication) for the credential pair. These are three separate recipes. Choose one for the workload instead of applying every filter to every request. Each begins with controlled input and finishes by checking the accepted run and the answer your application will consume. ## Recipe: keep a research conversation on large-context candidates \{#long-context-thread} Use this for a user working through a long set of notes. Before starting, prepare the permitted notes, user-scoped credentials and account-supported candidates with suitable context capacity. The request creates the research thread; it does not send the notes yet. Filter the fallback candidates using their known context-window metadata: [Request example: Create a new conversation thread](/api/conversations/create-thread#example-cookbook-managed-agents-model-controls-examples-01-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: $API_KEY`; `Authorization: Bearer $JWT`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. If any model in the [`models`](/api/models/schema-1h82h7ri5p#request-field-models) list has less than 128k context, it's silently removed. If all are removed, [`send-message`](/api/conversations/send-message) returns an immediate error. Keep the returned thread ID, then send the user's first notes and question through [generation](/managed-agents/conversations/generation). Follow that run to its answer. Continue with the same thread for follow-ups and use [context management](/managed-agents/conversations/context-management) as history grows. **Finished result:** the research thread has the intended candidate filter and a correlated answer to the supplied notes. If no candidate survives, correct the selection; do not assume the thread can accept unlimited context. ## Recipe: summarize support notes with a catalog price filter \{#price-filtered-generation} Use this for a batch of short support notes. Start with one note in a created thread and replace `bulk-task-001` with that ID. Set thresholds consistent with your permitted candidates and inspect actual usage before increasing volume. These fields compare catalog price per token, not total spend. Unknown prices can pass; use separately enforced budgets for a spending ceiling. For a bulk task, remove models whose known catalog prices exceed these example thresholds: [Request example: Send a message to a conversation](/api/conversations/send-message#example-cookbook-managed-agents-model-controls-examples-02-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: $API_KEY`; `Authorization: Bearer $JWT`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. Retain the accepted run ID, read its correlated reply and check the summary against the supplied note. Inspect measured usage and missing counters separately; known catalog price filters do not calculate the total charge. **Finished result:** one note has a checked summary and an understood outcome. Increase the workload only after that flow works and the account's actual spending controls meet your needs. ## Recipe: return a task summary after tool-assisted work \{#structured-output-with-tool-support} Use a conversation that already contains the task and any completed tool results. Select and authorize the required tools separately, finish their calls, then ask for a summary object. Wait until the prior turn is resolved before using this per-send override; queued sends do not retain it. Require catalog support for both tools and a structured response. This example requests a task summary; it does not attach any tools by itself: [Request example: Send a message to a conversation](/api/conversations/send-message#example-cookbook-managed-agents-model-controls-examples-03-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: $API_KEY`; `Authorization: Bearer $JWT`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. After the run completes, parse and validate its final answer against the same schema before displaying or using it. A valid `summary` string can still be inaccurate, so inspect the content before taking an action. See [structured answers](/managed-agents/model-controls/structured-output) for incomplete, refused and repaired results. **Finished result:** the application receives a completed object with a `summary` string that passes the same schema and accurately reflects the task. A capability filter does not attach tools, and a typed result does not authorize another action. --- URL: https://docs.travila.ai/managed-agents/profiles-prompts # Build a reusable assistant profile \{#create-and-version-agent-profiles} Build one nutrition-coach profile, use it in a conversation, then change its response style without copying a prompt into every send. The finished recipe gives you a stored profile, a conversation explicitly using it and a recorded version you can inspect when behavior changes. Use a single profile first. Add a picker or shared fragments only when your application needs multiple assistants. ## Before you start \{#start-here} You need a provisioned project, a backend secret key for profile management, a model accepted by your account, and the user-scoped credentials used for conversation calls. Replace `YOUR_MODEL_ID` with an [allowed model](/managed-agents/model-controls#allowed-models). Profile management takes the secret key **on its own**: no `X-On-Behalf-Of` or end-user JWT. Conversation calls need the [user-scoped authentication pair](/core-platform/identity-access/authentication). The public profile API uses the `default` project; `X-Project-Id` does not create or select a separate customer project. Choose an unused [`profileId`](/api/models/schema-1hmbcecg1j#response-field-profileid) for the recipe. The example uses `nutrition_coach`; do not overwrite a shared profile just to try it. ## Follow the profile through its first reply \{#get-started} 1. Create the profile below and retain its ID and assigned version. 2. Read it back to confirm the prompt and model you stored. 3. Select it explicitly when creating a conversation, then send one representative question and inspect the reply. 4. Make a controlled update and compare a later turn with the earlier one. The create/read/use steps are the main recipe. The sections after the first reply cover changing, restoring, selecting and importing profiles. ## Step 1: Save the assistant instructions \{#create-a-profile} The example creates [an enabled profile](/api/agent-profiles/create-agent-profile#overview) with a concise response style. Replace the model placeholder before sending. The returned version is the starting point for later comparisons. The model and every fallback in [`models`](/api/models/schema-1h82h7ri5p#request-field-models) must be allowed for your account. Otherwise create and update return `403`, with a message carrying `model_access/MODEL_NOT_ALLOWED` and the refused ID, and nothing is stored. An update is judged on every model it sends, including ones outside its update mask. See [model errors](/managed-agents/model-controls/errors). [Request example: Create an agent profile](/api/agent-profiles/create-agent-profile#example-cookbook-managed-agents-profiles-prompts-index-01-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** the stored record, echoed back with `version: 1`. [Response example: Create an agent profile](/api/agent-profiles/create-agent-profile#example-cookbook-managed-agents-profiles-prompts-index-json-01-response). Example identifiers and values are illustrative; substitute authorized values. ## Step 2: Confirm what you saved \{#read-a-profile} Read the new profile and compare its [`generationConfig.systemPrompt`](/api/models/schema-1h82h7ri5p#response-field-systemprompt), model and version with your intended setup. Do this before attaching it to the first conversation; a profile ID alone does not tell you which instructions are stored. [Request example: Get an agent profile](/api/agent-profiles/get-agent-profile#example-cookbook-managed-agents-profiles-prompts-index-02-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** `{"profile": {...}}` — the full record. Pass [`version`](/api/models/schema-1hmbcecg1j#response-field-version) to read [a specific immutable version](/api/agent-profiles/get-agent-profile#overview) instead of the latest: [Request example: Get an agent profile](/api/agent-profiles/get-agent-profile#example-cookbook-managed-agents-profiles-prompts-index-json-02-request). Example identifiers and values are illustrative; substitute authorized values. For this first run, use the version returned by creation. The version-3 request above illustrates a later inspection; it only works after that version exists. ## Step 3: Use the profile and inspect the reply \{#how-it-works} Create a thread with [`activeProfileId`](/api/conversations/create-thread#request-field-activeprofileid) set to `nutrition_coach`, using the user-scoped credentials from [conversation configuration](/managed-agents/conversations/configuration#agent-profiles). Retain the returned thread ID as [`conversationKey`](/api/conversations/send-message#request-field-conversationkey). Send one representative question with [the normal generation flow](/managed-agents/conversations/generation), retain its [`runId`](/api/conversations/send-message#response-field-runid), and read the correlated outcome. For an existing conversation, use [`setActiveProfileId`](/api/conversations/send-message#request-field-setactiveprofileid) on the send instead. Selecting a profile persists for later turns; an empty value does not clear the selection. **Finished result:** the profile exists at the version you recorded, the conversation explicitly selects it, and the accepted run has a correlated reply or a visible unsuccessful outcome. [Inspect the resolved generation context](/api/agent-profiles/selection-and-versioning#how-it-works) when diagnosing a reply; creating a profile is not itself a test of model behavior. ## Recipe: change the response style without replacing the profile \{#update-a-profile} Read the current profile first, then lower its temperature for a controlled comparison. [Use a leaf mask](/api/agent-profiles/update-agent-profile#overview) to change that setting while keeping the existing prompt and model. Each successful update appends a new immutable version. [Request example: Update an agent profile](/api/agent-profiles/update-agent-profile#example-cookbook-managed-agents-profiles-prompts-index-03-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** `{"profile": {...}}` with the new [`version`](/api/models/schema-1hmbcecg1j#response-field-version). After updating, retain the new version and send a later turn on an unpinned conversation. Compare the actual response and usage with your earlier turn; a lower temperature reduces variation in some models but does not guarantee deterministic output. If the change is unsuitable, use the version-recovery recipe below. ## Recipe: investigate a change and restore earlier content \{#version-history} If replies change after an edit, list versions, read the earlier snapshot and compare the stored prompt and configuration before making another update. The example history represents a profile that has already been edited. [Request example: List a profile's versions](/api/agent-profiles/list-agent-profile-versions#example-cookbook-managed-agents-profiles-prompts-index-04-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** newest first, one entry per successful mutation. [Response example: List a profile's versions](/api/agent-profiles/list-agent-profile-versions#example-cookbook-managed-agents-profiles-prompts-index-json-03-response). Example identifiers and values are illustrative; substitute authorized values. Pair a version number with [`get`](#read-a-profile) to read the saved profile snapshot. Investigating a past turn also requires its fragment-set version, resolved variables, generation configuration and any context added during the turn. Changes to prompt processing and model behavior can also affect the result. A saved profile does not guarantee exact reproduction of a model response. A profile that never existed returns an empty list rather than an error. After [restoring through a new update](/api/agent-profiles/selection-and-versioning#version-history), read the new version back and test a later turn. Historical fragments, supplied variables and model behavior still need separate inspection; restoring profile content alone cannot reproduce every old reply. ## Variant: let the user choose an assistant \{#read-the-selection-library} Once more than one profile exists, populate a picker from the library. After the user chooses, pass that profile ID through the conversation selection step above. Do not send full prompts and tool configuration merely to display a list of choices. Use [the returned selection metadata](/api/agent-profiles/get-agent-profile-library#overview) for the picker, then explicitly select the chosen profile for the conversation. [Response example: Get the profile library](/api/agent-profiles/get-agent-profile-library#example-cookbook-managed-agents-profiles-prompts-index-json-04-response). Example identifiers and values are illustrative; substitute authorized values. A conversation does not automatically select a profile when none is active; explicitly select the customer’s chosen enabled profile. ### Write a useful choice description \{#writing-whentouse} [`whenToUse`](/api/models/schema-1hmbcecg1j#response-field-whentouse) describes when the profile fits a turn. Your selection interface or application policy can use this metadata; the field itself does not enable an automatic router. Write a concrete selection instruction: * Good: `Use when the user asks about food, meals, macros, or logging what they ate.` * Poor: `The nutrition profile.` Use [`description`](/api/models/schema-1hmbcecg1j#response-field-description) to explain the profile in a picker and [`keywords`](/api/models/schema-1hmbcecg1j#response-field-keywords) to support your own search or selection logic. Together with [`profileId`](/api/models/schema-1hmbcecg1j#response-field-profileid), [`name`](/api/models/schema-1hmbcecg1j#response-field-name) and [`enabled`](/api/models/schema-1hmbcecg1j#response-field-enabled), these are the fields returned by [the library](#read-the-selection-library). ## Variant: inventory profiles before a shared change \{#list-profiles} Use full profile records when reviewing dependencies or planning a shared change. Read every page needed for the inventory and [include disabled profiles](/api/agent-profiles/list-agent-profiles#overview) when they matter. Use the selection library for an ordinary picker. [Request example: List agent profiles](/api/agent-profiles/list-agent-profiles#example-cookbook-managed-agents-profiles-prompts-index-06-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** [Response example: List agent profiles](/api/agent-profiles/list-agent-profiles#example-cookbook-managed-agents-profiles-prompts-index-json-05-response). Example identifiers and values are illustrative; substitute authorized values. ## Retire an assistant without stranding its conversations \{#delete-a-profile} Before disabling or deleting a profile, identify conversations that still select it and move them to enabled replacements. Direct sends cannot use a disabled profile; queued messages have the [different fallback behavior](/managed-agents/conversations/configuration#when-the-active-profile-cannot-be-used) described in configuration. Retirement is separate from the response-style test above. **For reversible retirement**, send this body to `agent-profiles/update` with your management credentials. It disables selection without deleting the profile or its version history: [Request example: Update an agent profile](/api/agent-profiles/update-agent-profile#example-cookbook-managed-agents-profiles-prompts-index-json-06-request). Example identifiers and values are illustrative; substitute authorized values. **For permanent removal**, use the delete request below instead. [Deletion removes the profile from the current library, retains historical versions and does not check for remaining references](/api/agent-profiles/delete-agent-profile#overview): [Request example: Delete an agent profile](/api/agent-profiles/delete-agent-profile#example-cookbook-managed-agents-profiles-prompts-index-07-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** `{}` on success. Re-enable a disabled profile through another masked update when it should be selectable again. Deletion retains historical versions, but their presence does not guarantee that dependent turns can be reproduced. Choose disabling when you need a profile that can be re-enabled. ## Variant: migrate an existing prompt library \{#import-an-existing-prompt-library} If your prompts already live in a file-based library — personas plus shared blocks they `@include` — [convert the whole thing in one call](/api/agent-profiles/import-agent-profiles#overview) rather than hand-porting each one. [Request example: Import a prompt library](/api/agent-profiles/import-agent-profiles#example-cookbook-managed-agents-profiles-prompts-index-08-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** [Response example: Import a prompt library](/api/agent-profiles/import-agent-profiles#example-cookbook-managed-agents-profiles-prompts-index-json-07-response). Example identifiers and values are illustrative; substitute authorized values. Inspect the imported profiles and fragments, supply any required variables explicitly, then run the same first-reply recipe. Import success confirms stored configuration; it does not prove the resulting prompt produced the intended answer. ### Flatten or fragments \{#flatten-or-fragments} | [`emitFragments`](/api/agent-profiles/import-agent-profiles#request-field-emitfragments) | What happens | Choose it when | | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `false` (default) | Each `@include` is resolved inline into that profile's system prompt. No fragment rows are written. | You want profiles self-contained and are happy editing shared text in several places. | | `true` | Shared blocks become fragment rows, referenced with `{{template "id" .}}`. | You want one edit to reach every profile. [Every block referenced by an `@include` must be supplied in the same call](/api/agent-profiles/import-agent-profiles#overview). | ## Related \{#related} * [Prompt Fragments](/managed-agents/profiles-prompts/prompt-fragments) — the shared blocks profiles compose * [Conversation Configuration](/managed-agents/conversations/configuration#agent-profiles) — selecting a profile for a conversation * [Agent tools](/integrations/tools-connections) — the tool bundle a profile carries * [Evals](/insights/evaluation) — scoring what a profile produced --- URL: https://docs.travila.ai/managed-agents/profiles-prompts/prompt-fragments # Reuse and update shared assistant instructions \{#share-prompt-fragments-across-profiles} Keep a common instruction block consistent across assistants without editing every profile. This recipe creates a `safety` fragment, includes it in an existing nutrition-coach profile, verifies the stored sources and then updates the shared text. The result is a reusable instruction block with a recorded fragment-set version. A fragment is prompt text, not an enforcement mechanism or a guarantee that the model follows the instruction. ## Before you start \{#get-started} Use an existing profile such as `nutrition_coach` and a backend secret key for the same project. Fragment and profile management take the secret key **on its own**, with no `X-On-Behalf-Of` or user JWT. The example fragment ID must not already exist. Start with one profile and inspect its reply before adding the include to other profiles. Every later edit reaches all profiles that include the fragment; there is no per-profile rollout. Profile pins do not pin fragment content. The example prompt uses `{{.userName}}`. Supply `userName` explicitly through [prompt variables](/managed-agents/conversations/configuration#prompt-variables) before the test send; do not rely on a declared default being inserted automatically. ## Step 1: Create the block and include it in the profile \{#create-a-fragment} Create the shared text, then use the second request below to update only the existing profile's system prompt. Keep the model and other settings in that profile. [The include resolves at render time](/api/agent-profiles/create-prompt-fragment#overview), so later fragment edits affect subsequent turns. [Request example: Create a prompt fragment](/api/agent-profiles/create-prompt-fragment#example-cookbook-managed-agents-profiles-prompts-prompt-fragments-01-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** [Response example: Create a prompt fragment](/api/agent-profiles/create-prompt-fragment#example-cookbook-managed-agents-profiles-prompts-prompt-fragments-json-01-response). Example identifiers and values are illustrative; substitute authorized values. Then include it from a profile's system prompt, via [Update an agent profile](/api/agent-profiles/update-agent-profile#request): [Request example: Update an agent profile](/api/agent-profiles/update-agent-profile#example-cookbook-managed-agents-profiles-prompts-prompt-fragments-json-02-request). Example identifiers and values are illustrative; substitute authorized values. Keep the updated profile ID for the test after the source readback below. ## Step 2: Check the sources and record their set version \{#read-and-list} Read `safety` back to confirm the text, then list fragments and retain [`setVersion`](/api/agent-profiles/get-prompt-fragment-set#request-field-setversion) alongside the profile version and variables used for the test. The sample list below represents a project with previous fragment writes; use the version your project returns. [Request example: Get a prompt fragment](/api/agent-profiles/get-prompt-fragment#example-cookbook-managed-agents-profiles-prompts-prompt-fragments-02-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** `{"fragment": {...}}`. [Request example: List prompt fragments](/api/agent-profiles/list-prompt-fragments#example-cookbook-managed-agents-profiles-prompts-prompt-fragments-03-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** [Response example: List prompt fragments](/api/agent-profiles/list-prompt-fragments#example-cookbook-managed-agents-profiles-prompts-prompt-fragments-json-03-response). Example identifiers and values are illustrative; substitute authorized values. [`setVersion`](/api/agent-profiles/get-prompt-fragment-set#request-field-setversion) is the thing to notice — see [below](#set-versions). Select the updated profile for a conversation, set `userName`, and send a representative question. Follow the run to a correlated outcome using [generation](/managed-agents/conversations/generation). Inspect the resulting behavior before reusing the include more widely. **Finished result:** the stored profile includes `safety`, the fragment exists with the intended text, and you have a correlated test-turn outcome plus the source versions needed to investigate it. A successful turn alone does not prove that a template rendered correctly. ## Recipe: change shared wording across the assistants \{#update-a-fragment} Before editing, identify [every profile and nested fragment that includes this block](/api/agent-profiles/update-prompt-fragment#overview). Review the effect on those assistants: the update below changes the medical-advice wording for all of them on their next turn. [Request example: Update a prompt fragment](/api/agent-profiles/update-prompt-fragment#example-cookbook-managed-agents-profiles-prompts-prompt-fragments-04-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** `{"fragment": {...}}`. Read the fragment and new set version after the update, then try the affected conversation again. If the wording is unsuitable, restore the earlier text through another update; reading an old set does not activate it. ## Recover the text used before a change \{#set-versions} When investigating a changed reply, use [the fragment-set version recorded with that turn](/api/agent-profiles/selection-and-versioning#prompt-fragments-set-versions). Retrieve the old set, compare it with the current text and inspect the profile and variable values from the same turn. [Request example: Get a fragment set by version](/api/agent-profiles/get-prompt-fragment-set#example-cookbook-managed-agents-profiles-prompts-prompt-fragments-05-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** every fragment as it existed at that version, ordered by [`fragmentId`](/api/models/schema-1j5dvgfmr9#response-field-fragmentid). [Response example: Get a fragment set by version](/api/agent-profiles/get-prompt-fragment-set#example-cookbook-managed-agents-profiles-prompts-prompt-fragments-json-04-response). Example identifiers and values are illustrative; substitute authorized values. ## Retire a shared block without leaving broken includes \{#delete-a-fragment} First remove or replace the include in every dependent profile and nested fragment, then inspect a test turn. Only delete the shared block after those dependencies are handled. The request below is the final removal step, not an automatic dependency cleanup. [Request example: Delete a prompt fragment](/api/agent-profiles/delete-prompt-fragment#example-cookbook-managed-agents-profiles-prompts-prompt-fragments-06-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** `{}` on success. Check both direct and nested includes before removing the shared block. Test a dependent conversation afterward; [a returned reply alone does not prove its instructions rendered](/api/agent-profiles/delete-prompt-fragment#overview). ## Related \{#related} * [Agent Profiles](/managed-agents/profiles-prompts) — the profiles that include these fragments * [Import](/managed-agents/profiles-prompts#import-an-existing-prompt-library) — converting an `@include`-based library into fragments in one call --- URL: https://docs.travila.ai/managed-agents/voice-media # Add a spoken conversation to your app (Preview) \{#voice-sessions-preview} > **Info: Deployment prerequisites** > > Voice sessions require an enabled voice service and a registered agent. Confirm availability for your account and obtain the supported agent name before starting a session. Let a user speak with the assistant in an existing conversation. Create a real-time voice session, then join its room from your client using the returned room URL and token. The platform provisions the room and joins a voice agent tied to the conversation's history and agent profile. Before starting, have a conversation ID, the deployment's registered agent name, user-scoped credentials and a client capable of joining the room provider. Treat recording as a separate user choice; use disabled recording unless the user has opted in. This recipe starts with a new room and the registered agent's configured voice. ## Step 1: Start the voice session for the existing thread \{#create-a-voice-session} Replace `support-chat-001` with the existing thread ID and `my-voice-agent` with the registered name supplied for your deployment. Call this once for the user's intent to start a session; if its response is lost, do not create more sessions just to discover whether the first one started. [Request example: Create a voice session (in progress)](/api/conversations/create-daily-session#example-cookbook-managed-agents-voice-media-index-01-request). 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. Keep the returned session ID and join details. Session creation starts the room/agent setup; the next step checks that both are usable. ## Step 2: Join the room and confirm the exchange \{#response} Use the returned room name with your configured Daily domain and give the room SDK the returned meeting token. Wait for room connection and the agent-ready lifecycle signal before inviting the user to speak. [Response example: Create a voice session (in progress)](/api/conversations/create-daily-session#example-cookbook-managed-agents-voice-media-index-json-01-response). Example identifiers and values are illustrative; substitute authorized values. > **Note: Voice transcripts and message history** > > Use conversation history to display the saved exchange. Do not automatically submit every transcript fragment again through `send-message`, which could duplicate a turn already saved by the voice session. If a session ends before a reply, refresh conversation state and keep any unsent draft separate. Ask one question, listen for the reply, then read the same conversation's history. **Finished result:** the client connected to the expected room, the agent was ready, and the saved exchange is visible in the original thread. Keep an unanswered or unsaved exchange unresolved rather than treating session creation as a successful conversation. When the user leaves, stop local audio capture and leave through the room client's supported lifecycle. If the session ends unexpectedly, refresh conversation state, preserve any unsent draft and explain the interruption. Local disconnect is not proof that every remote action stopped. ## Variant: associate app metadata with the session \{#request-fields} For an application that displays the speaker’s name beside the session, put that display information in [`userData.fields`](/api/models/schema-1kri473p8r#request-field-fields) when creating the session and read it back from the response. Treat it as client metadata, not authentication. The main recipe creates a new room. If your deployment uses a pre-existing room, follow its supported join setup and the [session request reference](/api/conversations/create-daily-session); do not create another room merely to recover a lost join response. ## Variant: select supported voice or audio settings \{#agent-config-socayoconfig} Use the registered agent’s settings for the first conversation. To change the spoken experience: 1. Choose a voice, language, provider and audio settings supported by your deployment. 2. Apply those choices through [`socayoConfig`](/api/conversations/create-daily-session#request-field-socayoconfig) using the [session configuration reference](/api/conversations/create-daily-session). 3. Repeat the connect, speak and saved-history check with the actual client audio path. Inspect readiness errors and the resulting audio. An accepted setting does not prove the voice or provider is provisioned. Avatar/video and sample-rate options require their corresponding deployment support. ## Variant: limit room lifetime, participants and recording \{#room-properties-dailyroomproperties} Before inviting the user, choose [the room lifetime, participant limit and permitted processing region](/api/conversations/create-daily-session#overview) through [`dailyRoomProperties`](/api/conversations/create-daily-session#request-field-dailyroomproperties). Set initial audio/video state for the user’s expected entry experience and verify the room behaves accordingly. Keep recording disabled unless the user explicitly opts in. Permission to speak is not permission to retain a recording; the main request uses `RECORDING_MODE_DISABLED`. Review recording choices on the meeting token as well as the room before enabling them. ## Separate recipe: dictate a draft without starting a voice agent \{#speech-to-text-tokens-preview} > **Info: Deployment prerequisite** > > Speech-to-text token issuance must be enabled for your account. The endpoint returns an error when the required service credentials are unavailable. To let your client transcribe audio without exposing your backend API key, [mint a short-lived speech-to-text token](/api/conversations/mint-stt-token#overview). The token is a single-purpose STT grant — the client calls Cartesia's STT API directly with it; your key never reaches the client. [Response example: Mint a speech-to-text token (in progress)](/api/conversations/mint-stt-token#example-cookbook-managed-agents-voice-media-index-json-02-response). Example identifiers and values are illustrative; substitute authorized values. Use the returned token lifetime and account for time elapsed during recording. Use this path for a user recording a message draft. It does not create a voice room or automatically send an assistant turn. Present the resulting transcript for review before using the normal message-send flow. ### Finish the dictated draft and handle interruption \{#recommended-client-flow} 1. **Mint for an explicit recording** — obtain the token when needed and account for its expiry during a long recording. Token issuance and transcription are subject to permissions, limits and cost. 2. **Transcribe the clip** — send the audio to Cartesia's STT API using the token. The token is scoped to speech-to-text only; it cannot be used for anything else. 3. **Handle failure explicitly** — if a permitted local recognizer is available, offer it; otherwise preserve the recording/draft according to the user's choices and report the failure. Do not silently claim fallback succeeded. A late final transcript must not overwrite user edits. Your backend API key stays server-side throughout. **Finished result:** the user has an editable transcript, or a visible transcription failure with their draft handled according to their choice. Send it as a new message only after the user chooses to send. An STT token response alone is not a transcription result. ## Upcoming recipe: keep a spoken session on local infrastructure \{#local-voice-sessions} **Status:** Upcoming — not yet available. Use this path when the conversation’s audio must remain on supported local infrastructure. Select a supported language, voice and deployment capacity; keep hosted fallback disabled when audio must stay local. Choose recording permission separately. 1. Start the local session and confirm readiness before accepting speech. 2. Allow thoughtful pauses, then process the completed utterance once. 3. On deliberate interruption, stop playback and keep late audio from restarting it. 4. Inspect the saved exchange or the explicit unavailable result when local capacity is exhausted. **Finished result:** a local spoken exchange or a visible failure that has not silently routed audio to a hosted provider. Local endpoints and deployment instructions are not yet available. The hosted session and speech-to-text token instructions above retain their current prerequisites. ## Related \{#related} * [Conversations Guide](/managed-agents/conversations) — Threads, messages, and generation * [LLM API Reference](/api/conversations) — Full endpoint reference --- URL: https://docs.travila.ai/managed-agents/coding-assistants # Fix a repository bug and review the change \{#overview} **Status:** Upcoming — not yet available. Hand off a contained bug fix and get back the change, the checks that ran and the work still unfinished. This recipe uses a CSV importer that treats blank rows as records: the task is to ignore those rows while preserving existing valid-row behavior. Start with one module and a known repository revision. The finished result is a reviewable diff and verification evidence for that revision. Committing, publishing and deploying are separate choices. The coding-assistant service and dedicated clients are not yet available. This recipe describes the completed-product workflow and supplies no current start command. ## Step 1: define the bug and the permitted change \{#assignment-and-permissions} **Status:** Upcoming — not yet available. Supply the repository, starting revision, affected importer, representative input and expected output. Include one fixture with a blank row and one with valid rows. Identify concurrent edits to preserve and the organization, project, environment and customer scope of connected resources. For the first run, allow reading the repository, editing the importer and relevant tests, and running the supported local checks. Reserve commit, branch publication, pull-request creation, merge and deployment for separate decisions. State the approved runtime, file area and network destinations. If the task delegates work, give each child a bounded assignment within the original authority and total budget. Review the exact plan or action when approval is required; a changed destination or material plan change needs the applicable new decision. Approval cannot exceed the task's limits or the reviewer's authority. **Ready to run:** the task has a testable outcome, a starting revision, permitted files/actions and explicit limits. “Improve the importer” alone is not the acceptance condition. ## Step 2: supply the repository’s relevant working instructions \{#instructions-and-skills} **Status:** Upcoming — not yet available. Provide the repository instructions and reviewed skills that govern the importer and tests. Inspect their active revisions and origins, and resolve material conflicts before the assistant relies on them. Imported files, tool output and draft skills cannot grant additional access. Use an existing reviewed practice when it fits this change. If the assistant proposes a reusable CSV-cleaning procedure after the task, keep it as a draft until a reviewer inspects that exact revision and an example use. Activating the draft is a separate decision. The active revision remains identifiable, and a practice can be disabled or restored when needed. The immediate goal is the importer fix; creating a new shared practice is an optional follow-up, not a prerequisite for completing it. ## Step 3: run the fix within a finite budget \{#bounded-first-run} **Status:** Upcoming — not yet available. 1. Select supported clients, languages and tools for the repository. 2. Supply the authorized source and fixture files for the blank-row case. 3. Set finite time and usage limits, plus the applicable compute, output, storage and network limits. Child work shares the total budget. 4. Ask the assistant to reproduce the fixture failure, make the contained change and run the relevant existing and new checks. 5. Follow progress and review any action that needs the approval defined in step 1. For self-hosted operation, use the supported deployment setup. Choose a hosted option separately with its data location and cost. The service and start controls are still unavailable until release. If the limit arrives before checks finish, the task returns the partial diff and names the outstanding checks. Review that result before authorizing another bounded run; a new run does not retroactively make the first one complete. ## Step 4: accept the fix from the diff and completed checks \{#result-review} **Status:** Upcoming — not yet available. Compare the diff against the starting revision and concurrent work. Confirm that it addresses blank rows without changing valid-row behavior or unrelated files. Inspect which checks actually ran, their revision and their results. A test file or suggested command is not execution evidence. Missing tests, incomplete children, truncated artifacts and unknown usage remain visible. For delegated work, review each child's contribution; successful child output can be useful while the parent task is still incomplete. **Finished result:** a reviewable importer change with completed verification for the stated fixtures and any remaining uncertainty called out. If an integration environment was unavailable, decide whether that missing check prevents acceptance. The result distinguishes edited files, committed changes, published branches, pull requests and deployed behavior. Accepting a diff does not imply that every later action occurred. ## Recover the original task or continue with a separate publication decision \{#task-recovery} **Status:** Upcoming — not yet available. After a disconnect, return to the original task and operation references. Recover current state before asking for duplicate work. Reconnect resumes progress or explains how to resynchronize; an uncertain command or external action is reconciled before another execution. Once the fix is accepted, authorize any desired commit or publication for the exact target. If publication loses its response, inspect that original operation and the target before publishing again. Branching or reverting conversation history does not undo a published change. Stopping prevents new work and reports actions still pending or uncertain. For unattended operation, set its purpose, allowed tools and total budget. A wake check with no change remains distinct from a failed check, run or notification. Required interactive approval that is unavailable ends with an actionable result. See [profiles](/managed-agents/profiles-prompts), [tool approval](/managed-agents/delegation-approvals/using-tools), [computer use](/managed-agents/computer-use), [model selection](/managed-agents/model-controls) and [billing](/core-platform/billing-spend) for extensions to the recipe. --- URL: https://docs.travila.ai/managed-agents/computer-use # Prepare and submit a partner registration \{#overview} **Status:** Upcoming — not yet available. Have the assistant fill a partner registration form from an authorized report, review the final values, then confirm what the site accepted. Use a browser session for this recipe; the account, files and approval stay tied to the task. You need the permitted website/account, the source report, an authorized person for login challenges and a decision on who approves submission. The result is a confirmed submission or a clearly unresolved action, plus any permitted output files and session cleanup status. Browser and desktop sessions are not yet available. This describes the completed-product workflow and supplies no current session-start command. ## Step 1: open a session for the account and report \{#session-preparation} **Status:** Upcoming — not yet available. 1. Describe the registration outcome and select the website, authorized account and organization/project/environment/customer scope. 2. Select the report the task may read or upload, and any permitted output locations. 3. Require approval before submitting the completed form. Filling fields and sending them are separate actions. 4. Arrange the supported login-challenge handoff. If the authorized person cannot complete a required challenge, leave the task blocked. 5. Set duration, concurrency, action, compute, storage, capture and usage limits. 6. **Recording is off unless you opt in.** If you enable it, choose permitted access and expiry for the recording and artifacts. 7. Review the account, file permissions, limits and execution location before starting. Any optional provider or fallback stays inside the approved data-location, account, consent and cost boundaries. For this registration, leave recording off and permit only the selected report and destination. The session shows these choices before work begins. ## Step 2: inspect the completed form and approve submission \{#action-review} **Status:** Upcoming — not yet available. Let the assistant inspect the page and prepare the form from the report. Compare the current account, site, recipient and final fields with your intended registration before approving the consequential action. If the account, destination or other material detail changes after review, return for the applicable new approval. A login challenge does not approve every later account action. Page content, downloads and dialogs provide task data; they cannot widen the assignment. After submission, inspect the site's acceptance outcome. A screenshot or lack of an error is not confirmation that the form was accepted. Research or extracted results retain their source and observation time; an inaccessible page, blocked site or incomplete extraction stays visible. **Submission result:** the site confirms the intended registration, or the action remains failed or unresolved with enough context to recover it. Do not approve a second submission merely to obtain a clearer response. ## Step 3: save the result and close the session \{#artifacts-and-cleanup} **Status:** Upcoming — not yet available. Retrieve any permitted output files belonging to the registration and save needed copies before their stated expiry. Downloads remain subject to file access and size limits. Close the session after the result is understood and inspect cleanup status. Travila cleans up the environment, temporary login material, recordings and files under the applicable retention policy. A closed window alone does not confirm cleanup; retain the session reference for support when it is incomplete. **Finished result:** the customer has the registration outcome and any permitted output, and can see whether cleanup is complete or still pending. A usable confirmation and pending cleanup are separate facts. ## Recover when the site or connection stops responding \{#submission-recovery} **Status:** Upcoming — not yet available. Reconnect through the original session and action references to recover the last confirmed observation. You return to the authorized live session or receive an explanation that attachment is unavailable; recovery does not silently choose another account or replacement session. If the site stopped responding after submission, inspect its confirmation page or account record before another attempt. When the outcome cannot be established, keep it unresolved and stop automatic repetition. Stopping or expiring the session prevents new actions and starts cleanup. It does not undo a transmitted form. Inspect external actions still pending or uncertain separately from the session's terminal state. ## Variant: use a desktop when the task needs another application \{#working-surface} **Status:** Upcoming — not yet available. Keep the registration in a browser when navigation, page inspection, extraction, forms, tabs, screenshots and authorized file transfer are enough. Use an appropriate API or bounded integration when it already performs the task. Choose a desktop only when the workflow also needs a supported graphical application, such as reviewing an authorized spreadsheet file. The initial desktop option is Linux with a supported application set. Native mobile automation, macOS/Windows hosting, multi-monitor work and unrestricted remote takeover are outside that scope. Desktop selection does not grant terminal use, arbitrary file access, installation or host access. Those actions need their own permission. See [coding tasks](/managed-agents/coding-assistants), [tool approvals](/managed-agents/delegation-approvals/using-tools), [safety](/managed-agents/safety) and [deployment operations](/enterprise/deployment-operations) for related workflows. --- URL: https://docs.travila.ai/managed-agents/safety # Run a support assistant within its approved data and action policy \{#overview} **Status:** Upcoming — not yet available. Let a support assistant use the customer's order details to answer their question while keeping unrelated destinations and actions outside its permission. This recipe sets that policy, checks representative requests, then handles a blocked or interrupted customer request without hiding the reason. You need an approved use, data audience, permitted destinations and actions, plus an authorized review contact. The result is a visible policy decision for the request and a recovery path for disputed or unavailable checks. Dietary declaration review is a separate recipe below. The policy console, complete safety workflow and personalized dietary assessment are not yet available. Existing model filters and product tags do not supply these complete controls. ## Step 1: allow the support task and define what needs review \{#effective-policy} **Status:** Upcoming — not yet available. Define the task as answering the current customer's order question. Select the data it may read, the model and tool destinations that may receive it, and the response audience. Keep an unrelated destination outside that approved path. Choose the allowed actions and work limits. Identify exact actions requiring eligible approval, required checks before displaying a response and whether any partial delivery is explicitly permitted. Set who may inspect protected evidence, receive incident/review notifications and suspend the workflow. Match escalation recipients and consent to actual staffed coverage; configuring a recipient does not create continuous monitoring. Review the platform/provider requirements and additional organization controls, then resolve contradictory or unsupported settings before activation. A project setting can strengthen a supported policy. An ordinary approval cannot waive a hard prohibition, and a detector result does not grant resource access. **Ready for the customer flow:** the allowed data path, action limits, response checks and review route are explicit for the intended audience. ## Step 2: check allowed, blocked and unavailable outcomes \{#policy-qualification} **Status:** Upcoming — not yet available. Use controlled requests with non-sensitive data before applying the configuration to real support work: 1. Ask a permitted question about the test customer's order and inspect the allowed result. 2. Ask for disclosure to an unrelated destination and inspect the blocked result and its explanation. 3. Include a harmless quotation that resembles a prohibited instruction to check whether it needs false-positive review. 4. Exercise the supported tools, schedules or memory paths used by the application, not only the initial message. 5. Inspect a checker-unavailable result separately from an allowed or blocked decision. Keep the operation and policy references for anything needing review. Mandatory controls apply across supported features and review evidence remains protected. These representative outcomes help you assess the configured policy; they do not establish detection of every harmful input. ## Step 3: resolve a blocked support request \{#blocked-and-interrupted-results} **Status:** Upcoming — not yet available. When a real request is blocked or interrupted, inspect whether the result is a policy denial, required eligible approval, uncertain evidence or an unavailable checker. Explain the relevant limitation to the customer without exposing protected records or bypass instructions. For a suspected false positive, submit review through the approved route with the operation and policy references. The original decision remains in effect while review is pending; asking for review does not grant broader access. If partial delivery was permitted, identify any response already shown before an interruption or correction. Later monitoring cannot undo that disclosure or replace a required before-delivery check. **Finished result:** the customer receives the permitted answer or a truthful blocked, waiting, uncertain or unavailable outcome with the applicable next step. A pending appeal is never displayed as approval. ## Separate recipe: review a product against the user’s dietary declarations \{#dietary-declarations} **Status:** Upcoming — not yet available. Use this workflow when the user opts into dietary personalization: 1. Let the user inspect their stored declarations and correct them before assessing a product. Keep unknown information, an explicit declaration of none and a stated constraint distinct; an empty or stale update does not erase a declaration. 2. Retain simultaneous preferences and unsupported declarations for review. Keep allergies, intolerances, celiac disease and personal preferences distinct. 3. Identify the product and review the current label, evidence source and freshness. 4. Show the matching outcome with the source wording and any uncertainty. 5. Keep the warning attached through the assistant response and supported export or summary. Let the user withdraw personalization when they no longer want it. | Outcome | What the user sees | | ----------------------------- | ------------------------------------------------------------------------------ | | Known conflict | The declared constraint, matching evidence and warning | | Possible conflict | The possible concern with its original wording and limits | | No matching declaration found | No match in the available evidence; no product-safety certification | | Unknown | Missing, unsupported, stale, partial or contradictory evidence or declarations | For a label saying “may contain,” preserve that wording rather than changing it to a definite ingredient claim or clearance. “Contains,” “may contain” and “does not contain” remain distinct; contradictory evidence stays visible. Missing tags, model confidence and a negative keyword match cannot establish safety. Verify the current label or ask its source for clarification when catalog evidence is incomplete. A catalog outage produces unavailable evidence, not clearance. **Finished result:** the user can review their declaration and the product evidence together, with meaningful uncertainty preserved. This feature does not provide diagnosis, emergency care or general allergen-safety certification. ## Follow an incident or withdraw access and personalization \{#incidents-and-access-removal} **Status:** Upcoming — not yet available. For an incident, open the affected operation and scope with the policy/evidence revision and authorized review state. Use the approved contact and follow notification progress: pending, sent, acknowledged, failed and unknown are different outcomes. Human monitoring requires an actual staffed recipient or approved program. For suspension, personalization withdrawal or deletion: 1. Submit the intended request for the affected scope. 2. Inspect whether dependent work has stopped and which actions or cleanup remain pending. 3. Review any records that must be retained and the stated reasons. 4. Keep the original request reference for follow-up until the outcome is understood. **Finished result:** access-removal and cleanup outcomes are visible separately. The user can see what stopped, what remains in progress and why any record remains, rather than treating a submitted request as completed erasure. See [tool approvals](/managed-agents/delegation-approvals/using-tools), [model selection](/managed-agents/model-controls), [computer use](/managed-agents/computer-use) and [assurance and support](/enterprise/assurance-support) for related workflows. --- URL: https://docs.travila.ai/managed-agents/delegation-approvals/build-agent-with-tools # Let a customer navigate your app through chat \{#build-an-agent-that-uses-your-tools} Let a user ask the assistant to open their profile in your app. Define a navigation tool, receive the requested action, check and execute it in your app, then return the actual result so the assistant can finish its reply. The optional connected-app step extends the workflow to a supported third-party account such as Google Calendar. Client-side tools do not go through the approval queue. Approval is a separate mechanism for tools the *platform* runs but a human must authorise — see [approval patterns](/managed-agents/delegation-approvals/using-tools#tool-execution-policy). Your application must check the user's permissions, validate the arguments and obtain any required confirmation before running its own tool; the run waits for your result. Start with one allowed route and one tool. The completed recipe opens the customer's profile, returns the actual navigation result and displays the assistant's reply for that run. Connected SaaS tools are a separate extension after the client-tool loop works. ## Prerequisites \{#prerequisites} * A **secret key** (`sk_…`) for your tenant, issued through your enabled management surface or account administrator. Backend calls use the secret key plus `X-On-Behalf-Of` to act on behalf of a specific user. See [Authentication & API Keys](/core-platform/identity-access/authentication). * A conversation thread. Create one with `create-thread` if you do not have one. See [Build an AI chat assistant](/managed-agents/conversations/build-chat-assistant) for the full setup. ## Step 1: Describe the navigation your app can perform \{#step-1-define-a-client-side-tool} Client-side tools are actions that run in your app or backend, not on the platform. Declare them in [`clientTools`](/api/models/schema-1h82h7ri5p#request-field-clienttools) when creating the thread — or per turn via [`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig): [Request example: Create a new conversation thread](/api/conversations/create-thread#example-cookbook-managed-agents-delegation-approvals-build-agent-with-tools-01-request). 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. **Response:** [Response example: Create a new conversation thread](/api/conversations/create-thread#example-cookbook-managed-agents-delegation-approvals-build-agent-with-tools-json-01-response). Example identifiers and values are illustrative; substitute authorized values. Save the [`threadId`](/api/models/schema-1i84dsgmg6#response-field-threadid) — you'll pass it as [`conversationKey`](/api/conversations/send-message#request-field-conversationkey) in every subsequent request. Implement the corresponding action in your application before sending the test question. For this recipe, `/profile` must be an allowed route for the signed-in user. [Declaring the tool schema does not implement navigation or validate arguments](/api/models/schema-1gomaj79cc#overview). ## Step 2: Ask to open the profile and retain the pending call \{#step-2-send-a-message-and-receive-the-call} Send a message that makes the model want to navigate. The model reads your tool description and decides whether to call it. Use `send-message-sync` for a bounded wait that can return the pending call directly. If the wait ends first or the connection drops, use the recovery flow below; do not resend the message. [Request example: Send a message and wait for the result](/api/conversations/send-message-sync#example-cookbook-developer-experience-local-tooling-testing-01-request). 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. **Response:** [Response example: Send a message and wait for the result](/api/conversations/send-message-sync#example-cookbook-managed-agents-delegation-approvals-build-agent-with-tools-json-02-response). Example identifiers and values are illustrative; substitute authorized values. `AGENT_STATUS_AWAITING_CLIENT_TOOLS` means the run is paused on you. Take the [`id`](/api/models/schema-1it6mqsqoo#response-field-id) and [`name`](/api/models/schema-1it6mqsqoo#response-field-name) off the pending call, and keep [`clientToolCursor`](/api/conversations/send-message-sync#response-field-clienttoolcursor) — [you need all three in the next step](/api/conversations/submit-client-tool-results-sync#overview). ## Step 3: Navigate once and report what happened \{#step-3-return-the-result-and-get-the-reply} For `navigate_to`, check that `screen` names an allowed route and that the current user may open it. Run the action, then post its actual result with `submit-client-tool-results-sync`. The response may contain the assistant reply, another tool batch or a still-active outcome; inspect [`status`](/api/conversations/send-message-sync#response-field-status) before treating the turn as finished. [Request example: Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync#example-cookbook-developer-experience-local-tooling-testing-02-request). 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. **Response:** [Response example: Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync#example-cookbook-managed-agents-delegation-approvals-build-agent-with-tools-json-03-response). Example identifiers and values are illustrative; substitute authorized values. After submitting the real result, handle another pending batch if one is returned; otherwise inspect the correlated run outcome. Follow [the result contract](/api/conversations/submit-client-tool-results-sync#overview) before declaring the customer’s navigation complete. Copy the pending call’s `id` and `name` into `toolCallId` and `toolName`, and return the actual `resultJson`. Echo the latest `clientToolCursor` for each synchronous batch. Another `AGENT_STATUS_AWAITING_CLIENT_TOOLS` response starts another batch; provisional text or a request whose wait ended early is not a terminal outcome. ## Check the customer’s completed navigation \{#run-it} After the request above, verify the whole customer journey: 1. The app received the complete `navigate_to` call, ID and current [`clientToolCursor`](/api/conversations/send-message-sync#response-field-clienttoolcursor). 2. It validated `/profile` and the user's access before executing the action. 3. The profile screen actually opened, and the submitted result describes that outcome. 4. The same run reached a recognized terminal outcome, or another tool batch was handled with its new cursor. **Finished result:** the screen is open and the assistant's available reply is tied to the completed action. If navigation failed, submit a truthful failure outcome rather than claiming it opened. The default five-minute answer window ends the wait on expiry; it does not establish whether an external action happened. Recover the original call before repeating an uncertain action. ## Recover the call when your connection cannot stay open \{#if-you-cant-hold-a-connection} A worker can send with `send-message` and learn about a call from the enabled `llm.tool_call_started` delivery surface or by polling [pending client tools](/api/conversations/list-pending-client-tools). The event’s presence in the API does not establish that webhook delivery is enabled in your deployment. Retain the original conversation and call IDs. Read the pending call, its deadline and current status before executing; when the call ID is known, use [the exact call readback](/api/conversations/get-tool-call#overview); a dropped connection does not authorize repeating an action that may already have completed. Validate arguments and permissions, reconcile the external result, then answer the same pending call with `submit-client-tool-results`. Inspect the resumed run to its outcome. Do not resend the original user message to recover a lost response. That creates another send and can invoke the configured cancel, queue, reject or ignore policy. If the call has become terminal or its deadline has passed, stop the old execution attempt and use the reported outcome. ## Separate recipe: let the customer connect a calendar \{#step-4-connect-a-third-party-app-optional} Use a connected calendar when the assistant needs a supported external account. The hosted Pipedream integration must be enabled for your deployment; it exposes connected accounts through `pipedream:{appSlug}` MCP servers without your application storing their credentials. 1. Follow [the connected-account recipe](/integrations/tools-connections/connected-apps) to issue a fresh Connect link for this attempt and use its returned expiry when the user chooses to connect. Redirect them through the authorized flow. 2. After the return, list accounts to confirm the intended calendar exists; a redirect alone is not the result. 3. Select `pipedream:google_calendar` for the conversation and inspect its discovered tools. Discovery occurs per turn, so a later connection is picked up on the next message. 4. Ask for work supported by those tools, apply the required [platform approval policy](/managed-agents/delegation-approvals/using-tools), and follow the run to its actual calendar outcome. **Finished result:** the chosen calendar is connected and the requested calendar work has a known outcome. A connection or tool list alone does not establish that the work finished. Use [connected-app recovery](/integrations/tools-connections/connected-apps) for an unhealthy account and [tool recovery](/managed-agents/delegation-approvals/using-tools#if-the-connection-drops) for a lost call response. ## Diagnose a platform MCP tool independently \{#try-it-out} If the connected-app variant fails before a useful tool result, [test an authorized platform tool directly](/integrations/tools-connections#calling-tools-directly) using the exact discovered server, name and argument schema. That diagnostic bypasses the conversation; it cannot test the `navigate_to` action implemented in your app. Keep direct memory-tool experiments to isolated or operator-qualified data. A caller-supplied memory user ID needs trusted-backend authorization; the authentication header does not automatically rewrite that argument. See [memory scope](/managed-agents/memory-knowledge) before using real records. ## Next steps \{#next-steps} | I want to... | Go to | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | Understand all tool sources and how they interact | [Agent tools](/integrations/tools-connections) | | Connect users' third-party SaaS accounts | [Connected apps](/integrations/tools-connections/connected-apps) | | Discover what MCP servers and tools are available | [List available servers](/api/conversations/mcp-list-available-servers) | | Configure approval policies for platform tools | [Agent tools — approval flow](/managed-agents/delegation-approvals/using-tools#tool-execution-policy) | | Browse all LLM API endpoints | [LLM API Reference](/api/conversations) | --- URL: https://docs.travila.ai/integrations # Integrations \{#integrations} An assistant needs access to the systems where work happens. Connect a user's account, expose your own business operations as tools, or send Travila events to your backend. Choose the workflow that matches the job. | I want to… | Guide | | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | Let an assistant read a calendar or work with a user's connected app | [Build a calendar assistant](/integrations/tools-connections/connected-apps) | | Let an agent read websites using a service account I already own | [Read a website with your own service account](/integrations/tools-connections/custom-mcp-servers) | | Let an agent interact with my application and ask before sensitive actions | [Use and approve tools](/managed-agents/delegation-approvals/using-tools) | | Add web search or another available tool | [Build a web-research assistant](/integrations/tools-connections) | | Update my backend when an assistant finishes work | [Update an order when a run finishes](/integrations/webhooks) | | Restore delivery after my receiver fails | [Recover a missing backend update](/integrations/webhooks/deliveries) | | Look up food records or holiday dates | [Build a food log or holiday-aware date picker](/integrations/data-providers) | For exact contracts, use the [connected-app](/api/connected-apps), [MCP-server](/api/mcp-servers) and [webhook](/api/webhooks) references. The [run-completed Event declaration](/api/events/u1u0sjgmch) describes its payload. Check the chosen guide's prerequisites and availability before connecting a service. Use the [Event catalog](/api/events) to compare lifecycles and find payload fields, examples and receiver verification guidance. --- URL: https://docs.travila.ai/integrations/tools-connections # Build an assistant that researches the web \{#give-your-agent-tools} Give your users an assistant that can look up current information and answer with sources. This recipe adds web research to an existing conversation using Travila's available Tavily tools, then checks that an answer came from a successful lookup. You need a working [text conversation](/managed-agents/conversations/quickstart), a backend API key, an authenticated application user, and Tavily enabled in your Travila catalog. Keep the key on your backend. Use the same user and conversation throughout the recipe. ## Choose the job your agent needs to do \{#start-here} Start here for web research. For a different job, follow its recipe: | Customer task | Recipe | | -------------------------------------------------------- | --------------------------------------------------------------------------------- | | Answer a question using current web information | Continue below | | Check the user's calendar or work in a connected app | [Connect an account](/integrations/tools-connections/connected-apps) | | Read a website using a service account you already own | [Connect your own MCP server](/integrations/tools-connections/custom-mcp-servers) | | Act in your application or ask before a sensitive change | [Use and approve tools](/managed-agents/delegation-approvals/using-tools) | | Recall a user's preferences in later conversations | [Build with memory](/managed-agents/memory-knowledge) | ## 1. Check that web search is available \{#discovering-available-tools} Find the server and inspect its tools before designing the assistant around them. A catalog entry alone does not prove that the service can answer a request now. ### Find the available search service \{#list-mcp-servers} Discover servers available in the authenticated scope; no body filters are supplied. [Request example: List available MCP servers](/api/conversations/mcp-list-available-servers#example-conversations-mcpListAvailableServers-request). 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. Find the [platform-provided Tavily service](/api/conversations/mcp-list-available-servers#overview) in the returned catalog and keep its server ID for the next step. If the server is absent or paused, stop this setup and resolve its availability with your operator. Use [your own registered server](/integrations/tools-connections/custom-mcp-servers) when you want to use your own vendor account. ### Inspect the tools you will use \{#list-tools} Call [`mcp-list-tools`](/api/conversations/mcp-list-tools) with [`servers`](/api/conversations/mcp-list-tools#request-field-servers) containing the selected `built-in:tavily` reference. Read the returned tool names, descriptions and input schemas. Choose the search or extraction tools needed for your assistant's job. Supply an explicit server list. Omitting it can discover unrelated registered servers; this operation does not infer a particular conversation's configuration. ## 2. Enable research for the conversation \{#platform-servers} For a conversation without an active agent profile, read its current settings through [conversation state](/api/conversations/get-conversation-state), add the selected server to that complete settings object, and submit it below. The update replaces the whole settings object: preserve the interrupt policy, generation limit, prompt variables and other choices the conversation still needs. The example is complete for a new conversation with no customized settings. For your existing conversation, replace `thread_abc123` with its key and include the settings you read along with the server selection. [Request example: Update conversation settings](/api/conversations/update-settings#example-cookbook-integrations-tools-connections-index-02-request). 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. Select only the discovered search tools this assistant needs, then test [the effective selection](/api/tools/selection#platform-servers) on the next turn. ## 3. Ask a question and check its sources \{#get-started} Send a question that needs a fresh lookup, such as “Find the latest official React release notes, summarize the changes relevant to building a chat interface, and include links.” Use your existing [send-message flow](/managed-agents/conversations/generation). Inspect the [tool-call record](/api/conversations/get-tool-call) and the returned answer. The useful result is a successful lookup followed by an answer that cites the retrieved sources. A selected server reference in [`generationContext.resolvedMcpServers`](/api/models/schema-1im79fphmq#response-field-resolvedmcpservers) is not evidence that discovery or a tool call succeeded. If no lookup occurred, do not label the answer as freshly researched. Treat retrieved pages as external content. Render text and links safely, and check that a cited source supports the claim before using the answer for an important decision. A search result does not authorize an action in another service. ### Isolate a failing lookup \{#calling-tools-directly} If the assistant cannot retrieve a page, test the discovered read-only tool through [`mcp-call-tool`](/api/conversations/mcp-call-tool). Supply its exact server ID, tool name and schema-valid arguments; [`argumentsJson`](/api/models/schema-1it6mqsqoo#request-field-argumentsjson) is a JSON object. Keep the returned [`requestId`](/api/conversations/mcp-call-tool#response-field-requestid) for correlation. Check the tool's result as well as the outer HTTP status. A direct call helps distinguish an unavailable service or bad input from the assistant choosing not to call it. It executes outside the conversation's approval flow, so use it only for an operation your backend has independently authorized. ## Keep each task focused \{#per-turn-servers} For a turn that needs a different selection, supply [`overrideMcpServers`](/api/conversations/send-message#request-field-overridemcpservers) on [`send-message`](/api/conversations/send-message) or [`send-message-sync`](/api/conversations/send-message-sync). Include the complete server list and its allow/block rules for that task: [a non-empty override replaces the inherited list](/api/tools/selection#per-turn-servers). ## Load tools only when the assistant asks for them \{#deferred-tools} A server with many tools adds every tool's full definition to each request the assistant makes. To hold them back until they are needed, set [`deferTools`](/api/models/schema-1hik90rmo1#request-field-defertools) to `true` on that server's reference: in the conversation's settings through [`update-settings`](/api/conversations/update-settings), for one turn in [`overrideMcpServers`](/api/conversations/send-message#request-field-overridemcpservers), or in an agent profile's [`mcpServers`](/api/models/schema-1hmbcecg1j#request-field-mcpservers), the list used while that profile is active. The assistant then starts the turn with one search tool, `tool_search`, in place of that server's tools. When it searches, the matching tools are added to its next step in the same turn, and it calls them under their own names with the same approval rules as any other tool. A tool it has called stays available on later turns while that call is still part of the conversation's context; a tool that was only found is searched for again. The server reference's allow and block rules still decide what a search can find, and a call to a tool that has not been found yet is refused with a message telling the assistant to search first. To confirm that a turn deferred, read the assistant messages in its reply: [`toolCalls`](/api/models/schema-1j3dcf7kvu#request-field-toolcalls) holds a `tool_search` call before the call to the tool it found. A search uses one generation of the turn. Set [`maxLoops`](/api/models/schema-ph6avse89k#request-field-maxloops) in the conversation's settings to at least 3, so the assistant can search, call the tool and then answer; with the default of 2 it can search but cannot call what it found. The limit is read from the conversation's settings wherever the server is deferred, including for one turn and in an agent profile, and a task that needs several searches or tool calls needs a higher [generation limit](/managed-agents/conversations/configuration#max-loops). Deferring pays off when a server has many tools and a task needs a few of them. For a server with only a handful, the extra search step can cost more than it saves. ## Add actions with approval \{#tool-approval-flow} When your research assistant also sends messages or changes records, add the relevant connected app or custom server and configure approval rules before offering those actions. The default requires no approvals. Match the actual discovered names or full server IDs, then test an approved call and a denied call. Follow [Use and approve tools](/managed-agents/delegation-approvals/using-tools) for the full pending-call, decision and recovery flow. An approval is about the displayed action and account; merely connecting an app does not approve everything it can do. ### Apply the approval rules for this agent and turn \{#policy-precedence} Put the approval rules on [the configuration that owns this task](/api/tool-execution/policies#policy-precedence). Test an approved and denied action for the actual profile and turn before enabling it for customers. ## Let the assistant work inside your application \{#client-tools} For a result such as opening a screen or looking up a record that only your backend can access, declare a client tool. Your application receives the call, validates and authorizes it, performs the action, and submits the result for that original call. Use the [client-tool recipe](/managed-agents/delegation-approvals/using-tools#client-side-tools) to build that round trip and recover interrupted responses. These tools need your execution handler; Travila does not perform the application action for you. ## Schedule a summary while the app is closed \{#schedule-without-client-tools} Send a weekly summary even when nobody has your app open. Your conversation may normally offer client tools such as opening a screen, but those actions need your application's execution handler. This recipe removes inherited client tools for the scheduled turn and preserves normal interactive behavior for the next turn. 1. Choose the conversation and summary message. Keep only connected-service tools that the unattended job can use; clearing client tools does not remove those tools or authorize their actions. 2. Follow the [scheduled-agent recipe](/core-platform/scheduling/build-scheduled-agents#step-3-drive-an-agent-turn-from-the-callback) to send the summary request from your backend worker. Include `overrideGenerationConfig: {"clearClientTools": true}` next to [`userMessage`](/api/conversations/send-message#request-field-usermessage) in that send request, and keep this turn setting with the saved summary task. Omit [`clientTools`](/api/models/schema-1h82h7ri5p#request-field-clienttools) or leave it empty. A nonempty replacement list wins over the clear directive. Put the directive on this turn, not on the stored conversation defaults or profile. 3. Follow the accepted run to its [generation outcome](/managed-agents/conversations/generation). The scheduled run has no inherited client-tool definitions, including when it waits behind another run. Connected-service calls still follow their normal execution and approval rules. The next interactive turn inherits the original client tools. For example, a conversation's normal client tool opens the account dashboard. Its Monday summary asks “Summarize last week's completed tasks” with the per-turn directive above. The summary does not ask the closed app to open a dashboard; a later interactive request can use that tool again. The directive changes tool selection, not earlier history or already completed actions. **What it does not do, and recovery:** an empty [`clientTools`](/api/models/schema-1h82h7ri5p#request-field-clienttools) list still inherits rather than clears, so send the directive above rather than an empty list. Clearing client tools does not remove connected-service tools or authorize their actions. If a run is already waiting for a client result, reconnect the original handler and reconcile that call before resending; changing a later turn's tools does not resolve an existing pending call. ## Continue building \{#related} * [Connected apps](/integrations/tools-connections/connected-apps): let the assistant use a customer's account. * [Custom MCP servers](/integrations/tools-connections/custom-mcp-servers): connect a service you operate or pay for. * [Conversation API reference](/api/conversations): exact tool discovery, invocation and configuration contracts. * [Agent profiles](/managed-agents/profiles-prompts): reuse the selected tools and instructions across conversations. MCP resource and prompt transport operations currently return empty responses and cannot supply content for this recipe. Their availability is documented in the reference: [list resources](/api/conversations/mcp-list-resources), [read resource](/api/conversations/mcp-read-resource), [list prompts](/api/conversations/mcp-list-prompts) and [get prompt](/api/conversations/mcp-get-prompt). Use [prompt fragments](/managed-agents/profiles-prompts/prompt-fragments) for reusable agent instructions. --- URL: https://docs.travila.ai/integrations/tools-connections/connected-apps # Let your assistant answer questions about a customer's calendar \{#connect-your-agent-to-third-party-apps} Build a “Connect calendar” button so a customer can ask your assistant what is on their schedule. The customer authorizes their account, your application confirms the connection, and the assistant uses that account's available tools in an ordinary conversation. This recipe uses the optional hosted [Pipedream Connect](https://pipedream.com/docs/connect/managed-auth/quickstart) integration. It needs Pipedream enabled by your Travila operator, Google Calendar in the available catalog, a backend API key, and an authenticated application user. For a service you control, use [your own MCP server](/integrations/tools-connections/custom-mcp-servers). ## Prepare the connection experience \{#what-you-dont-have-to-build} Your application builds the Connect button, opens a hosted authorization page, and shows the resulting account in its integration settings. Pipedream manages the third-party credentials; your application does not store or refresh them. Resolve `X-On-Behalf-Of` from the signed-in user's trusted application session for every request below. Use that same beneficiary for connection, confirmation and conversation. Never let an arbitrary body parameter choose whose calendar a request can access. Keep “connected” distinct from “approved to act.” Reading a calendar and creating an event are different customer decisions. This recipe starts with answering a calendar question; add event creation only after designing its [approval experience](/managed-agents/delegation-approvals/using-tools). ## 1. Offer the calendar connection \{#connecting-an-account} Use catalog discovery to confirm that the integration is available. If it is not, leave the feature unavailable in your UI rather than sending the customer into a broken connect flow. ### Find Google Calendar in the catalog \{#1-show-the-user-what-they-can-connect} [Request example: List connectable apps](/api/connected-apps/pipedream-list-apps#example-cookbook-integrations-tools-connections-connected-apps-01-request). 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. A matching result provides the name and image for your Connect button and [`nameSlug`](/api/models/schema-oti80oaqc4#response-field-nameslug) for subsequent requests: [Response example: List connectable apps](/api/connected-apps/pipedream-list-apps#example-cookbook-integrations-tools-connections-connected-apps-json-01-response). Example identifiers and values are illustrative; substitute authorized values. Keep `google_calendar`, the returned slug, with the selected app. For a broader integration picker, use [categories](/api/connected-apps/pipedream-list-app-categories) and [app details](/api/connected-apps/pipedream-retrieve-app). Paginate catalog results with [`pageInfo.endCursor`](/api/models/schema-ohepdcsvjo#response-field-endcursor) as [`after`](/api/connected-apps/pipedream-list-apps#request-field-after); an empty [`data`](/api/connected-apps/pipedream-list-apps#response-field-data) page ends the list. ### Create the authorization link when the customer clicks Connect \{#2-create-a-connect-link} [Request example: Start connecting an app](/api/connected-apps/pipedream-create-connect-token#example-cookbook-integrations-tools-connections-connected-apps-02-request). 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. Open the returned [`connectLinkUrl`](/api/connected-apps/pipedream-create-connect-token#response-field-connectlinkurl) unchanged: [Response example: Start connecting an app](/api/connected-apps/pipedream-create-connect-token#example-cookbook-integrations-tools-connections-connected-apps-json-02-response). Example identifiers and values are illustrative; substitute authorized values. Create a fresh link for this attempt. Do not assume it is single-use; read [`expiresAt`](/api/connected-apps/pipedream-create-connect-token#response-field-expiresat) instead of assuming a fixed lifetime. Include [`appSlug`](/api/connected-apps/pipedream-create-connect-token#request-field-appslug) so the hosted page knows which app to connect. Bind your application's attempt record to the signed-in session and compare the returned [`state`](/api/connected-apps/pipedream-create-connect-token#request-field-state) with that record. The platform returns [`state`](/api/connected-apps/pipedream-create-connect-token#request-field-state) unchanged; it is not a secret or proof of authorization. For an embedded Connect page, use the [connect-token reference](/api/connected-apps/pipedream-create-connect-token) and specify the exact allowed framing origins. ### Confirm the account before showing Connected \{#3-confirm-the-connection-landed} After the customer returns, read their accounts: [Request example: List the caller's connected accounts](/api/connected-apps/pipedream-list-accounts-for-current-user#example-cookbook-integrations-tools-connections-connected-apps-03-request). 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. [Response example: List the caller's connected accounts](/api/connected-apps/pipedream-list-accounts-for-current-user#example-cookbook-integrations-tools-connections-connected-apps-json-03-response). Example identifiers and values are illustrative; substitute authorized values. Find the intended account and require `healthy: true` before showing it as usable. An absent [`healthy`](/api/models/schema-1fd4ce3lnc#response-field-healthy) field means false. A redirect alone does not prove that authorization completed. Save the returned account ID and display its account name so the customer can recognize the calendar. If no healthy account exists, show a retry of the Connect flow instead of claiming success. ## 2. Give this conversation access to the calendar \{#giving-the-model-a-connected-apps-tools} Create a thread for the same application user with the connected app selected: [Request example: Create a new conversation thread](/api/conversations/create-thread#example-cookbook-integrations-tools-connections-connected-apps-04-request). 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. Retain the returned conversation key. For an existing thread, use [update-settings](/api/conversations/update-settings). Tool discovery happens on later turns, so completing a connection does not require recreating a thread. An active [agent profile](/managed-agents/conversations/configuration#agent-profiles) replaces the conversation's MCP server list, even with an empty profile list. Put the calendar selection on the profile when you use one. ### Start with the actions this feature needs \{#narrowing-what-the-model-can-reach} Inspect the tools returned by [tool discovery](/api/conversations/mcp-list-tools) for `pipedream:google_calendar`. Select the actual read tools needed to answer schedule questions using [`allowlistToolPatterns`](/api/models/schema-1hik90rmo1#request-field-allowlisttoolpatterns). An empty allowlist allows all app tools, and [`blocklistToolPatterns`](/api/models/schema-1hik90rmo1#request-field-blocklisttoolpatterns) takes precedence. Do not infer read-only behavior from a friendly tool description alone. Set approval rules before testing tools that create or change events. Exact tool names and account inputs can vary with the configured integration; discovery supplies the contract your application should use. Follow [Use and approve tools](/managed-agents/delegation-approvals/using-tools) to display a proposed action and resolve its original pending call. ## 3. Ask about the schedule and inspect the result \{#what-a-tool-call-looks-like} Send “What is on my calendar today?” using your normal [message flow](/managed-agents/conversations/generation). Keep the selected account visible in your application's conversation or integration settings. Inspect the [tool-call record](/api/conversations/get-tool-call) as well as the assistant's answer. A completed recipe has a successful calendar lookup against the intended account and an answer based on that result. [If the tool reports an unavailable account, invalid input or authorization link](/api/connected-apps/account-selection#connected-apps-what-a-tool-call-looks-like), show that next step instead of an empty schedule. ## Let the customer choose between work and personal accounts \{#when-a-user-has-more-than-one-account} Run Connect again to add the other account, then use [the discovered tool’s account selector](/api/connected-apps/account-selection#connected-apps-when-a-user-has-more-than-one-account) when the customer chooses which calendar to read. Show which account an action will use. If the customer's request is ambiguous, ask them to choose before acting. Invalid or missing required account selection is rejected, but a model instruction to choose correctly does not replace your application's approval experience. ### Offer account management from the conversation \{#the-account-meta-tools} The integration also exposes `pd_list_accounts` and `pd_connect_account`, so an assistant can answer which accounts are connected or obtain a link for another account. Your app should still [confirm the resulting account](/api/connected-apps/account-selection#connected-apps-the-account-meta-tools) before reporting success. ## Recover when access expires during a conversation \{#choosing-when-the-user-connects} Use the same application-driven Connect flow for a revoked or unhealthy account. Pause the dependent feature in your UI, let the user reconnect, confirm a healthy account, and then let them continue the task. ### Recognize a connection request inside a tool result \{#what-an-unconnected-app-does} Treat [a returned connection request](/api/connected-apps/account-selection#connected-apps-what-an-unconnected-app-does) as a setup step. Confirm a working calendar lookup before showing the customer that the requested action completed. Inspect the tool result in the returned messages or [conversation state](/api/conversations/get-conversation-state). If it contains a Connect URL, present a connection action rather than reporting a successful lookup. Never rewrite a returned Connect URL. Validate a URL before opening it: require the expected HTTPS origin and path, expected parameters, no embedded credentials or fragment, and association with the current authenticated Connect attempt. A model-generated URL or matching text prefix is not enough. ### Keep connection recovery in your application \{#option-1--connect-first-then-wire-the-tools} The recommended path is the same as initial setup: create a fresh link for the selected app, open it, and confirm the account with a fresh lookup. This gives the customer a clear account choice and your application an observable result. If the original calendar call may have changed something before failing, inspect the original call and the calendar before trying again. Reconnecting an account does not establish that an earlier action had no effect. ### Optional: show the connection action through a client tool \{#option-2--hand-the-link-back-with-a-client-tool} You can declare a [client tool](/managed-agents/delegation-approvals/using-tools#client-side-tools) that carries a Connect URL into your UI. Your application [validates and opens the URL](/api/connected-apps/account-selection#connected-apps-option-2--hand-the-link-back-with-a-client-tool), confirms the intended healthy account, and submits a truthful result for the original client-tool call. A tool description cannot guarantee that the model forwards a link or calls the calendar again. Keep the application-driven flow available, and inspect the run outcome after submitting the client-tool result rather than promising automatic completion. ## Offer Disconnect and account deletion \{#managing-connections} Keep connection management reachable after setup. Customers need to see unhealthy connections and withdraw access without starting a conversation. ### Repair an unhealthy account \{#health} Read [list-accounts](/api/connected-apps/pipedream-list-accounts-for-current-user) for the current user and app. An absent or false [`healthy`](/api/models/schema-1fd4ce3lnc#response-field-healthy) value with an error identifies an unusable connection. There is no repair operation; run Connect again and confirm the resulting account. ### Disconnect the selected calendar \{#disconnecting-one-app} Use the ID shown on the customer's connection screen: [Request example: Disconnect one account](/api/connected-apps/pipedream-delete-account-for-current-user#example-cookbook-integrations-tools-connections-connected-apps-05-request). 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. Read the account list again to confirm removal and stop selecting that account for new work. An account ID belonging to another user is returned as not found. Disconnecting cannot undo an already dispatched provider action; inspect pending work before reporting that all activity stopped. ### Remove integration data when the customer leaves \{#offboarding-a-user-entirely} For an application user who is deleting their account, remove all their Pipedream connections under that same authenticated beneficiary: [Response example: Delete the caller's integration data entirely](/api/connected-apps/pipedream-delete-external-user-for-current-user#example-cookbook-integrations-tools-connections-connected-apps-json-04-response). Example identifiers and values are illustrative; substitute authorized values. Verify the intended user’s connections are gone and retain unresolved external actions for follow-up. [Removing these connections is irreversible](/api/connected-apps/pipedream-delete-external-user-for-current-user#overview). ## Extend the feature beyond available tools \{#calling-an-apps-api-directly} If a required operation is missing from the discovered tools, use the [connected-account proxy](/api/connected-apps/pipedream-proxy-for-current-user) to call a supported API on that app's domains with the user's own [`accountId`](/api/connected-apps/pipedream-proxy-for-current-user#request-field-accountid). Your backend must authorize the specific operation; it does not pass through conversational tool approvals. Check the upstream result before confirming the action. Use [the response’s declared format](/api/connected-apps/pipedream-proxy-for-current-user#overview) and a supported provider download flow for large results. ## Next recipes and reference \{#related} * [Use and approve tools](/managed-agents/delegation-approvals/using-tools): authorize changes before the assistant makes them. * [Build an assistant that researches the web](/integrations/tools-connections): add public information to its answers. * [Connected apps API reference](/api/connected-apps): exact catalog, connection and proxy contracts. --- URL: https://docs.travila.ai/integrations/tools-connections/features/custom-mcp-servers # Use your own services in an assistant \{#custom-mcp-servers} Your assistant needs information from a service you already run or pay for. Connect that service through a supported MCP server so Travila can call its selected tools during the conversation. Keep its credential in the secret store and put only the secret's name in the server configuration. For a complete example, [build an assistant that reads a website using your Firecrawl account](/integrations/tools-connections/custom-mcp-servers). The same registration pattern works for a compatible server exposing your own application operations. ## Take a question from setup to a verified answer \{#setup} 1. Choose a question your service can answer and a test record or page you can inspect yourself. 2. Store the service credential and register its public HTTPS MCP endpoint. 3. Test the saved connection and inspect the returned tools. Select only those needed for the task. 4. Enable the server for the intended conversation or agent, then ask the test question. 5. Inspect the actual tool result and check the answer against your source. The finished integration produces a supported answer from the selected service. Registration or a successful connection test alone is not the finished customer experience. Follow the [worked recipe](/integrations/tools-connections/custom-mcp-servers) for requests and recovery steps. ## Choose the right connection for your application \{#scope-and-current-limitations} A custom MCP server must be publicly reachable over HTTPS with a supported MCP-over-HTTP transport. If only your application can reach the system, use a [client tool](/managed-agents/delegation-approvals/using-tools#client-side-tools) instead. Current public configuration uses the tenant's `default` project. A different project identifier does not create a separate test environment or customer boundary; use a separately provisioned tenant where separation is required. Choose a service you trust with the task's arguments and a credential limited to the intended work. Configure [tool approval](/managed-agents/delegation-approvals/using-tools) before offering sensitive changes. Being able to connect to a service does not grant permission for every action it exposes. ## Maintain the connection after launch \{#available-operations} When the service changes or a credential expires, use the [maintenance steps](/integrations/tools-connections/custom-mcp-servers#managing-servers) to inspect dependencies, update the full saved configuration and verify another real call. For urgent revocation, revoke the credential at its issuer; a configuration update does not recall calls already in progress. Exact fields and limits belong in the [custom server reference](/api/mcp-servers) and [secret reference](/api/secrets). Use them when you need the full request and response fields for a maintenance operation. ## Continue building \{#related} * [Read a website using your own account](/integrations/tools-connections/custom-mcp-servers) * [Let a customer connect their calendar](/integrations/tools-connections/connected-apps) * [Approve an agent's proposed action](/managed-agents/delegation-approvals/using-tools) When reporting feedback, use the document and section IDs displayed on this page. --- URL: https://docs.travila.ai/integrations/tools-connections/custom-mcp-servers # Answer questions about a website using your own Firecrawl account \{#bring-your-own-mcp-server} Let a customer ask your assistant to read a public page and explain what it says. This recipe uses a Firecrawl account you already own: store its credential, register its MCP endpoint, test discovery, and use it in a conversation. The same connection pattern applies to a compatible MCP server for a service you operate. If you want Travila's available web tools without a separate vendor account, use the [web-research recipe](/integrations/tools-connections). If the action must run inside your application or private network, use a [client tool](/managed-agents/delegation-approvals/using-tools#client-side-tools). ## Prepare a test question and account \{#what-you-need} You need a Firecrawl credential permitted to read the chosen public site, a backend Travila key, a test application user and an existing conversation. Choose a page you can inspect yourself and a question whose answer appears on it. This lets you check the final answer against the source. Follow [Firecrawl’s API-key MCP setup](https://docs.firecrawl.dev/mcp-server) for the vendor endpoint and bearer credential used below. The server must offer Streamable HTTP at a publicly reachable HTTPS endpoint. Travila cannot launch a local process or dial your private-network endpoint for this recipe. Custom-server configuration currently belongs to the tenant's `default` project; a supplied `X-Project-Id` does not create project or test/live isolation. Use an isolated tenant for testing when required. ## 1. Store the Firecrawl credential \{#store-the-credential} Run this from your backend, replacing the placeholder with your credential: [Request example: Create or update a secret](/api/secrets/put-secret#example-cookbook-integrations-tools-connections-custom-mcp-servers-01-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. The response contains metadata, not the stored value. Keep the name `firecrawl-api-key` for the next step. Registration rejects a reference to a secret that does not exist. Only your trusted backend should hold this Travila key: current secret APIs do not restrict a key to one named secret, so a key that can use them can overwrite or delete other project credentials. Keep the Firecrawl credential out of agent instructions and public endpoint URLs. ## 2. Register the service you want Travila to call \{#register-the-server} [Request example: Register a custom MCP server](/api/mcp-servers/create-custom-mcp-server#example-cookbook-integrations-tools-connections-custom-mcp-servers-02-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. Keep the returned server ID, `firecrawl`. Configuration calls use this bare ID and a backend key without `X-On-Behalf-Of`. Later conversation calls use `custom:firecrawl` and the authenticated application user. The saved record contains [`authSecretRef`](/api/models/schema-p1cuh9jgfq#request-field-authsecretref), not the credential. Confirm the endpoint and enabled state in the response before continuing. Registration alone does not give every agent access to this server. ### Adapt the connection for another service \{#authentication-modes} Match the service's documented authentication method when adapting this recipe. The [create-server reference](/api/mcp-servers/create-custom-mcp-server) describes bearer, named-header, query-parameter and no-auth modes and their required fields. An omitted authentication mode is rejected. For a provider that requires a key in a query parameter, store the value as a secret and configure the parameter name through query authentication. Do not put the value in the saved endpoint URL: get/list return that URL. Restrict access to diagnostic errors too; provider errors may echo credentials in forms that are not fully sanitized. ### Connect only a server intended for this customer task \{#egress-guard} Use a public HTTPS service you trust with the tool arguments it will receive. Private, loopback and local-only destinations are rejected, and cross-host redirects are not followed. See the [server reference](/api/mcp-servers/create-custom-mcp-server) for accepted configuration. A successful connection does not make a server suitable for customer data. In particular, an administrative tool connected with developer-wide credentials may expose more than the user's task requires. Give this integration a credential and tool selection appropriate to the data it will read. ## 3. Check the saved connection and choose its tools \{#test-it-before-you-rely-on-it} [Request example: Test a custom MCP server connection](/api/mcp-servers/test-custom-mcp-server-connection#example-cookbook-integrations-tools-connections-custom-mcp-servers-03-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. A successful test reports the discovered tool count: [Response example: Test a custom MCP server connection](/api/mcp-servers/test-custom-mcp-server-connection#example-cookbook-integrations-tools-connections-custom-mcp-servers-json-01-response). Example identifiers and values are illustrative; substitute authorized values. Inspect [whether the connection test actually succeeded](/api/mcp-servers/test-custom-mcp-server-connection#overview). Fix the endpoint, credential or network problem before asking the assistant to repeat the whole research task. ### Inspect the names before setting filters or approvals \{#tool-names-are-not-namespaced} [Request example: List available MCP tools](/api/conversations/mcp-list-tools#example-cookbook-integrations-tools-connections-custom-mcp-servers-04-request). 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. Choose the tools needed to read the test page using the returned names and input schemas. The server ID is `custom:firecrawl`; tool names are whatever the server advertises. Do not prepend that server ID to a tool name when creating allow/block or approval patterns. Select tools with distinct names when using multiple servers; registration does not reject duplicate tool names across servers. A successful connection test establishes discovery, not authorization for every tool it offers. ## 4. Ask about the page in a conversation \{#give-it-to-the-model} Use the server for a single turn with [`overrideMcpServers`](/api/conversations/send-message#request-field-overridemcpservers). Replace the conversation key and page URL with your test values: [Request example: Send a message to a conversation](/api/conversations/send-message#example-cookbook-integrations-tools-connections-custom-mcp-servers-05-request). 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. The prompt is an illustrative customer task, not a promise that a page's content or pricing remains unchanged. The assistant chooses from the selected server's discovered tools. Use your chosen tool names in [`allowlistToolPatterns`](/api/models/schema-1hik90rmo1#request-field-allowlisttoolpatterns) when restricting the task; a non-empty server override replaces inherited server selections and their filters. Read the run outcome and [tool-call record](/api/conversations/get-tool-call), then compare the answer with the page. The recipe is complete when a successful read from the intended server supports the answer. If the page could not be fetched, show that failure rather than presenting the assistant's recollection as retrieved content. For repeated use, add the server to the appropriate [agent profile](/managed-agents/profiles-prompts) or conversation settings. Configure [approval rules](/managed-agents/delegation-approvals/using-tools) before exposing tools that perform sensitive actions. ## Keep the integration working \{#managing-servers} Use these maintenance steps when the website-reading feature is already in use. Inspect saved configuration with [get-server](/api/mcp-servers/get-custom-mcp-server), and use [list-servers](/api/mcp-servers/list-custom-mcp-servers) with [`authSecretNameFilter`](/api/mcp-servers/list-custom-mcp-servers#request-field-authsecretnamefilter) to find every server depending on a credential. Include disabled servers when checking that dependency list. ### Move or change the server \{#updating-is-a-full-replace} Read the saved definition, apply the intended change to [that complete record](/api/mcp-servers/update-custom-mcp-server#overview), then submit it through [update-server](/api/mcp-servers/update-custom-mcp-server). Read the record again and test the connection. A saved version confirms the configuration update, but it does not establish that every call has adopted it or cancel calls already in progress. ### Rotate the credential \{#rotating-a-credential} First find dependent servers. Then replace the named secret using the same name: [Request example: Create or update a secret](/api/secrets/put-secret#example-cookbook-integrations-tools-connections-custom-mcp-servers-06-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. Inspect [secret metadata](/api/secrets/get-secret-metadata) and test the connection. Metadata alone cannot prove the stored value after a partially failed write. A successful connection shows that this test was accepted; the API does not report when all calls have switched credentials. Coordinate the cutover with your operator before retiring the old credential at Firecrawl. Updating the stored value does not revoke the old one at its issuer. For urgent revocation, revoke at the issuer and account for the resulting interruptions. ### Stop using the service \{#disabling-vs-deleting} Remove dependent conversation/profile references when retiring the feature. To keep the configuration for later, update the complete server record with `enabled: false`. To remove it, call [delete-server](/api/mcp-servers/delete-custom-mcp-server). After deletion is observed, new resolution fails. Neither disabling nor deleting recalls an in-flight call or definitions already loaded for it. Deleting a server leaves the referenced secret in place. ### Retire the unused credential \{#retiring-a-credential} Check the server dependency list before [deleting the secret](/api/secrets/delete-secret). A still-referenced secret returns 409 by default. Update or remove those references first; forced deletion intentionally leaves dependent servers unable to authenticate. Confirm that the obsolete credential is also revoked at its issuer. Deleting Travila's copy does not invalidate a credential held elsewhere. ## Plan for slow or unavailable pages \{#limits} Choose [a supported request timeout](/api/models/schema-p1cuh9jgfq#overview) that fits how long the customer can wait for the page. Keep an unavailable lookup visible instead of promising a completed research answer. If the feature stops working, test the connection, inspect the original call and distinguish authentication failure from a page-specific failure. Do not repeatedly rerun the entire customer task to diagnose it. ## Next recipes and reference \{#related} * [Approve tools before they change data](/managed-agents/delegation-approvals/using-tools) * [Connect a customer's calendar](/integrations/tools-connections/connected-apps) * [Custom MCP server API reference](/api/mcp-servers) * [Project secret API reference](/api/secrets) --- URL: https://docs.travila.ai/integrations/webhooks # Update your backend when an assistant finishes \{#react-to-platform-events-in-your-backend} Your application has asked an assistant to draft an order summary. The customer can leave the screen while it works; your backend still needs to record whether the run finished and make its result available. Use a webhook to receive that update without keeping the customer's browser connected. Travila delivers the event to your receiver. Your application owns the order record and decides what to do with the completed result. ## Build the completion workflow \{#start-here} 1. Create a backend receiver that verifies and durably accepts incoming events. 2. Register its URL and subscribe to `llm.generation_completed`. 3. Start an ordinary assistant run and save its run ID with the order in your application. 4. On a matching completion event, inspect the run's outcome before marking the order summary ready. 5. Confirm both the delivery and your application's update. A successful delivery alone does not prove that your worker completed its work. Follow [the receiver setup recipe](/integrations/webhooks/endpoints) for these steps. If an update is missing, use [the recovery recipe](/integrations/webhooks/deliveries). ## Prepare the receiving service \{#how-it-works} You need an HTTPS URL your backend controls, a backend API key, and an existing conversation that can produce a run. Webhook configuration belongs to the tenant and uses a secret API key without `X-On-Behalf-Of`. Keep that key and the endpoint's signing secret out of browser code. Configure your receiver before starting customer work. An endpoint receives nothing until it has a subscription, and events produced before that subscription are not a historical backfill. ## Choose the event for your application result \{#event-types} For the order-summary workflow, select `llm.generation_completed`. Completion includes unsuccessful outcomes; read the event's status before showing the summary as ready. | A different application need | Event to evaluate | | ------------------------------------------------------------ | -------------------------------------------------- | | Add each new conversation message to your application's view | `llm.message_published` | | Show that a run began | `llm.generation_started` | | Observe a tool being dispatched or completing | `llm.tool_call_started`, `llm.tool_call_completed` | A new-message event and a run-completed event can concern the same turn. Assign each a distinct job so they do not trigger the same business action twice. Pending approvals currently require [the approval lookup flow](/managed-agents/delegation-approvals/using-tools); `llm.tool_call_approval_required` is not delivered as a webhook. The [run-completed Event declaration](/api/events/u1u0sjgmch) describes its payload. Other selected Event declarations appear in the API navigation. For updates to an open conversation screen, see [streaming availability](/managed-agents/conversations/streaming). Use the [Event catalog](/api/events) to compare lifecycles and find payload fields, examples and receiver verification guidance. ## Keep the workflow working as your app changes \{#concepts} Save the endpoint and subscription identities with your application's webhook configuration. There is one live subscription per endpoint. To change its event selection, replace the subscription; the gap does not receive events. If you need continuity, plan an overlap using a separate endpoint and deduplicate shared events before cutting over. Use [delivery history](/integrations/webhooks/deliveries) to recover retained failed deliveries. Neither changing a subscription nor re-enabling a receiver proves that missed events have replayed. ## Next recipes and reference \{#related} * [Receive and process the first completion event](/integrations/webhooks/endpoints) * [Recover a missing backend update](/integrations/webhooks/deliveries) * [Send a notification to a person](/core-platform/notifications) * [Webhook API reference](/api/webhooks) --- URL: https://docs.travila.ai/integrations/webhooks/endpoints # Receive a completed order summary in your backend \{#create-endpoints-and-subscriptions} Associate an assistant run with an order in your application, then update that order when the run finishes. Keep the run identifier with the order so your backend can reconcile the result. This recipe uses an application-owned receiver and worker, the endpoint/subscription APIs, and the declared generation lifecycle. Prepare an HTTPS receiver and a backend API credential. Keep endpoint credentials on the backend. Configure and verify the receiving integration before using it for order changes. ## 1. Register the receiver for completed runs \{#create-an-endpoint} Use [Create a webhook endpoint](/api/webhooks/create-webhook-endpoint) with your HTTPS receiving URL. Supply [`eventTypes`](/api/webhooks/create-webhook-endpoint#request-field-eventtypes) for the subscription you want to create, and retain the returned endpoint and subscription identifiers. An endpoint without an event selection needs a [subscription](/api/webhooks/create-webhook-subscription) before it can receive the configured events. ### Save the signing secret \{#list-endpoints} Store the endpoint [`secret`](/api/models/schema-1ffl20kv2k#response-field-secret) in your backend credential store. Use [List webhook endpoints](/api/webhooks/list-webhook-endpoints) to find your endpoint by its returned identifier. Keep the listing and credentials private; do not send them to application users. ## 2. Accept verified events before updating the order \{#verify-the-signature} Verify the incoming request with the endpoint secret and the [receiver signature procedure](/api/events#delivery-envelope). Preserve the original request bytes before parsing JSON. Reject an invalid signature, an unknown delivery format or an unexpected scope. Persist the authenticated event identity, payload digest and pending work before returning `2xx`. Acknowledge an identical duplicate without scheduling the order update again. If durable acceptance fails, return a non-success response so the delivery can be retried according to its configured policy. Use the run identifier to find the associated order and inspect the [generation completion fields](/api/models/schema-pntuu08p80#response). Mark a summary ready only for a successful outcome. Handle errors and context-compaction outcomes separately. Keep your application’s own operation identity for external effects; receipt deduplication alone does not make an order update happen exactly once. ## 3. Prove that the order reaches the right result \{#list-subscriptions} Use [List webhook subscriptions](/api/webhooks/list-webhook-subscriptions) to inspect the configured endpoint selection before testing. Inspect the subscription for the new endpoint before testing: Confirm that its [`eventTypes`](/api/webhooks/create-webhook-endpoint#request-field-eventtypes) includes `llm.generation_completed`. Start one ordinary assistant run, saving the returned run ID with a test order in your application. Check [delivery history](/integrations/webhooks/deliveries), then inspect your own order record. The completed recipe has a matching run outcome, a durably accepted event and the intended order update. Also send an identical delivery to your local handler test: it must not repeat the update. Test an unsuccessful run separately so your UI does not show a failed summary as ready. ## Change the receiver when your application moves \{#managing-endpoints} Use the following variations after the first completion workflow works. ### Move to a new receiving URL \{#update-an-endpoint} Use [Update a webhook endpoint](/api/webhooks/update-webhook-endpoint) for the replacement receiving URL after testing it. Deploy and test the new receiver, with its configured verification credentials and deduplication records, before changing the saved URL: Nonempty name, URL and description replace the corresponding stored values; empty strings do not clear fields. There is no public revision precondition, so concurrent changes can overwrite one another. Verify the receiving configuration before retiring the old receiver. ### Change which events the receiver handles \{#one-subscription-per-endpoint} Plan a deliberate cutover when changing event selection. Check the current subscription before [replacing it](/api/webhooks/create-webhook-subscription#overview) so the receiver’s gap or overlap is understood. For a cutover that needs overlap, create a separate endpoint with the new event selection, deduplicate authenticated events across both receivers, verify the new path, and retire the old subscription. A second subscription on the same endpoint is rejected. Events published in a replacement gap are not delivered to that endpoint. ### Use your deployment's own subscription name \{#addressing-a-subscription-with-your-own-id} Use [an application-owned subscription name](/api/webhooks/create-webhook-subscription#overview) when that makes deployment recovery clearer. Save the created subscription identity with the name. Deletion frees that name for reuse. Keep a record of which deployment the name currently identifies so recovery does not confuse an old subscription with its replacement. ### Retire this order-summary integration \{#delete-an-endpoint} Use [Delete a webhook endpoint](/api/webhooks/delete-webhook-endpoint) when retiring this integration. Stop assigning new work to this integration and inspect the delivery history you need to retain. Then delete the endpoint: Deleting the endpoint removes it and its associated provider subscriptions. Already dispatched deliveries can still reach the receiver; deletion does not establish erasure of historical deliveries or backups. Keep any application work already accepted by your receiver under your own cleanup and reconciliation process. ### Event catalog \{#receiver-event-catalog} See [Event catalog](/api/events#event-catalog) in the event catalog for the delivery contract and payload reference. Continue with [verifying the subscription outcome](#list-subscriptions) for this receiver recipe. #### Webhook events \{#receiver-webhook-events} See [Webhook events](/api/events#webhook-events) in the event catalog for the delivery contract and payload reference. Continue with [verifying the subscription outcome](#list-subscriptions) for this receiver recipe. #### Delivery envelope \{#receiver-delivery-envelope} See [Delivery envelope](/api/events#delivery-envelope) in the event catalog for the delivery contract and payload reference. Continue with [verifying the subscription outcome](#list-subscriptions) for this receiver recipe. #### Event types \{#receiver-event-types} See [Event types](/api/events#event-types) in the event catalog for the delivery contract and payload reference. Continue with [verifying the subscription outcome](#list-subscriptions) for this receiver recipe. #### Payload shapes \{#receiver-payload-shapes} See [Payload shapes](/api/events#payload-shapes) in the event catalog for the delivery contract and payload reference. Continue with [verifying the subscription outcome](#list-subscriptions) for this receiver recipe. #### llm.message\_published \{#receiver-llmmessage\_published} See [llm.message\_published](/api/events#llmmessage_published) in the event catalog for the delivery contract and payload reference. Continue with [verifying the subscription outcome](#list-subscriptions) for this receiver recipe. #### llm.generation\_started \{#receiver-llmgeneration\_started} See [llm.generation\_started](/api/events#llmgeneration_started) in the event catalog for the delivery contract and payload reference. Continue with [verifying the subscription outcome](#list-subscriptions) for this receiver recipe. #### llm.generation\_completed \{#receiver-llmgeneration\_completed} See [llm.generation\_completed](/api/events#llmgeneration_completed) in the event catalog for the delivery contract and payload reference. Continue with [verifying the subscription outcome](#list-subscriptions) for this receiver recipe. #### Values of status \{#receiver-llm-generation-completed-values-status} See [Values of status](/api/events#llm-generation-completed-values-status) in the event catalog for the delivery contract and payload reference. Continue with [verifying the subscription outcome](#list-subscriptions) for this receiver recipe. #### llm.tool\_call\_started \{#receiver-llmtool\_call\_started} See [llm.tool\_call\_started](/api/events#llmtool_call_started) in the event catalog for the delivery contract and payload reference. Continue with [verifying the subscription outcome](#list-subscriptions) for this receiver recipe. #### llm.tool\_call\_completed \{#receiver-llmtool\_call\_completed} See [llm.tool\_call\_completed](/api/events#llmtool_call_completed) in the event catalog for the delivery contract and payload reference. Continue with [verifying the subscription outcome](#list-subscriptions) for this receiver recipe. #### Approval waits \{#receiver-llmtool\_call\_approval\_required} See [Approval waits](/api/events#llmtool_call_approval_required) in the event catalog for the delivery contract and payload reference. Continue with [verifying the subscription outcome](#list-subscriptions) for this receiver recipe. #### Conversation updates \{#receiver-conversation-updates} See [Conversation updates](/api/events#conversation-updates) in the event catalog for the delivery contract and payload reference. Continue with [verifying the subscription outcome](#list-subscriptions) for this receiver recipe. --- URL: https://docs.travila.ai/integrations/webhooks/deliveries # Recover a missing backend update \{#monitor-and-retry-deliveries} An assistant has finished an order summary, but your application still shows it as processing. Trace the original run through webhook delivery and your own worker before starting more work. This recipe recovers a retained failed delivery after repairing the receiver. You need the run or event identity from the affected work, your endpoint ID, a backend API key, and access to your receiver's logs and saved events. Use an isolated test order when practicing the flow. ## 1. Find where the update stopped \{#deliveries} Start with the delivery records for your endpoint and the time of the missing update. This example selects failed deliveries; remove or change [`status`](/api/webhooks/list-webhook-deliveries#request-field-status) when you need to inspect other outcomes: [Request example: List webhook event deliveries](/api/webhooks/list-webhook-deliveries#example-cookbook-integrations-webhooks-deliveries-01-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. Use [`eventId`](/api/webhooks/list-webhook-deliveries#request-field-eventid) when you know the exact event, and paginate the results. The [list-deliveries reference](/api/webhooks/list-webhook-deliveries) describes the available filters. Retained records do not form a complete audit of every HTTP attempt. | What you find | Next step | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `SCHEDULED` or `PROCESSING` | Check again for the same delivery; it has not reached a confirmed terminal result. | | `RETRY` | Inspect the receiver failure and repair it while automatic retry is pending. | | `FAILED` | Repair the receiver, then assess a manual retry of this retained delivery. | | `COMPLETED` | Your receiver accepted it. Inspect the queued work and order update in your application. | | `DISCARDED` | Inspect retained history before concluding whether an earlier attempt occurred. | | No matching delivery | Check the original run, event selection and subscription timing. Absence from retained history does not establish that the run never completed. | The API prefixes the displayed states with `DELIVERY_STATUS_`. A `COMPLETED` delivery confirms HTTP acceptance, not successful execution of your background worker. ## 2. Repair the receiver \{#receiving-webhooks} Use the failure to choose the repair. Restore reachability for connection errors, correct signature verification for rejected authentic deliveries, or restore durable event storage when your receiver could not accept work. Before replaying customer work, verify that your handler recognizes an already accepted event and that your worker checks the existing order update before repeating an external action. If the receiver accepted the event but its worker stopped, recover that saved work in your application; sending another webhook is not the first recovery step. For out-of-order arrivals, use a documented resource version or sequence when available, or read current resource state. Arrival time alone cannot tell you which update wins. ### Check whether the endpoint is still active \{#auto-disable-on-sustained-failure} Inspect the [saved endpoint](/api/webhooks/list-webhook-endpoints). If it is inactive, repair the receiver before re-enabling it with [update-endpoint](/api/webhooks/update-webhook-endpoint). Automatic disabling is deployment-dependent; a failed delivery does not prove that disabling happened. Re-enabling permits later delivery. It does not prove that failed or discarded work replayed, so continue with the original retained records. ### Understand the retry window \{#retry-configuration} Inspect the subscription's [`retryConfig`](/api/models/schema-1fn66l17fv#response-field-retryconfig) through [list-subscriptions](/api/webhooks/list-webhook-subscriptions). It records the requested strategy, count and base interval. Confirm the deployment's effective timing, counting and retention policy with your operator when planning how long an outage can be recovered. Do not assume that every old event remains eligible for replay or that the configured interval promises an exact attempt time. ## 3. Replay the original eligible delivery \{#retrying} After repair, request a retry using its original delivery ID: [Request example: Retry a failed webhook delivery](/api/webhooks/retry-webhook-delivery#example-cookbook-integrations-webhooks-deliveries-02-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. Inspect the returned outcome and then [read the delivery again](/api/webhooks/list-webhook-deliveries). Do not create a new assistant run to compensate for a delivery problem: that can duplicate the work the first run already performed. Finally, check the application record. Recovery is complete when the intended order update is present and the original event has been handled without repeating its business action. If replay eligibility or retention prevents recovery, reconcile the original run and saved application work instead of treating a new run as a retry. --- URL: https://docs.travila.ai/integrations/data-providers # Build a food log and a holiday-aware date picker \{#use-external-reference-data-in-your-application} Help customers complete a task without manually searching another site. A food log can retrieve a product's nutrient record; a date picker can show public holidays beside candidate dates. These recipes use the data tools enabled for your Travila deployment. Your application owns the food entry or appointment being created. ## Prepare the lookup for the feature you are building \{#choose-and-verify-a-result} Use [tool discovery](/integrations/tools-connections#discovering-available-tools) to find the enabled source and inspect its input schema. Confirm that it supports the country, food type or date range your feature needs before offering the lookup to customers. Keep the provider's returned identity with a selected result. This lets your application reopen the original record or explain which source was used when the customer corrects an entry. A tool lookup retrieves reference data; it does not save a food log or book an appointment for you. ## Let a customer log a food without retyping its label \{#food-and-nutrient-records} Build the interaction around choosing the right food and serving: 1. Ask the customer to search for a food or enter a packaged product's barcode. The current tools support unified nutrition search, USDA search/detail/batch/list, and Open Food Facts search or barcode lookup. 2. Show recognizable candidates with their source and product or preparation details. For a USDA result, use its FDC ID to retrieve the selected record. For a packaged product, retain its barcode identity. These are different identifiers and cannot be substituted for one another. 3. Show the record's serving basis beside the amount the customer logs. Compare nutrient amounts only on a common basis, such as per 100 g or per labeled serving. Do not silently compare one product's serving with another's 100 g value. 4. Save the chosen source record, serving basis and available nutrient values with the food entry in your application. Display missing values as unavailable, so an absent nutrient is not presented as zero. 5. Let the customer review and correct the selection before relying on the entry. A successful result is a recognizable food with an explicit amount and source, not merely the first search hit. Search results can be abridged; a detail lookup may be necessary before showing a complete entry. A batch can omit unavailable records. Scores from USDA and Open Food Facts are not directly comparable, so do not use a mixed score to claim one result is the best match. Use [USDA's data documentation](https://fdc.nal.usda.gov/data-documentation/) and [Open Food Facts' API documentation](https://openfoodfacts.github.io/openfoodfacts-server/api/) to interpret source formats and evidence. Reference data does not certify the contents or allergy safety of the physical product the customer has. Keep the actual label and customer correction available in the food-log experience. ## Show public holidays while a customer chooses a date \{#holiday-calendars} Add a holiday hint to a scheduling screen so customers can notice a date they may want to avoid: 1. Let the customer select the relevant country and, where supported, subdivision. Use the year of the dates they are considering. 2. Request the applicable holiday lookup through the discovered tool. Check the [supported calendar coverage](https://holidays.readthedocs.io/en/latest/) against the version enabled by your operator. 3. Show returned holiday names beside the matching dates, with the selected region visible. Leave the appointment choice with the customer: a public holiday does not establish whether their workplace is closed or whether they personally observe it. 4. Keep an unavailable state in the date picker. The current lookup can return empty or false when its provider fails, so an empty result cannot reliably certify that a date has no holiday. Confirm important dates against the relevant official calendar. The completed feature helps the customer choose a date with context. It should not label a day “guaranteed working day” or automatically book an appointment based on an empty holiday result. Future dates may change with official announcements. ## Let the customer finish when a lookup is unavailable \{#recover-without-inventing-data} For the food log, offer manual entry or let the customer retry the selected lookup; keep an unavailable nutrient blank. For the date picker, let them choose a date while showing that holiday information could not be confirmed. If a source is rate-limited, honor its retry guidance and bound retries. If only part of a multi-source result is available, show the sources that answered instead of presenting the partial list as complete. Keep source and retrieval dates where available so a cached value does not appear to be a fresh lookup. Confirm enabled sources and update policy with your operator before shipping either feature. Provider data feeds have their own licensing, availability and freshness requirements even when the software that calls them is self-hosted. --- URL: https://docs.travila.ai/developer-experience # Developer Experience \{#developer-experience} Get from an integration idea to a working request, then test the behavior your application depends on. Choose the task you need to complete; each guide identifies its supported interface and any upcoming additions. | I want to… | Start here | | --------------------------------------------------------- | -------------------------------------------------------------------------- | | Make my first authenticated call | [Quickstart](/managed-agents/conversations/quickstart) | | Run requests from my development environment | [Development setup](/developer-experience/local-tooling/development) | | Check recovery, tools and expected results before release | [Test an integration](/developer-experience/local-tooling/testing) | | Have a coding agent build against the actual interface | [Build with the documentation](/developer-experience/skills/build-with-ai) | | Look up an exact request, response or error | [API reference](/api) | | Add Travila to an application with an SDK | [SDK workflow](/developer-experience/sdks) — upcoming | | Develop and troubleshoot from the terminal | [CLI workflow](/developer-experience/local-tooling) — upcoming | | Give a coding agent a reusable integration procedure | [Skills](/developer-experience/skills) — upcoming | | Report an integration or documentation problem | [Feedback](/feedback) — product feedback submission is upcoming | The [feature catalog](/developer-experience/documentation/feature-catalog) summarizes availability; use the task guides for the steps and expected results. --- URL: https://docs.travila.ai/developer-experience/documentation/feature-catalog # Custom MCP server preview \{#platform-features} [Custom MCP servers](/integrations/tools-connections/features/custom-mcp-servers) are documented as **Preview**. Read that capability guide for deployment requirements and current limitations. Preview does not establish a support SLA or an unchanged compatibility promise. Use the page’s displayed document and section IDs when reporting feedback; [the documentation manifest](/documentation-manifest.json) records their revisions. --- URL: https://docs.travila.ai/developer-experience/local-tooling # Work from your terminal \{#overview} **Status:** Upcoming — not yet available. Debug a chat integration without rebuilding your application after every request. Start a terminal session, submit a controlled conversation, inspect its result and receive its events in your local handler. **Availability:** The customer CLI and local event-forwarding service are not released yet, so installation and command names are not supplied here. Use the [HTTP development setup](/developer-experience/local-tooling/development) and Postman collection for those available workflows today. This page describes the CLI experience. ## Start a development session \{#development-session} **Status:** Upcoming — not yet available. 1. Sign in and choose a saved deployment profile. Inspect the selected API origin, account and project before making requests. 2. Select your authorized test environment and use controlled data and recipients. Test work can still call paid models or tools; review [spending controls](/core-platform/billing-spend). 3. Run a conversation operation and inspect its conversation ID, run ID and status. Use the [first conversation guide](/managed-agents/conversations/quickstart) for the workflow. 4. Check the result, then exercise an interrupted request or denied action using [integration testing](/developer-experience/local-tooling/testing). The session is ready when the controlled message reaches the expected conversation result and you can recover its identity after an interrupted wait. For CI, supply credentials and required inputs explicitly. Noninteractive commands return structured results without opening a browser or waiting for input. A missing input returns an error and a nonzero exit status. The current HTTP API does not provide separate test projects or test keys. Follow the current testing guide until those controls are available; naming a local profile “test” does not create an isolated environment. ## Receive events in your local webhook handler \{#local-event-forwarding} **Status:** Upcoming — not yet available. Select the project, event types and local handler URL for a forwarding session. The session shows deliveries and your handler's responses so you can debug your integration while it runs locally. For example, subscribe to `llm.message_published` and inspect how your handler processes a new message. After a disconnect, the session identifies deliveries you can recover and any gap that has expired. Redelivering an event keeps its original identity; it does not repeat the action that produced the event. Synthetic fixtures, event redelivery and a new business action are separate choices. Your receiver still [verifies and deduplicates deliveries](/integrations/webhooks/endpoints). Until local forwarding is available, use an explicitly registered HTTPS receiver through [webhook setup](/integrations/webhooks). ## Resolve a failed request \{#request-diagnostics} **Status:** Upcoming — not yet available. | What you see | What to do | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | Authentication rejected | Check the selected API origin and credentials. Refresh an expired user token; replace a revoked key through its supported recovery process. | | Permission denied | Check that the selected account and key can perform the action on that resource. | | Rate limit reached | Follow the returned retry guidance within your request deadline. Request limits and spending budgets are separate controls. | | Connection lost after submission | Keep the known request or run ID and check its outcome before submitting another action. | | API unavailable | Retain the request ID and time for your Travila operator. Self-hosted operators can use their deployment's troubleshooting guide. | The CLI keeps structured results separate from diagnostic messages and returns a failure exit status for unsuccessful commands. An interrupted action reports its known identity and recovery information, so automation can stop or recover without treating an unknown result as a completed request. ## Finish development and sign out \{#session-cleanup} **Status:** Upcoming — not yet available. Remove the test resources you created through their supported operations and check whether cleanup completed. Signing out does not delete resources or cancel persistent schedules. Logout removes local credentials and reports remote revocation separately. If your machine is offline, remote revocation remains unconfirmed. This lets you distinguish a cleared workstation from a credential that may still work elsewhere. For an operator-controlled installation, see [deployment and operations](/enterprise/deployment-operations). Use [SDKs](/developer-experience/sdks) to embed the same application workflows in code or [developer skills](/developer-experience/skills) to work with a coding agent. --- URL: https://docs.travila.ai/developer-experience/local-tooling/development # Try a chat request in Postman \{#set-up-your-development-environment} Before wiring chat into your application, send one conversation request from Postman and inspect the answer. This gives you a working request to compare with your application's request when authentication or response handling goes wrong. **Before you start:** obtain an account, the supported API origin and credentials from your administrator. Use a controlled application user and message. Current requests can invoke paid models or real tools; there is no public sandbox or test-key type. Follow [testing setup](/developer-experience/local-tooling/testing#not-yet-available) for an isolated account and controlled destinations. ## Import the requests for the chat workflow \{#postman-collection} Import both files into Postman: * [Travila collection](/postman/travila-platform.postman_collection.json) * [Travila environment](/postman/travila-platform.postman_environment.json) Select the **Travila Platform** environment. Follow the [quickstart](/managed-agents/conversations/quickstart) to choose the conversation creation, message and state requests in order. You do not need to run every operation in the collection. The collection is generated from the same OpenAPI specs as the reference. Its generated bodies are starting points, not working test fixtures. Replace placeholders using the quickstart and the selected operation's schema; a generated request does not establish that a route is enabled for your deployment. ## Point Postman at your account \{#base-url} Set the environment's `baseUrl` to the API origin supplied for your account. For the hosted API, use `https://api.travila.ai`. Keep the origin and credentials for the same account together. The collection supplies each operation's path and JSON request method. For exact paths or a self-written HTTP client, use the [API reference](/api). ## Identify the application and signed-in user \{#required-headers} For this backend test, set `apiKey` to the secret key and `onBehalfOf` to your controlled application user's ID. The collection configures authentication headers once, and its requests inherit them. Keep the key out of shared exports and screenshots. If you are instead testing the browser/mobile authentication path, use a publishable key and set `jwt` to the signed-in user's token. Follow [authentication](/core-platform/identity-access/authentication) for the supported identity setup. A user-scoped request made with a backend key needs `X-On-Behalf-Of`. An `authenticated user_id is required` response means the user identity is missing; fix the request context before changing the conversation payload. The current public project is `default`; changing `X-Project-Id` does not create a project or a test environment. ## Send a message and inspect the completed result \{#body-encoding} 1. Use the quickstart's request body to create a conversation, replacing its example values with your own allowed settings. 2. Save the returned conversation ID and use it in the message request. Send a controlled message that does not ask a tool to change an external system. 3. Inspect the returned status and identifiers. Read the conversation state as the quickstart describes to find the result of your message. 4. Confirm that the answer belongs to the conversation and user you selected. Save the request with placeholders for secrets so you can compare it with your application later. A successful HTTP response can acknowledge work that is still running. Use [generation outcomes](/managed-agents/conversations/generation) to distinguish an answer from pending work, a tool request or a failure. If a response is lost, recover the known operation before resending a message. When converting the request into application code, follow the [JSON contract](/api#request-format) for field presence, response names and large integer values. The operation's generated schema remains the source for exact fields. ## Use the working request to finish your integration \{#whats-next} Run the same flow from your application's backend and compare its user identity, selected conversation and completed result with Postman. Then follow [integration testing](/developer-experience/local-tooling/testing) for interrupted requests and the tools your application uses. If you prefer to start in code, the [HTTP quickstart](/managed-agents/conversations/quickstart) provides the request sequence. [Build with a coding agent](/developer-experience/skills/build-with-ai) shows how to give that task and its exact reference to an agent. --- URL: https://docs.travila.ai/developer-experience/local-tooling/testing # Check a chat integration before customers use it \{#test-your-integration} Before enabling your assistant for customers, verify that it completes the task you promise and recovers when a request or tool call is interrupted. This recipe starts with a working chat integration and adds the tests that catch duplicate actions, lost tool results and regressions. **Before you start:** complete the [chat quickstart](/managed-agents/conversations/quickstart), then arrange a separately provisioned test account with your Travila operator. Use controlled data, recipients and finite spending limits. The current public API has no separate test projects or test keys; model calls can cost money and tools can act in real external accounts. First run one ordinary conversation through your application and save the conversation, run and result identities. The later checks compare actual outcomes with that baseline. Run the tool and scheduling checks only if your application uses those capabilities. ## Verify a connected tool before asking the assistant to use it \{#2-call-a-tool-in-isolation} Choose a read-only tool your test account is allowed to use. [Discover its current definition](/integrations/tools-connections), select the intended connected account and prepare arguments from that definition. Call it directly through [Execute an MCP tool](/api/conversations/mcp-call-tool#request) so you can distinguish a connection or argument problem from the assistant choosing the wrong action. Use the [direct-tool recipe](/integrations/tools-connections#calling-tools-directly) and [operation reference](/api/conversations/mcp-call-tool) for the request. Supply [`argumentsJson`](/api/models/schema-1it6mqsqoo#request-field-argumentsjson) as a JSON object, not an encoded string. [`requestId`](/api/conversations/mcp-call-tool#request-field-requestid) helps correlate the response; it is not a general deduplication guarantee. Verify the returned information belongs to your controlled account and matches the known fixture. Then use the same connection in a conversation and check the assistant's result. For memory tools, authorize the explicit user selector and use isolated test memories until your deployment's memory isolation is qualified; the selector is not proof of permission. ## Verify that an in-app action returns control to the conversation \{#3-exercise-the-client-tool-loop-end-to-end} If your assistant can navigate your application, configure a controlled conversation with the `navigate_to` client tool using the [client-tool guide](/managed-agents/delegation-approvals/using-tools#client-side-tools). Replace the sample conversation ID below with that conversation. Ask it to open the profile page: [Request example: Send a message and wait for the result](/api/conversations/send-message-sync#example-cookbook-developer-experience-local-tooling-testing-01-request). 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. Read the actual response. When it reports `AGENT_STATUS_AWAITING_CLIENT_TOOLS`, save the call ID, arguments and [`clientToolCursor`](/api/conversations/send-message-sync#response-field-clienttoolcursor). Check that the user may perform the requested navigation, execute it in your test application, and submit the actual result using those returned values: [Request example: Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync#example-cookbook-developer-experience-local-tooling-testing-02-request). 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. The sample call ID and cursor above are placeholders. Do not report a navigation that did not happen. Check the new status after submission: another tool round needs another result, active work still needs observation, and a terminal result can be success, failure, cancellation or timeout. The test passes when the requested page opens and the same conversation reaches its expected result with matching call identities. Also drop the connection once and recover the original pending call before deciding whether it still needs execution. See the [full recovery workflow](/managed-agents/delegation-approvals/using-tools#client-side-tools). Client tools wait for your application; they do not appear in the platform approval queue. Your application performs its own permission check before executing them. ## Prevent a network retry from repeating the customer’s action \{#1-qualify-retries-before-enabling-them} Interrupt a response after your application submits a controlled action. Keep the original operation identity and inspect its outcome before sending another mutation. Verify the customer's visible result and the number of real effects, such as messages delivered or records changed. Enable automatic write retries only for an endpoint whose deduplication contract is qualified for your deployment. Test the same scope, operation key and payload twice, including a lost response. Then test a changed payload, another user, expired retention and revoked access. These cases must not reuse another caller's result or silently repeat an effect. The public API does not provide universal deduplication or a guaranteed 24-hour retry window. Follow the [retry contract](/api#idempotent-requests); where it is unqualified, recover the original operation and require an explicit decision before a new mutation. Equal response bodies alone do not prove that only one action occurred. ## Keep good answers from regressing after a change \{#4-regression-test-agent-behaviour-with-eval-datasets} Save a small set of representative customer tasks and their expected results. Include the successful chat turn, the tool interaction and a failure case your application must handle. Run those cases with the current configuration, then again after changing the model, instructions or tools. Follow [datasets and evaluation runs](/insights/evaluation/datasets-and-runs) to create the dataset, execute each item in your harness, score its result and record the run. The evaluation API records evidence; recording a run does not execute its items or authorize actions in customer systems. Compare the actual answers and task outcomes, investigate failures, and retain the run and configuration references with your release decision. Use isolated fixtures and finite spending limits for both versions. A stored evaluation run without executed cases is not evidence that the new assistant works. ## Check a scheduled follow-up before enabling recurrence \{#5-verify-scheduler-callbacks-locally} If the application sends a scheduled briefing or reminder, start with a single controlled callback to your test receiver. [Verify its signature and claims](/core-platform/scheduling/verifying) before allowing the receiver to start work, then reject invalid callbacks and acknowledge an identical valid retry without repeating the work. Follow the [scheduled-agent recipe](/core-platform/scheduling/build-scheduled-agents) through to the final notification or conversation result. Confirm the intended recipient receives it once for the intended execution. A successful callback delivery alone does not prove the downstream task finished. Use the verification guide's published signing-key discovery and rotation procedure; do not copy a single signing key into the receiver. Enable the recurring schedule only after the controlled execution and failure case behave as expected. ## Choose a test setup that matches current availability \{#not-yet-available} | What you need | Current setup | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Keep tests away from customer data | Arrange a separately provisioned account and controlled destinations with your operator. Public test/live modes are not available. | | Use development credentials | Use the supported `sk_*` or `pk_*` path. There is no separate test-key type. | | Select an isolated project | The current public project is `default`; a different header does not create a project. | | Exercise webhook recovery | Use a controlled real event or delivery retry. A synthetic webhook test-event API is not available. | Keep the exact environment, configuration, observed result and remaining failures with your verification record. Report what you ran; do not mark unsupported test cases as passed. --- URL: https://docs.travila.ai/developer-experience/skills # Use focused guidance with your coding agent \{#overview} **Status:** Upcoming — not yet available. Use a developer skill to guide your coding agent through a Travila integration, such as adding chat, receiving webhook events or evaluating an agent change. Each skill combines focused instructions with the relevant API reference and examples. **Availability:** Public Travila skill packages and an endpoint for external coding agents are not released yet. You can use [documentation retrieval and a bootstrap prompt](/developer-experience/skills/build-with-ai) with the public HTTP APIs today. A skill supplies guidance. Your configured credentials and permissions determine what the agent can access and execute. ## Build an integration with a coding agent \{#documentation-workflow} **Status:** Upcoming — not yet available. 1. Choose one outcome: add a conversation, receive webhook events or run a controlled evaluation. 2. Give the agent the matching skill and your intended API origin. Set credentials through the client's secret mechanism; keep them out of shared prompts. 3. Supply the [documentation index](/llms.txt), task guide and operation schemas. The [combined guide file](/llms-full.txt) contains guides; exact API fields come from the linked reference. 4. Review the requests the agent prepares and the actions they perform before authorizing execution. 5. Test the result and one failure-recovery case using [integration testing](/developer-experience/local-tooling/testing). For a webhook integration, the skill guides the agent through preparing a receiver, verifying a delivery and handling a duplicate. It links the current schemas and recovery instructions. If a required reference or operation is missing, the agent identifies that gap instead of inventing an endpoint. ## Choose a skill for your task \{#skill-collection} **Status:** Upcoming — not yet available. | Your goal | What the skill guides you through | Related guide | | ------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | | Add chat to an application | Select credentials, create a conversation, send a message and diagnose a rejected request. | [Quickstart](/managed-agents/conversations/quickstart) | | Respond to Travila events | Register a receiver, verify deliveries and recover from duplicates or interruptions. | [Webhooks](/integrations/webhooks) | | Build and evaluate a tool-using agent | Configure its tools, run controlled cases and inspect the results. | [Tools](/integrations/tools-connections) and [evaluation](/insights/evaluation) | Each released skill identifies its supported client capabilities and API version. The workflows above are descriptions, not package names or installation commands. ## Install and update a skill \{#package-review} **Status:** Upcoming — not yet available. Skills use the [Agent Skills format](https://agentskills.io/specification): a directory containing `SKILL.md` instructions and optional references, assets or scripts. Use a client that supports the package's required capabilities. Review the publisher, version, license, instructions and included scripts before installation. Installing guidance does not run its scripts or perform actions in Travila. When updating, review the changed instructions and resolve any conflict with your local edits. Retain the previous version when you need to roll back. Removing a skill removes its guidance; revoke credentials or cancel submitted work separately when that is your intent. ## Use skills with your own infrastructure \{#local-skill-use} **Status:** Upcoming — not yet available. Obtain the versioned skill package from your own mirror, configure your self-hosted API origin, and use a compatible local coding client and model. The workflow does not require a proprietary package registry. Verify that the selected tools and model are available in your environment; a local instruction file does not make a hosted dependency available offline. Run the same integration task before and after adopting the skill, comparing the result, corrections, time and cost. [Evaluation](/insights/evaluation) helps you keep that comparison repeatable. See [language SDKs](/developer-experience/sdks) for application code and [terminal workflows](/developer-experience/local-tooling) for local commands. --- URL: https://docs.travila.ai/developer-experience/skills/build-with-ai # Ask a coding agent to add chat to your application \{#build-with-ai-coding-agents} Use a coding agent to add a working chat flow to an existing application: create a conversation, send a user's message and display its result. Give it the outcome and relevant contract, then review the integration against your application's authentication and user interface. **Before you start:** identify the application's backend, signed-in user mechanism and chat screen. Obtain the credentials needed for a controlled test, and configure them through your development environment's secret mechanism rather than pasting them into a shared prompt. ## Give the agent the references for this feature \{#what-to-point-an-agent-at} Start with the [documentation index](/llms.txt) and [chat quickstart](/managed-agents/conversations/quickstart). Ask the agent to follow their links to the specific API operations it needs. Retrieve an additional guide when the feature needs it, such as file attachments or client tools. Guide and API reference pages have plain Markdown copies: append `.md` to the route, for example `https://docs.travila.ai/managed-agents/conversations/quickstart.md`. API copies include request/response schemas and link to the downloadable OpenAPI contracts. The [combined documentation file](/llms-full.txt) includes selected guides and canonical API reference pages. Use it for a broader review when it fits the agent’s context; for this chat integration, the quickstart and selected operations are usually sufficient. ## Describe the finished feature in the task prompt \{#bootstrap-prompt} Adapt this task to your repository and chosen test environment: Coding-assistant bootstrap prompt. * Add a chat feature to this application using Travila's current HTTP API. * Read https\://docs.travila.ai/managed-agents/conversations/quickstart.md and follow its links * to the exact API reference. Use https\://docs.travila.ai/llms.txt to find * additional guides only when this feature needs them. * Use our existing signed-in user flow. Keep backend secrets on the server. * Let the user create a conversation, send a message and see its completed * answer. Save the conversation identity so another message continues it. * Handle pending work and failures explicitly. After a lost response, recover * the original operation instead of automatically submitting another message. * Inspect our application structure before choosing files to change. Use the * existing design and error handling patterns. Do not invent API fields, * SDK packages or support for upcoming features. Identify any missing contract. * Verify one complete chat turn and one interrupted-request recovery case in * our controlled test environment, and report exactly what was verified. Add your application's file locations and the user-visible behavior you expect. Keep credentials and unrelated customer conversations out of the prompt. ## Review the generated integration against the real request \{#conventions-agents-must-know} Check the prepared requests against the linked operation schemas before running them. The agent should use the application's authenticated user, keep the returned conversation and run identifiers, and interpret status rather than assuming every successful request contains an answer. Let the generated API reference supply encoding and presence rules. In particular, do not allow the client to round large counters or treat an omitted value as a supported explicit setting. Use the [API contract](/api) when reviewing those details. Review the code diff and the external actions a test will perform. A coding agent reading documentation has not been authorized to access every connected account or send a message to a real recipient. ## Verify that a customer can complete a conversation \{#next-steps} Run the feature as your controlled application user. Create a conversation, send a message, wait for its actual outcome, and send a follow-up in the same conversation. Verify that the interface shows the intended answers and handles the interrupted-request case without duplicating the user's action. Keep the result and any remaining failures with the code review. An agent's completion message or a compiling client does not prove the conversation works. Use [integration testing](/developer-experience/local-tooling/testing) for the rest of your application's acceptance cases. For reusable packaged guidance, see the upcoming [developer skills](/developer-experience/skills) workflow. --- URL: https://docs.travila.ai/developer-experience/sdks # Build an application with a Travila SDK \{#overview} **Status:** Upcoming — not yet available. Add chat to your application without writing every HTTP request by hand. This recipe creates a conversation, displays a reply, and recovers when the connection ends before the answer arrives. The SDK handles request encoding and typed results while your application controls credentials, customer selection and what to do with the response. **Availability:** Application SDK packages are not released yet. TypeScript and Python are the first target languages, followed by Go; Swift support is handled separately for mobile. Installation commands and supported runtime versions are not available yet. To integrate today, use the [HTTP quickstart](/managed-agents/conversations/quickstart) and [API reference](/api). OpenAI client compatibility is a separate interface; the native conversation API does not accept OpenAI requests interchangeably. ## Add a conversation to your application \{#first-client-workflow} **Status:** Upcoming — not yet available. 1. Create or select your first project through [workspace setup](/core-platform/workspaces-projects), then obtain credentials for your application. 2. Configure the client with your API base URL and credentials. Keep secret keys on your backend. A browser or mobile application uses a publishable key with the signed-in user's token; see [authentication](/core-platform/identity-access/authentication). 3. Create a conversation and save its ID. Send the user's message to that conversation. 4. Read the returned run ID and status. Display the answer when the run completes, or handle a tool request when the run needs your application's help. 5. Set a limit on how long your application waits. If the connection ends first, retain the run ID and follow the [generation recovery workflow](/managed-agents/conversations/generation) rather than sending the user's message again. Verify the completed feature by sending a follow-up in the saved conversation and confirming it appears with the earlier exchange. For a chat application, the conversation ID connects later messages to the same history. The run ID identifies the work started by one send. A successful request can mean that work was accepted or paused for a tool; it does not always contain a finished answer. ## Handle results, pagination and interrupted requests \{#response-semantics} **Status:** Upcoming — not yet available. The client preserves the information your application needs to interpret a result: | Your task | Client behavior | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Apply an optional setting | Keeps omission distinct from an explicitly supplied `false` or `0` where the API supports that distinction. | | Store a large counter or sequence | Preserves decimal-string 64-bit values without rounding them to a JavaScript number. | | Load the next page | Keeps the original filters and follows the operation's continuation cursor, including after a short or empty page. | | Handle a newer response value | Exposes an unknown value or compatibility error instead of calling it success. | | Recover after a timeout | Retains the known resource or run identity. Retries follow the endpoint's [retry contract](/api#idempotent-requests); a write is not silently repeated. | | Stop waiting | Cancels the local wait without claiming that remote work or an external action stopped. | For example, a sequence value of `"9007199254740993"` remains the same when you store and resend it. If a request's result is unknown, your application can present that state and recover it without issuing a duplicate action. ## Connect to more than one deployment or account \{#client-isolation} **Status:** Upcoming — not yet available. Create a separate client configuration for each deployment and account your application is authorized to use. Changing credentials on one client does not change another client's credentials, including during concurrent requests. For example, a service that connects to two customer-owned deployments keeps each API origin and credential together. It cannot obtain access to another project by changing a resource ID. Use your own API origin for a self-hosted installation and keep TLS verification enabled. Credentials are not forwarded to another origin after a redirect. Use request IDs, status and timing to diagnose failures; keep keys, tokens, signed download URLs and private request bodies out of routine logs. ## Upgrade your integration safely \{#sdk-adoption} **Status:** Upcoming — not yet available. Each SDK release identifies its supported API and runtime versions, operation coverage, license and upgrade instructions. Use a pinned package version, including when installing from your organization's private mirror. Before upgrading, run your integration's main workflow and failure cases with the new client. Check denied access, pagination, lost responses and concurrent clients using [integration testing](/developer-experience/local-tooling/testing). Pre-1.0 upgrades can require application changes; follow the release's migration guidance. Keep the earlier package if you need to roll back the client. Rolling it back does not undo requests already processed by Travila. See [terminal workflows](/developer-experience/local-tooling) and [coding-agent skills](/developer-experience/skills) for other ways to build your integration. --- URL: https://docs.travila.ai/core-platform # Core Platform \{#core-platform} Give your application authenticated access, store files for its users, send notifications and run recurring work. Start with the task you need below; each guide identifies its availability and setup requirements. | Build this application feature | Recipe | | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Let a signed-in person use their own conversations and data | [Connect application authentication](/core-platform/identity-access/authentication), then [choose the feature’s permissions](/core-platform/identity-access/scopes-permissions) | | Let users choose the assistant’s language and preferences | [Build an agent preferences screen](/core-platform/identity-access/end-users) | | Welcome a user and keep updates in their inbox | [Prepare the welcome notification](/core-platform/notifications/administration#get-started), then [build the inbox](/core-platform/notifications/inbox) | | Send a coaching update to a phone or a subscribed group | [Send a completed update](/core-platform/notifications/sending), [connect push](/core-platform/notifications/push), or [build topic subscriptions](/core-platform/notifications/topics) | | Deliver a daily agent briefing | [Build the scheduled agent workflow](/core-platform/scheduling/build-scheduled-agents), then [let the user change its schedule](/core-platform/scheduling/managing) | | Store and retrieve a user’s attachments | [Build user file storage](/core-platform/files-data/files) and [organize files](/core-platform/files-data/managing) | | Connect a private tool using a stored credential | [Store, reference and rotate the credential](/core-platform/secrets) | | Take an application from its trial into paid use | [Approve funding and reconcile usage](/core-platform/billing-spend) — Upcoming, not yet available | | Give a teammate application access | [Onboard the teammate in the console](/core-platform/console-administration) — Upcoming, not yet available | | Fulfil a customer’s export or erasure request | [Track the privacy request to resolution](/core-platform/governance-privacy) — Upcoming, not yet available | Choose the feature first and follow its steps through the visible result and recovery path. Complete field catalogs live in the [Storage](/api/storage), [End User](/api/end-users), [Notification](/api/notifications), [Scheduler](/api/scheduled-jobs) and [Secrets](/api/secrets) API references. --- URL: https://docs.travila.ai/core-platform/workspaces-projects # Launch an application with your team \{#overview} **Status:** Upcoming — not yet available. Set up a Travila project for your application, make the first permitted call, and give teammates access without sharing one person's credentials. This recipe takes a new team from signup through a tested configuration to live use. **Available today:** use the account and credentials supplied by your administrator and follow the [HTTP quickstart](/managed-agents/conversations/quickstart). The current public API uses the legacy `default` project. Self-service first-project creation, multiple projects and separate test/live modes are not yet available; a different project header or a key named “test” does not enable them. The following workflow describes the upcoming project experience. Your first project is part of onboarding, so setup finishes with a usable place to build your application. ## Choose the home for your application \{#workspace-model} **Status:** Upcoming — not yet available. Use a workspace for your company and a project for each application. For example, a team building a support assistant creates one project for that application; it adds a second project when it builds a separate sales assistant. Choose a supported data region before creating the project. That region is fixed for the project, so check your [data placement requirements](/core-platform/governance-privacy) before continuing. Each project provides test and live modes for preparing changes and serving customers. If your application serves several business customers, use a project customer identity for each one. The identity is shared across test and live, while records, users and connections remain separate in each mode. Records with no customer assigned form their own unassigned selection; that selection does not mean “all customers.” If you manage a separate business's own Travila workspace, it remains an independent workspace and grants you the access you need. Follow [Travila for Platforms](/platforms) for that relationship. Ownership, permission to operate and responsibility for payment are separate choices. ## Create the first project and make a test call \{#first-project-setup} **Status:** Upcoming — not yet available. 1. **Create or join your workspace.** Verify your identity through signup or accept a verified invitation. A company's name or email domain alone does not grant membership in its workspace. 2. **Create the application project.** Give it a name and choose a supported, permitted data region. Review the capabilities and capacity offered there. 3. **Wait for the required capabilities to be ready.** Setup shows its progress and names any quota, capacity or integration step that needs attention. Use the recovery steps below if setup is interrupted. 4. **Review the included allowance.** See the finite free usage and remaining capacity before making the first call. You can use the applicable allowance without entering payment details; permission to incur paid spending is separate. 5. **Create a service credential for test.** Select its owning service, project, mode, permissions and expiry. Store the returned secret securely on your backend. Reloading the page does not reveal the old secret or create a replacement key. 6. **Make the first permitted call.** Follow the [conversation quickstart](/managed-agents/conversations/quickstart) with the selected project's supported credentials and verify the returned result. Authorization and finite usage limits apply from this first call. You have completed onboarding when the first project and required capability are ready and your application can make its first authorized call. Keep the project and operation references if a setup step needs recovery. ### Resume setup after an interruption \{#project-readiness} **Status:** Upcoming — not yet available. Reopen the original project operation if the browser closes or a request times out. Recovering that operation returns the same project and its progress, so a slow setup does not create duplicate projects. | Setup shows | Next step | | ------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Pending | Continue from the original operation and inspect the remaining step. | | Requires action | Complete the named prerequisite, such as capacity approval or a required connection. | | Ready | Check that the particular capability your application needs is ready, then make the test call. | | Failed or uncertain | Keep the project and operation references and ask the responsible account contact to reconcile or retry the failed step. | When requesting help, include the intended application, region, required capability, operation reference, last observed state and time. Leave credentials out. A project can exist while one capability still needs setup; readiness makes that unfinished work visible. ## Invite teammates without sharing service keys \{#people-and-service-ownership} **Status:** Upcoming — not yet available. Assign each ordinary workspace member to the projects they need. Workspace administrators inherit project access. Your teammates can then manage their assigned work without passing a personal credential around the team. Keep application keys owned by the project and service that use them, with a current responsible contact and the creator recorded in audit history. When a developer leaves, remove their workspace membership to end all their project access. The independently owned service key continues to work; review possible secret exposure separately and [rotate or revoke exposed keys](/api/authentication#managing-api-keys). When demoting an administrator who remains a workspace member, review direct project assignments too: separately granted access can remain. Test and live service credentials stay pinned to their permitted project and mode, so a test credential cannot run live work. ## Try a configuration change before serving customers \{#test-and-promotion} **Status:** Upcoming — not yet available. Configure the support assistant in test and run representative conversations with controlled data. Test starts without live provider credentials or destinations. If you deliberately connect a real external account, its tools can still send messages, change data or incur charges. Once the change gives the intended result, select the tested configuration version and the live destination. Review the difference and promote it using source-read and destination-write permission. Promotion copies the selected agent configuration; credentials, conversations, schedules and customer history stay in their original mode. Verify the live assistant's result after promotion. An authorized teammate can also edit live directly, and the configuration history identifies that edit separately. Until project modes are available, use the [current integration testing workflow](/developer-experience/local-tooling/testing) with its stated isolation limits. ## Bring an existing integration into the project model \{#existing-account} **Status:** Upcoming — not yet available. Keep using your administrator-provisioned account until its migration is supported. Record the application credentials, required scopes, user-identity setup, connected accounts, usage allowance and spending permissions that the existing integration depends on. During an agreed migration, preserve verified project and resource identities and resolve unmapped ownership before moving traffic. Afterward, repeat the application's main flow with the intended project credentials and verify the user and usage attribution. Naming a legacy credential after the new project is not a migration or an access boundary. Use [authentication](/core-platform/identity-access/authentication) and [integration testing](/developer-experience/local-tooling/testing) for the currently supported path. Current test fixtures can invoke real models, tools and recipients; arrange controlled destinations with your administrator. ## Retire or relocate an application deliberately \{#project-lifecycle} **Status:** Upcoming — not yet available. When you need to stop the assistant immediately, suspend its project to stop new work. Track requests already sent to external services separately; suspension does not undo those actions. Choose the next step according to what your team needs to keep: | Your goal | Action and result | | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Pause an application while preserving eligible data | Archive the project and check the disclosed restoration deadline and exclusions. An eligible restore does not revive revoked credentials. | | Clear test fixtures and continue serving customers | Reset only the authorized test scope; live data stays available. | | Remove one application's customer | Suspend or erase that customer across both modes and follow cleanup for each capability. | | Close the workspace | Track cleanup, pending provider actions and records retained under an approved exception until the requested scope is accounted for. | | Move to another data region | Create a project in the new region and approve a migration covering identities, moved data and any retained copies. Changing a workspace preference does not move existing data. | Changing the payer or accepting an [Enterprise agreement](/enterprise/commercial-agreements) preserves workspace, project and credential identities unless a separate migration is agreed. Earlier usage keeps its original attribution, and payment does not remove an independent security restriction. See [billing and spend](/core-platform/billing-spend). --- URL: https://docs.travila.ai/core-platform/files-data # Build features with customer files \{#store-and-serve-user-files} Let a customer attach a recording to a support request, collect a project's documents, or find a report they uploaded last month. Travila stores the files for the authenticated application user; your application connects each returned file ID to the case, project or other record it belongs to. ## Choose the feature you are building \{#start-here} | Customer need | Recipe and finished result | | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | “I need to send you a recording of the bug.” | [Build an attachment flow](/core-platform/files-data/files): select a file, confirm the upload, and reopen it from the support request. | | “Keep this project's documents together.” | [Organize project documents](/core-platform/files-data/folders): prepare a folder, add documents, and remove the project’s files deliberately. | | “Find the report I uploaded and mark it reviewed.” | [Build a document library](/core-platform/files-data/managing): browse, search by name or tag, label work and archive it. | | “Ask the assistant about this file.” | [Attach a file to a conversation](/managed-agents/conversations/attachments): use a stored attachment in a supported model request. | ## Connect storage to the signed-in customer \{#how-it-works} Identify the application user from your authenticated session before making storage requests. Keep a file's ID on your own application record, and request temporary links when that user uploads or opens it. Each user has a separate folder tree and storage quota. Use folders for organization within that user's files. They do not select another user or create a new authorization boundary. Upload and download URLs are temporary access links; keep them private and store the file ID as the durable application reference. ## Prepare your integration \{#related} Start with [authentication](/core-platform/identity-access/authentication) so the recipe uses the correct application user. Keep your backend secret out of client-side code. Use the [Storage API reference](/api/storage) for exact operation fields, response types and supported options as you implement the chosen flow. --- URL: https://docs.travila.ai/core-platform/files-data/files # Add file attachments to a support request \{#upload-and-download-files} A customer reporting a bug needs to send a recording and open it again when they return to the case. Build an attachment flow that uploads the recording, confirms it is stored, and retrieves a fresh download link whenever the customer opens it. This recipe uses `video.mp4` as an example. The same flow works for documents and other files. Your application owns the support request and associates it with Travila's returned [`fileId`](/api/storage/generate-upload-url#response-field-fileid); Travila provides file storage, metadata and temporary upload/download URLs. **Before you start:** use an [authenticated application user](/api/authentication#acting-as-a-user--x-on-behalf-of), a backend credential kept off the browser, and a test file you are allowed to store. Create the `/media` folder through the [folder recipe](/core-platform/files-data/folders) if your application needs a folder entry. Use the same user for every storage call in this recipe. ## Build the upload interaction \{#uploading-files} When the customer selects a file, your application knows its name, content type and byte size. Keep the attachment in a pending state while the upload and registration finish. Only a registered file is ready to show as an attachment. Use a pre-signed upload for new integrations, including small files. The file bytes go directly to the returned upload destination, while your backend handles the authenticated Travila requests. This avoids sending a base64 copy through your API request. The flow has three stages: request an upload URL, send the file bytes, then register the uploaded file. Keep the returned file ID across those stages so an interrupted request can be checked without starting another attachment. ### Upload and confirm the recording \{#pre-signed-upload-large-files} **1. Request a destination for the selected file.** Supply its actual byte size. This example declares a 50 MiB recording; use the size of your own file. The upload URL expires after the requested period. [Request example: Generate a pre-signed upload URL](/api/storage/generate-upload-url#example-cookbook-core-platform-files-data-files-01-request). 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. Travila returns the file ID to keep with the pending attachment, the upload URL and the headers your uploader must send: [Response example: Generate a pre-signed upload URL](/api/storage/generate-upload-url#example-cookbook-core-platform-files-data-files-json-01-response). Example identifiers and values are illustrative; substitute authorized values. [Check that the upload finished before registering it](/api/storage/uploads#files-pre-signed-upload-large-files). If a response is lost, keep the same file reference while recovering the attachment. **2. Send the selected file to that URL.** Use the returned URL and every [`requiredHeaders`](/api/storage/generate-upload-url#response-field-requiredheaders) value unchanged. The example below shows the values from the response above; your application must use its own response. Provider-specific upload illustration: first use [the upload-URL contract](/api/storage/generate-upload-url#request). Use the returned URL and required headers unchanged; upload the file bytes as the binary body, not JSON or protobuf. The example uses a PUT of video.mp4, Content-Type video/mp4, and a provider-required x-goog-content-length-range of 0,52428800. Its storage.googleapis.com bucket URL is a placeholder, not an issued upload target. Use the provider, URL and headers returned for your upload; these example values are not an upload target. **3. Register the uploaded file.** Use the same ID, folder and name to make it available for listing and download: [Request example: Register a file uploaded via pre-signed URL](/api/storage/register-uploaded-file#example-cookbook-core-platform-files-data-files-03-request). 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. After registration succeeds, save the [`fileId`](/api/storage/generate-upload-url#response-field-fileid) on your application's support request and mark the attachment ready. The customer can leave and return to the case without uploading it again. If registration returns `404`, the object is not yet available; check the upload before registering again. Exact request and response fields: [upload URL](/api/storage/generate-upload-url) and [registration](/api/storage/register-uploaded-file). ## Let the customer reopen the attachment \{#downloading-files} When the customer opens the case, load the saved [`fileId`](/api/storage/generate-upload-url#response-field-fileid) from your application record. Authenticate that same user and request a fresh download URL: [Request example: Generate a pre-signed download URL](/api/storage/generate-download-url#example-cookbook-core-platform-files-data-files-04-request). 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. [Response example: Generate a pre-signed download URL](/api/storage/generate-download-url#example-cookbook-core-platform-files-data-files-json-02-response). Example identifiers and values are illustrative; substitute authorized values. Use the returned URL to open or download the recording. The response also provides its name, type and size for your attachment row. The completed feature lets the customer reopen the stored recording after a page reload; it does not depend on keeping the original upload URL. To offer a download with a chosen filename, use the operation's [`responseContentDisposition`](/api/storage/generate-download-url#request-field-responsecontentdisposition) field, for example: [Request example: Generate a pre-signed download URL](/api/storage/generate-download-url#example-cookbook-core-platform-files-data-files-json-03-request). Example identifiers and values are illustrative; substitute authorized values. Request a URL when it is needed and keep it out of public logs or messages. Its expiry limits the link's lifetime; anyone who possesses a still-valid URL can use it. Do not treat the URL as the permanent attachment record. See the [download reference](/api/storage/generate-download-url) for the exact contract. ### Show several attachments on the case \{#many-urls-at-once} For a case with several attachments, use the saved file IDs to request download links in a batch of 1–50 files. This prepares the attachment list without a separate request for every link: [Request example: Generate pre-signed download URLs for multiple files](/api/storage/batch-generate-download-urls#example-cookbook-core-platform-files-data-files-05-request). 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. [Response example: Generate pre-signed download URLs for multiple files](/api/storage/batch-generate-download-urls#example-cookbook-core-platform-files-data-files-json-04-response). Example identifiers and values are illustrative; substitute authorized values. Render each result independently. Show a link only when [`success`](/api/models/schema-oq46sv4kha#response-field-success) is true and a usable URL is present. A missing success flag means false; show an unavailable attachment for that entry while leaving successful attachments usable. Match the result by [`fileId`](/api/storage/generate-upload-url#response-field-fileid), not by assuming the whole batch succeeded. The batch can return different outcomes even when its HTTP request succeeds. Use the [batch reference](/api/storage/batch-generate-download-urls) for all fields. ## Recover an attachment that cannot be opened \{#file-references-and-expiry} | Customer sees | Application recovery | | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Upload did not finish | Keep the attachment pending. Check the transfer before attempting registration; a URL response alone did not store the file. | | Registration response was lost | Register the same file ID again and use its existing result. | | Download link expired | Request a new authorized link for the saved file ID. Do not ask the customer to upload the file again solely because a link expired. | | File is no longer available or access is denied | Show that attachment as unavailable and keep other attachments usable. [A saved ID does not guarantee permanent retention or access](/api/storage/uploads#files-file-references-and-expiry). | | An assistant cannot read a required attachment | Explain that the file could not be used; do not present an answer as if it included that file. See [conversation attachments](/managed-agents/conversations/attachments). | The supplied [`contentType`](/api/models/schema-1lls6fo8p7#response-field-contenttype) is metadata. It does not independently verify the bytes or establish that a file is safe to display. Apply the file handling rules your application needs before rendering customer content. ## Move an existing inline uploader to this flow \{#inline-upload-small-files} If your application already sends base64 content to `upload-file`, replace that path with the three stages above and keep associating the resulting file ID with the same application record. Inline upload is deprecated; it is not the recommended path for a new attachment feature. Its exact legacy contract remains in the [inline upload reference](/api/storage/upload-file). Complete one upload and reopen it through a fresh download link before switching the rest of your application. Existing registered files can continue to be retrieved by their IDs. --- URL: https://docs.travila.ai/core-platform/files-data/folders # Organize a customer’s project documents \{#folders} A customer working on several projects needs to find each project's documents together. Give them a folder for the work, store new documents there, and show that folder when they return to the project. In this recipe, `/documents/work` holds one application user's work documents. Folder names are organization within that user's storage; they are not separate Travila projects or a way to grant another user access. **Before you start:** complete [authentication for an application user](/api/authentication#acting-as-a-user--x-on-behalf-of). Use that same user for folder, upload and listing requests. Your application maintains the association between its project and the folder path. ## Prepare a folder and add the first document \{#create-a-folder} 1. Choose the folder path your application will use for the project. If your interface displays parent folders, create `/documents` first by using that path in the [create-folder request](/api/storage/create-folder). 2. Create the project's folder: [Request example: Create a new folder](/api/storage/create-folder#example-cookbook-core-platform-files-data-folders-01-request). 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. 3. Follow the [attachment upload recipe](/core-platform/files-data/files), using `/documents/work` as the folder path when [requesting the upload URL](/api/storage/generate-upload-url#request-field-folderpath) and [registering the file](/api/storage/register-uploaded-file#request-field-folderpath). 4. [List files in that folder](/core-platform/files-data/managing#list-files-in-a-folder) to display the project's documents. Open a document using a fresh download link for its file ID. The finished project page shows the uploaded document when the customer returns. Creating `/documents/work` creates only that folder entry; it does not create a separate `/documents` entry. Explicitly creating the parents in step 1 keeps a folder-tree interface consistent. ## Remove the project’s documents when the customer chooses \{#delete-a-folder} When the customer no longer needs these documents, first show the files and subfolders affected by deleting the folder. Request confirmation in your application before deleting content the customer may still need. To preserve a document, [move it to another folder](/core-platform/files-data/managing#move--rename-a-file) first. To delete this folder and its contents: [Request example: Delete a folder](/api/storage/delete-folder#example-cookbook-core-platform-files-data-folders-02-request). 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. Refresh the folder listing after the operation. If deletion fails, inspect which files remain before offering another attempt: [some files may already have been removed](/api/storage/delete-folder#overview). --- URL: https://docs.travila.ai/core-platform/files-data/managing # Build a searchable document library \{#managing-files} A customer who has uploaded weeks of notes and reports needs to find the right document, label reviewed work, and make room for new files. Build a library with a folder view, name/tag search, a document detail panel and deliberate cleanup. **Before you start:** [upload a few test documents](/core-platform/files-data/files) for one authenticated application user. The examples use `/documents` and show individual operations for the library's interactions. Replace the sample file ID with an ID returned for your user, and keep that ID in each list item even when its name or folder changes. ## Help the customer find a document \{#listing-and-searching-files} Start with the customer's current folder, then offer search when they remember a name or tag instead of a location. Use a folder listing for browsing and filtering; use search across folders for a known document. Neither path searches inside file contents. ### Populate the folder view \{#list-files-in-a-folder} Load the first page of the customer's documents: [Request example: List files and folders in a directory](/api/storage/list-files#example-cookbook-core-platform-files-data-managing-01-request). 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. Use the listing's pagination contract when the folder contains more results. Keep the returned file IDs with the visible rows so selecting one opens the same document after a rename or move. The [list-files reference](/api/storage/list-files) describes the response and pagination fields. A “Work reports” view can narrow the list to matching names, types and tags: [Request example: List files and folders in a directory](/api/storage/list-files#example-cookbook-core-platform-files-data-managing-json-01-request). Example identifiers and values are illustrative; substitute authorized values. An empty result should offer a way to clear these filters or upload a document. It does not mean the user's entire storage is empty. ### Find a report when its folder is unknown \{#search-files} Send the customer's query to search across their folders. This example finds PDF reports using a name or tag match, with additional criteria for a finance view: [Request example: Search files](/api/storage/search-files#example-cookbook-core-platform-files-data-managing-02-request). 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. Let the customer narrow a broad search by name or tag. Do not offer an effective date filter or a complete inventory from [this capped lookup](/api/storage/search-files#overview). ## Let the customer review and label a document \{#file-metadata} Selecting a result opens a detail panel with the file's current metadata and a download action. After reading the document, the customer can mark it reviewed and add the labels your application uses to organize work. ### Open the selected document’s details \{#get-metadata} Read the selected file by ID rather than using the displayed name as its identity: [Request example: Get file metadata](/api/storage/get-file-metadata#example-cookbook-core-platform-files-data-managing-03-request). 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. Show the returned details, then request a [fresh download link](/core-platform/files-data/files#downloading-files) when the customer opens the file. A stale or deleted result should appear unavailable without preventing the customer from opening other documents. See the [metadata reference](/api/storage/get-file-metadata). ### Save the review labels without erasing other labels \{#update-metadata} Read the latest metadata, merge the customer's changes in your application, and submit the complete metadata map and complete nonempty tag list you intend to keep. For a document whose intended final labels are those below: [Request example: Update file metadata](/api/storage/update-file-metadata#example-cookbook-core-platform-files-data-managing-04-request). 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. Refresh the detail panel and relevant filtered list after saving. Coordinate simultaneous edits so one writer does not erase another's changes: [the supplied metadata map replaces the stored map](/api/storage/update-file-metadata#overview), and a nonempty tag list replaces the old list. ## Keep completed work out of the active library \{#file-operations} Offer an archive action for documents the customer wants to keep, and a separate delete action for files they no longer need. Moving a document preserves its file ID; deleting it removes the file that saved references point to. ### Archive a completed document \{#move--rename-a-file} Prepare an `/archive` folder if your interface needs its folder entry. Move the selected notes out of the active folder and optionally give them a more useful name: [Request example: Move or rename a file](/api/storage/move-file#example-cookbook-core-platform-files-data-managing-05-request). 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. Reload the active folder and archive view. The document should leave the first and appear in the second. Keep application references attached to the existing file ID; its logical path changes when it moves. See [move-file](/api/storage/move-file). ### Delete a document the customer no longer needs \{#delete-a-file} Show the selected document's name and ask the customer to confirm deletion in your application. Then delete that file ID: [Request example: Delete a file](/api/storage/delete-file#example-cookbook-core-platform-files-data-managing-06-request). 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. Refresh the library after success. If the response is lost, inspect whether the original file remains before presenting a final outcome. Remove its download action from your application's saved records; a saved file ID is not a retained copy. See [delete-file](/api/storage/delete-file). ## Make room for another attachment \{#quota} When a customer cannot upload another document, show their current usage and let them choose files to remove: [Response example: Get storage usage and quota](/api/storage/get-storage-quota#example-cookbook-core-platform-files-data-managing-json-02-response). Example identifiers and values are illustrative; substitute authorized values. After deletion, check usage again and retry the intended upload when enough space is available. Quota preflight does not reserve space, so simultaneous uploads can change the remaining capacity. The byte totals are decimal strings. Preserve their integer precision when calculating the remaining space; file and folder counts are numbers. See [storage quota](/api/storage/get-storage-quota) for the full response. ## Investigate a library that looks out of sync \{#complete-state} If a customer reports that a moved file disappeared or usage looks wrong, inspect that user's [complete storage state](/api/storage/get-state) from a controlled support or diagnostic path. Compare the saved file ID, its current path and the remaining folder entries, then refresh the affected view. This operation returns every folder and file at once without pagination. Use paginated listings for the library interface. In a state response, folders are keyed by path and files by ID; the path inside a file record can change without changing its identity. --- URL: https://docs.travila.ai/core-platform/identity-access # Identity and access \{#identity-and-access} Choose the guide for your application’s authentication and access needs. * [Authentication and API keys](/core-platform/identity-access/authentication): connect signed-in users to their conversations. * [End users](/core-platform/identity-access/end-users): build an agent preferences screen. * [Scopes and permissions](/core-platform/identity-access/scopes-permissions): control access to application operations. * [Authentication reference](/api/authentication): inspect key configuration, headers and permission rules. --- URL: https://docs.travila.ai/core-platform/identity-access/authentication # Connect signed-in users to their conversations \{#authentication--api-keys} Let a person sign in to your application and reopen their saved conversations. This recipe has your backend request that person’s conversation list and return it to the application. Keep the secret key on the server; derive the user from the session your application has already authenticated. ## Before you start \{#choose-your-integration} Have your application’s sign-in flow, the account and API origin supplied by your administrator, and one controlled application user. Ask the administrator to issue a secret key with `conversations:read` and `users:impersonate` for this feature. Copy the key when it is created: its full value is shown once. Use the [key-management route enabled for your account](/api/authentication#managing-api-keys). The current public reference publishes no application key-management endpoint. A console session is separate from application authentication, and naming a key after a project or “test” does not create isolation. Keep this request in the backend unless your feature specifically needs the [direct browser/mobile variant](#2-client-app-with-a-publishable-key). ## Show the signed-in person’s conversations \{#1-backend-with-a-secret-key} 1. Store the issued secret key in your backend’s secret configuration. Keep it out of client code and shared request logs. 2. Resolve the person’s Travila user ID from your authenticated application session. Do not trust a user ID sent by a browser merely because your backend can impersonate users. 3. Call `list-threads` with that key and user. Replace `user_123` with the resolved identity and use your account’s API origin: List the authenticated user’s conversations with default paging. [Request example: List conversation threads](/api/conversations/list-threads#example-conversations-listThreads-request). 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. 4. Read the result using the [list-threads response schema](/api/conversations/list-threads) and show those conversations in your application. An empty list is a valid result for a new user. 5. Reopen the list as the same person and confirm it contains their expected conversations. Test another controlled user through the same application route so a cached response cannot show the first person’s work. The completed feature ties each displayed conversation list to the signed-in person. A successful request proves access for this operation, not that all other features are enabled. Continue with the [chat recipe](/managed-agents/conversations/build-chat-assistant) when the person must open a conversation and send another message; that feature also needs write permission. ## Recover a rejected request \{#error-responses-and-troubleshooting} Read the error before replacing a credential or widening access: | What failed | Recovery | | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `authenticated user_id is required` | Supply the user resolved from your application session in `X-On-Behalf-Of`. The secret key identifies the tenant, not the person. | | `insufficient_scope` | Check the feature’s approved read and impersonation grants with the administrator. Do not add a wildcard to make the request pass. | | Missing, expired, disabled or revoked key | Use the [key error reference](/api/authentication#authentication-errors) to correct the key or obtain its replacement. A revoked key cannot be restored. | | `429` or a temporary verification failure | Use bounded backoff and any returned retry guidance within your request deadline; stop and surface the failure when that deadline expires. | Retry the list read after resolving the identified problem. Keep application authorization checks: scope enforcement varies by operation. The accepted per-minute limit is not a guaranteed traffic or spending ceiling; hourly and burst settings are unsupported. Use the [current limit and error reference](/api/authentication#rate-limiting) when configuring production traffic. ## Variant: load the list directly in a browser or mobile app \{#2-client-app-with-a-publishable-key} Use this variant when the client must call Travila directly. It uses a publishable key and the signed-in user’s token; the server secret never ships to the client. 1. Have the administrator configure a publishable key for the accepted identity provider, issuer and audience using the [identity configuration reference](/api/authentication#create-a-publishable-key). The current provider allowlist does not accept Keycloak or arbitrary custom-JWKS providers. 2. Sign the person in through that configured provider and obtain its accepted user token. 3. Request the conversation list with both credentials: List the authenticated user’s conversations with default paging. [Request example: List conversation threads](/api/conversations/list-threads#example-conversations-listThreads-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: pk_your_key_here`; `Authorization: Bearer `; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. 4. Display the returned list for that session. If the token expired, refresh it through the sign-in provider; for issuer, audience or signature errors, correct the configured identity path using the [token error reference](/api/authentication#publishable-key-errors). The user comes from the validated token, so this path does not use `X-On-Behalf-Of`. Keep management actions on your backend: publishable-key creation filters do not uniformly apply to later key edits and operation checks. Review saved permissions using the [restriction reference](/api/authentication#publishable-key-restrictions). ## Replace a backend key while the application keeps working \{#key-rotation} For a planned replacement: 1. Issue the successor through the key-management route enabled for your account. Record the application and consumers that must switch. 2. Update each consumer’s secure configuration and run the permitted conversation-list request with the new key. 3. Confirm every consumer has switched, then revoke the predecessor or let its chosen grace period expire. The current rotation contract defaults to a 24-hour overlap and allows up to 720 hours. Revocation may not stop requests already in flight or immediately reach every cache. For suspected exposure, revoke the exposed credential promptly and recover its consumers. Publishable keys use a different replacement path: issue a new key, migrate clients, then revoke the old one. See the [replacement contract](/api/authentication#key-rotation) for those limits and the [authentication reference](/api/authentication) for the remaining shared configuration details. --- URL: https://docs.travila.ai/core-platform/identity-access/end-users # Build an agent preferences screen \{#manage-end-user-settings} Let a person choose the language their assistant uses and, if your application offers it, a preferred model. Start with those reversible preferences. Add location only for a feature that needs it and can explain its use; this API currently has no clear-location operation. After sign-in, load the profile, render saved choices with their inherited defaults, save only what the person changes, and read the profile back. Use the subsequent conversation to observe the result; model behavior can still differ from the saved preference. The end-user record holds those saved preferences. Identity claims may be copied from the accepted sign-in token; a profile can be empty until information has been captured or saved. The platform reads this record on every turn. Location and locale can inform context preparation when the corresponding capability is enabled. They do not guarantee that a model always uses the correct timezone or language. > **Info: Every call is scoped to the caller** > > These request bodies do not select a user. Use a publishable key with that user's accepted JWT, or a backend secret key with the permitted `X-On-Behalf-Of` header. Your backend must identify the user from its authenticated application session, not accept an arbitrary user ID from a client. ## 1. Load the saved settings and account defaults \{#read-the-profile} [Response example: Get the caller's end-user profile](/api/end-users/get-end-user#example-cookbook-core-platform-identity-access-end-users-json-01-response). Example identifiers and values are illustrative; substitute authorized values. Render the saved preferences and available account defaults. [An empty profile is a valid starting point](/api/end-users/get-end-user#overview) for the settings screen. ## 2. Save the user’s preferred language \{#update-locale} When the person chooses another language, send its BCP-47 tag below. Read the profile again to confirm the override. Offer “use sign-in language” by [clearing the override](/api/end-users/update-locale#overview) rather than guessing the identity-provider default. [Request example: Update the caller's locale override](/api/end-users/update-locale#example-cookbook-core-platform-identity-access-end-users-02-request). 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. **Response:** `{}` on success. Send an **empty string** to clear the override and fall back to the identity-provider locale: [Request example: Update the caller's locale override](/api/end-users/update-locale#example-cookbook-core-platform-identity-access-end-users-json-02-request). Example identifiers and values are illustrative; substitute authorized values. ## 3. Offer supported model and response preferences \{#update-default-generation-config} Expose only the supported preferences your application intends users to control. Save the selected values, then read the profile back. [A per-message or agent-profile choice can take precedence](/api/end-users/update-default-generation-config#overview), so explain why a conversation may use a different setting. [Request example: Update the caller's default generation config](/api/end-users/update-default-generation-config#example-cookbook-core-platform-identity-access-end-users-03-request). 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. **Response:** `{}` on success. ## Variant: remember a display preference \{#update-metadata} Use metadata for an application preference such as the compact display shown below. Start from the current profile, merge the changed value, and read it back; removing a key restores your application’s own fallback rather than assigning a privileged account state. User-editable key/value preferences. Never use this metadata as the authority for paid tiers, staff roles, access grants or onboarding completion; those require separately controlled records. [Request example: Update the caller's metadata](/api/end-users/update-metadata#example-cookbook-core-platform-identity-access-end-users-04-request). 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. **Response:** `{}` on success. [To delete a key explicitly](/api/end-users/update-metadata#overview): [Request example: Update the caller's metadata](/api/end-users/update-metadata#example-cookbook-core-platform-identity-access-end-users-json-05-request). Example identifiers and values are illustrative; substitute authorized values. ## Before adding location: explain retention and consent \{#location-consent-and-freshness} Coordinates are sensitive, and the current user record stores the submitted precise location. Weather results rounded to a grid do not mean the precise submitted location is absent from records or traces. Request location only for a clear user purpose, record capture time and distinguish it from lookup/cache time. The current public reference has no clear-location operation; do not promise that sending `(0, 0)` clears consent or location. Zero coordinates are geographically valid. ## Variant: use location for local-time context \{#update-location} [Request example: Update the caller's location](/api/end-users/update-location#example-cookbook-core-platform-identity-access-end-users-05-request). 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. **Response:** [Response example: Update the caller's location](/api/end-users/update-location#example-cookbook-core-platform-identity-access-end-users-json-06-response). Example identifiers and values are illustrative; substitute authorized values. **Do not send a timezone.** [Travila derives the IANA zone from the coordinates](/api/end-users/update-location#overview) and returns it in the response. This gives the agent context for phrases such as “this evening”; confirm the interpreted time before scheduling an important action. ## Continue to conversations and notification settings \{#related} * [Authentication](/core-platform/identity-access/authentication) — Firebase tokens, secret keys, and `X-On-Behalf-Of` * [Model Routing](/managed-agents/model-controls) — how [`defaultGenerationConfig`](/api/models/schema-1l1et4gp2i#response-field-defaultgenerationconfig) interacts with per-turn overrides * [Conversations](/managed-agents/conversations) — where the user context is applied * [Notifications](/core-platform/notifications) — the separate subscriber record used for delivery --- URL: https://docs.travila.ai/core-platform/identity-access/scopes-permissions # Control access with scopes \{#control-access-with-scopes} Build a backend that lists a signed-in person’s conversations without giving that feature a general-purpose credential. Keep privileged administration in a separate server path. This recipe uses the conversation read and impersonation permissions already documented below; add write access only if the same feature must send messages. Choose the minimum permissions your application needs. Scopes are labels attached to an API key; where an operation enforces its scope, a missing grant returns `403 insufficient_scope`. Enforcement currently varies by operation, so keep privileged calls behind your backend's access checks instead of relying on key scopes alone. ## Issue the credential for the feature \{#where-scopes-are-set} Scopes are set in the `permissions` field when a key is created or edited through the management interface enabled for your account. A valid credential can still be denied access to an operation that requires a scope it does not have. For the conversation-list recipe, request `conversations:read` and `users:impersonate`. The example below also grants `conversations:write` for the optional message-sending variant; omit that grant for a feature that only lists conversations. Example API-key permission configuration. * `name`: text backend-service. * `permissions[0]`: text conversations\:read. * `permissions[1]`: text conversations\:write. * `permissions[2]`: text users\:impersonate. ## Recipe: let a person list their conversations \{#select-permissions-for-the-operation} 1. List the actions the feature performs. Listing conversations needs `conversations:read`; a secret-key request for a person also needs `users:impersonate`. 2. Request those permissions through the key-management route enabled for your account. Avoid a wildcard merely to make a denied request disappear. 3. Resolve the user from your application’s authenticated session and call [`list-threads`](/core-platform/identity-access/authentication#1-backend-with-a-secret-key). 4. Check a permitted request and a denied action before exposing the backend route. Keep your application’s own authorization checks because enforcement varies across APIs. 5. If a request fails, use the [denial guidance](#per-endpoint-enforcement) to distinguish a missing scope from a wrong or expired credential. The result is a credential and backend route tied to a defined feature. Keys do not currently establish separate project or test/live isolation. A scope label does not validate a user ID supplied by an untrusted client. ## The users\:impersonate scope and X-On-Behalf-Of \{#the-usersimpersonate-scope-and-x-on-behalf-of} Most platform endpoints operate on a specific user's data. When calling with a secret key (`sk_*`), the `X-On-Behalf-Of` header is how you identify that user. The key must carry the `users:impersonate` scope, or the request fails with `403 insufficient_scope`. If the feature also sends messages, use the same resolved user with the additional `conversations:write` permission. This variant requires an existing conversation key: [Request example: Send a message to a conversation](/api/conversations/send-message#example-cookbook-core-platform-identity-access-scopes-permissions-01-request). 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. Request this scope when you create your key. Without it, an attempt to act on behalf of a user is rejected with a 403. For the full list of endpoints that require `X-On-Behalf-Of`, see [Acting as a user](/api/authentication#acting-as-a-user--x-on-behalf-of). ## Understand what a broader grant would allow \{#scope-matching-rules} Keep the conversation-list feature on its named permissions. A wildcard would also permit unrelated actions as those scopes are added; use a separate credential for a feature that needs broader access. See the [scope-matching reference](/api/authentication#key-types) for exact permission and wildcard behavior. ## Variant: move permitted user work into a client app \{#publishable-key-restrictions} Use a publishable key with the signed-in user’s JWT only for the user operations your client needs. Keep key management, billing and other administrative work on your backend; consult the [publishable-key restrictions](/api/authentication#publishable-key-restrictions) before choosing permissions. Later key updates and operation checks do not uniformly apply this filter. Review the saved permissions after an edit, restrict who can manage keys, and keep management calls behind your backend's access checks. The user JWT accompanying a publishable key identifies the user; it does not grant permission for every operation. ## Recover a denied request without widening access blindly \{#per-endpoint-enforcement} A valid key and JWT do not establish permission for every operation. A request can pass authentication and still fail because the key lacks the required scope. Always check the error body for `insufficient_scope` rather than assuming a `401` or `403` is a credential issue. If the error is `insufficient_scope`, compare the operation with the feature’s approved action list before changing the grant. If it reports expired or invalid credentials, recover authentication instead. Re-run the permitted request after the change and review the saved permissions; a successful edit is not proof that every operation enforces the intended restriction. ## Related \{#related} * [Authentication & API keys](/core-platform/identity-access/authentication) — complete a signed-in conversation request. * [Authentication reference](/api/authentication) — key configuration, permission rules, headers and errors. --- URL: https://docs.travila.ai/api/authentication # Authentication and key configuration reference \{#overview} Use this reference for credential configuration, required headers, key limits and authentication errors. Start with the [signed-in conversation recipe](/core-platform/identity-access/authentication) for a complete integration. This is a curated reference for shared authentication behavior. Exact operation request and response schemas remain in the [generated API reference](/api); this page does not publish key-management endpoints. ## Key management availability \{#managing-api-keys} Use the key-management surface enabled for your deployment. The current public reference does not publish application key-management endpoints; a signed-in dashboard session is distinct from application API authentication. Application keys identify the tenant in the current integration. Their names do not create separate project or test/live isolation. Keep key-management access restricted, and revoke or rotate a key explicitly when its value may have been exposed. Ask your account admin if you need a key issued, a scope added, or an existing key rotated. > **Caution** > > That dashboard session authenticates *you*. Use the documented application credential pair for public API calls. Session invalidation and token revocation depend on the identity provider and the platform's validation path; a signed token is not inherently irrevocable. See [Firebase session management](https://firebase.google.com/docs/auth/admin/manage-sessions) for the distinction between token expiry, refresh-token revocation and revocation checking. ## Application key types \{#key-types} | Type | Prefix | Use it from | Pairs with | | --------------- | ------ | ---------------------- | ----------------------------------------------------------------------------- | | **Secret** | `sk_*` | Your backend | [`X-On-Behalf-Of`](#acting-as-a-user--x-on-behalf-of), when acting for a user | | **Publishable** | `pk_*` | Client apps (iOS, web) | A user JWT, always | Every key carries a name, a description, a set of [scopes](/core-platform/identity-access/scopes-permissions), and an optional expiry. Each also has a short prefix (for example `sk_2hfK`) shown in the dashboard, so you can identify a key in logs without handling the full value. The full key value is shown once at creation and cannot be retrieved afterward. Store it through your approved secret-handling mechanism. Scope matching accepts an exact permission such as `conversations:read`, a prefix wildcard such as `users:*`, or the all-scopes wildcard `*`. Scope enforcement varies by operation; a matching key permission does not replace the application’s own authorization checks. ## Publishable-key identity configuration \{#create-a-publishable-key} Publishable keys are designed for client-side apps (iOS, web). They must always be paired with a user JWT, and require OIDC configuration so the platform can validate that JWT. When you create one, select an accepted provider and supply its issuer and audience. The API accepts only `firebase`, `auth0`, `okta`, `cognito` and `supabase`. It derives the verification-key URL from the validated provider configuration; supplying a custom JWKS URL does not enable another provider. | Field | Description | | ---------------- | --------------------------------------------------------------------------------------------------------------------- | | `provider` | Required provider identifier from the allowlist above | | `issuer` | Expected `iss` claim in the JWT | | `jwksUrl` | Derived verification-key URL; caller-supplied values do not override provider validation | | `audience` | Expected `aud` claim in the JWT | | `userIdClaim` | *(Optional)* JWT claim to extract the user ID from. Defaults to `sub` | | `requiredClaims` | *(Optional)* Map of claim names to expected values. Supports dot notation for nested claims (e.g., `firebase.tenant`) | > **Tip: OIDC Provider Examples** > > These are common provider configuration patterns, not a certification of every provider or token type. Qualify the issuer, audience, signing algorithm, key rotation and required claims for your deployment. Use the provider-issued token type accepted by that configuration. > > | Provider | `issuer` | `jwksUrl` | > | --------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------- | > | **Firebase** | `https://securetoken.google.com/` | `https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com` | > | **Auth0** | `https://.auth0.com/` | `https://.auth0.com/.well-known/jwks.json` | > | **Okta** | `https://.okta.com/oauth2/default` | `https://.okta.com/oauth2/default/v1/keys` | > | **AWS Cognito** | `https://cognito-idp..amazonaws.com/` | `https://cognito-idp..amazonaws.com//.well-known/jwks.json` | > > Keycloak is not currently accepted. The examples describe accepted issuer patterns and their derived URLs; they are not custom-JWKS configuration instructions. > > See [Build an AI chat assistant](/managed-agents/conversations/build-chat-assistant) for a client using one end to end. ### Publishable-key permission restrictions \{#publishable-key-restrictions} Do not give client keys management permissions. Creation removes `api_keys:*`, `webhooks:*`, `tenants:*`, `billing:*`, `system:*`, `users:impersonate` and `*` from publishable keys, but later updates and operation checks do not uniformly apply that filter. Review permissions after editing a key, restrict who can edit keys, and keep administrative operations behind your backend's access checks; a `pk_*` prefix alone is not a management-access boundary. For a worked example that selects only the permissions an application feature needs, follow [Control access with scopes](/core-platform/identity-access/scopes-permissions). ## User identity and operation scope \{#acting-as-a-user--x-on-behalf-of} > **Danger: Required on most endpoints, not optional** > > A secret key identifies your **tenant**, not a user. Most endpoints operate on a specific user's data and reject a request that doesn't identify one: > > Missing delegated user identity error. This example is an excerpt. Use the linked operation or model for its full format; error bodies can differ by operation and failure type. > > * `code`: text UNAUTHENTICATED. > * `message`: text authenticated user\_id is required. > > With an `sk_*` key, `X-On-Behalf-Of` is the **only** way to supply that user. If your very first call returns the 401 above, this header is what's missing — not your key. > > The key must also carry the `users:impersonate` scope, or the request fails with `403 insufficient_scope`. Ask for that scope when you request your key. Which endpoints need it: | Endpoints | `X-On-Behalf-Of` with `sk_*` | | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Conversations | **Required** | | Storage | **Required** | | Scheduler | Operation-specific: owner operations select a user; project teardown requires a backend request **without** this header. Requests without a user are also accepted on the current path, which uses the legacy `default` project. | | End User | **Required** | | Notifications — user-facing (inbox, preferences, push devices) | **Required** | | Notifications — subscriber-specific operations, including management reads/updates/deletes | **Required** when selecting a user | | Notifications — project configuration (workflows, providers, topics) | Follow the operation reference; `/manage/` alone does not establish scope | | Webhooks | Not needed — tenant-scoped | | Agent profiles, custom MCP configuration, project secrets | Key-only project/tenant operations in the current reference; use the operation's required permissions | | Evals | Reads, configuration and queue operations can use a bare key. `record-score` requires verified reviewer identity; a backend supplies permitted `X-On-Behalf-Of`. Supply reviewer identity for comment attribution too. See the [review recipe](/insights/evaluation/review). | Publishable keys (`pk_*`) never need it: the user comes from the accompanying JWT. Identify the user from your authenticated application session. Do not accept an arbitrary user ID from an untrusted client merely because your backend holds an impersonation-capable key. ## Key replacement and revocation \{#key-rotation} For planned replacement, issue the successor through your enabled management interface, update the application’s secure configuration, and make a permitted request from each consumer. Keep the old credential only for the overlap needed to finish that migration. For suspected exposure, prioritize revoking the exposed credential and recover the affected consumers. The current rotation contract issues a replacement key and sets the old one to expire after a grace period you choose — 24 hours by default, up to 720 hours (30 days). Both keys authenticate during that window, giving your consumers time to switch over. Verify that every consumer has switched before the old key expires. Revocation may not stop requests already in flight or immediately reach every cache. Once every consumer is on the new key, the old one expires on its own; revoke it early from the dashboard if you want it dead sooner. > **Caution** > > Publishable keys (`pk_*`) cannot be rotated this way. Issue a new one, migrate your clients, then revoke the old key. ## Rate-limit availability \{#rate-limiting} > **Caution: Availability and limits** > > The API accepts a per-minute request limit, but do not rely on that setting as a guaranteed rate or spending ceiling. Confirm your account's enforced limits and bound traffic in your application. Hourly and burst settings are not currently supported. > > An absent per-key limit does not mean free, unmetered or unlimited use. Admission limits, free allowances and provider spending budgets are separate controls. Your deployment may reject requests with `429` for other reasons. Apply bounded concurrency, deadlines and backoff in your client. ### Requested limit fields \{#requesting-a-limit} If you want a ceiling applied to a key, set `requests_per_minute` when the key is created or updated: Example rate-limit configuration. * `rate_limit.requests_per_minute`: number 1000. | Field | Status | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `requests_per_minute` | Positive values request a limit. Zero or omission on creation adds no per-key limit; on update it leaves an existing limit unchanged. An update cannot clear a limit with zero. | | `requests_per_hour` | Accepted by the API but **ignored** — no hourly window is applied. | | `burst_size` | Accepted by the API but **ignored** — no burst shaping is applied. | The last two exist in the request schema and will not error, but setting them has no effect. ### Rate-limit response headers \{#response-headers} When supported and emitted by the deployment, inspect: | Header | Description | | ----------------------- | ------------------------------------------------------- | | `X-RateLimit-Limit` | Maximum requests in the current window | | `X-RateLimit-Remaining` | Requests remaining in the current window | | `X-RateLimit-Reset` | Unix timestamp when the window resets | | `Retry-After` | When present, seconds until the next request is allowed | A throttled request can return **HTTP 429 (Too Many Requests)**. Headers may be absent; do not infer unlimited capacity from their absence. Honor `Retry-After` when present and stop retrying at your operation deadline. ## Authentication error formats \{#error-responses-and-troubleshooting} Use the HTTP status and the error fields described below to choose the recovery action. Key-verification errors can include `denialReason`; other authentication errors use the shapes shown for that error. ### Application key errors \{#authentication-errors} | Error | HTTP Status | Cause | Fix | | --------------------- | ----------- | ---------------------------------- | ---------------------------------------------------------------------- | | `missing_credentials` | 401 | No API key or JWT in request | Add `X-API-Key` header | | `api_key_not_found` | 401 | Key doesn't exist | Verify the key value is correct | | `api_key_expired` | 401 | Key has passed its expiration date | Create a new key | | `api_key_disabled` | 401 | Key is disabled | Contact your admin to re-enable | | `api_key_revoked` | 401 | Key has been revoked | Create a new key — revocation is permanent | | `api_key_invalid` | 401 | Generic invalid key | Verify the key format (`sk_*` or `pk_*`) | | `insufficient_scope` | 403 | Key lacks the required scope | Update the key's permissions or create a new key with the needed scope | | `rate_limited` | 429 | Key hit its rate limit | Wait for the reset window or increase the rate limit | ### User token errors \{#publishable-key-errors} | Error | HTTP Status | Cause | Fix | | ------------------------------ | ----------- | --------------------------------------- | -------------------------------------------------------------------------- | | `publishable_key_requires_jwt` | 401 | `pk_*` key used without a user JWT | Add `Authorization: Bearer ` header | | `jwt_expired` | 401 | User JWT has expired | Refresh the JWT token | | `jwt_malformed` | 401 | JWT is malformed | Verify the JWT structure | | `jwt_invalid_signature` | 401 | JWT signature verification failed | Ensure the JWT was issued by the correct provider | | `jwt_invalid_issuer` | 401 | JWT issuer doesn't match expected value | Check the OIDC issuer config on the publishable key | | `jwt_invalid_audience` | 401 | JWT audience doesn't match | Check the OIDC audience config on the publishable key | | `user_id_claim_not_found` | 401 | JWT missing the user ID claim | Ensure your JWT includes the `sub` claim (or the configured `userIdClaim`) | ### Verification service errors \{#server-errors} | Error | HTTP Status | Cause | Fix | | ------------------------------- | ----------- | -------------------------------------- | ---------------------------------------------------------- | | `denialReason: "unkey_error"` | 500 | Key verification failed | Retry with bounded backoff; if persistent, contact support | | `misconfigured_publishable_key` | 500 | Publishable key missing OIDC metadata | Recreate the key with `publishableConfig.oidc` | | `oidc_not_configured` | 500 | User sign-in configuration unavailable | Contact platform support | In the inspected contract, key-verification failures can return HTTP 500 with `denialReason: "unkey_error"`. Transport failures reaching verification return a separate 503 response; do not assume every failure uses the same JSON shape. ## Request headers \{#headers} | Header | Required | Description | | ---------------- | ------------------------------------------ | -------------------------------------------------------------------- | | `X-API-Key` | Yes | Your API key (`sk_*` or `pk_*`) | | `Content-Type` | Yes | Always `application/json` | | `Authorization` | For `pk_*` keys | `Bearer ` — required with publishable keys | | `X-On-Behalf-Of` | Required for user-scoped calls with `sk_*` | The application user to act for (requires `users:impersonate` scope) | Use the [common JSON contract](/api#request-format) for field names, omitted values and decimal-string 64-bit integers. --- URL: https://docs.travila.ai/core-platform/notifications # Reach users on every channel \{#reach-users-on-every-channel} Welcome a new user, tell them an update is ready, and keep that notice available when they return. Start with an in-app welcome message, then add the channels and preferences your application needs. ## Choose the customer interaction \{#start-here} | Build this feature | Recipe | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Welcome a new user in your application | [Prepare and deliver a welcome notification](/core-platform/notifications/administration#get-started) | | Tell a user that a conversation update is ready | [Send the completed update’s notice](/core-platform/notifications/sending), with [push enrollment](/core-platform/notifications/push) when needed | | Keep notices available after the user leaves the screen | [Build an in-app inbox](/core-platform/notifications/inbox) | | Let users choose message types and channels | [Build notification settings](/core-platform/notifications/preferences) | | Let users follow a recurring update | [Build topic subscriptions](/core-platform/notifications/topics) | ## Before you start \{#related} Have an [authenticated application user](/core-platform/identity-access/authentication) and a backend that authorizes who may configure or send notifications. Management routes do not enforce a separate administrator role, and subscriber operations still select their user through authentication; follow the [administration prerequisites](/core-platform/notifications/administration). The in-app recipe needs no external email or push account. For another channel, prepare its provider and device or contact information using the linked recipe. Use the [Notification API reference](/api/notifications) for exact request fields and the [JSON contract](/api#request-format) for response presence rules. ## Deliver the first welcome message \{#how-it-works} 1. [Prepare the welcome template](/core-platform/notifications/administration#workflows) and connect it to the intended recipient. 2. Trigger it from your backend after the user’s application enrollment succeeds. Save the returned transaction reference. 3. [Load that user’s inbox](/core-platform/notifications/inbox#get-inbox-feed) and display the welcome message. 4. Let the user open the intended screen, mark the notice read and archive it. Reopen the app to confirm its saved state. 5. Add [notification preferences](/core-platform/notifications/preferences), then connect extra delivery channels if the application needs them. The feature works when the intended user can find the notice and complete its action. If it does not arrive, [follow the original delivery](/core-platform/notifications/administration#delivery-status) before sending another: a trigger acknowledgement is not arrival. When the recipient is your backend rather than a person, use the [webhook recipe](/integrations/webhooks). --- URL: https://docs.travila.ai/core-platform/notifications/administration # Welcome a new user with an in-app message \{#manage-workflows-subscribers-and-providers} After a person finishes signing up, leave a welcome message they can find when they return to your application. Prepare one template, enroll that person as a notification recipient, send the welcome after signup succeeds and confirm it appears in their inbox. Start with in-app delivery; it needs no external email or push account. ## Before you start \{#get-started} Have a backend credential, one authenticated application user and the completed signup event that should trigger the welcome. Step 4 connects the message to the user’s inbox. Your application must authorize who can configure or send notifications: these management calls accept a verified key or configured standalone JWT without a separate administrator-role check. Keep configuration and sending in the backend. Subscriber reads, updates and deletion select the user through authentication; `/manage/` does not grant access to every user. The examples below use `user-1` for one controlled application user. Confirm which notification environment your account edits. These calls can change production directly; separate development and production notification environments are account-dependent. ## 1. Prepare the welcome message \{#workflows} Create a workflow using [`manage/create-workflow`](/api/notifications/create-workflow). This existing in-app definition welcomes a coaching-app user; change its wording for your application while retaining the provider’s supported structure: Create the in-app welcome definition from the administration recipe; provider JSON is passed through. [Request example: Create a notification workflow](/api/notifications/create-workflow#example-notifications-createWorkflow-request). Example identifiers and values are illustrative; substitute authorized values. The response returns the stored [`workflow`](/api/notifications/create-workflow#response-field-workflow) definition. Save the workflow/trigger identifier you will send; use [list-workflows](/api/notifications/list-workflows) if you need to discover its valid identifier. Workflow definitions are opaque provider JSON—the Travila API passes them through rather than defining their delivery-step schema. The template in this recipe contains its welcome text directly, so its send request does not need message variables. ## 2. Enroll the same application user \{#subscriber-management} A subscriber is the notification record for your application user. Use [`manage/get-subscriber`](/api/notifications/get-subscriber), authenticated as `user-1`, to check whether it already exists. This read takes `{}`; a backend selects the user with permitted `X-On-Behalf-Of`, not a user ID in the body. Push registration may already have created the record. For a new recipient, call [`manage/create-subscriber`](/api/notifications/create-subscriber) with your application’s user identity: [Request example: Create a notification subscriber](/api/notifications/create-subscriber#example-cookbook-core-platform-notifications-administration-json-02-request). Example identifiers and values are illustrative; substitute authorized values. Keep using `user-1` when sending and when that person opens the inbox. The returned [`novuSubscriberId`](/api/notifications/create-subscriber#response-field-novusubscriberid) is an opaque provider reference, not a replacement for your application user ID. If creation’s response is lost, inspect the same user’s subscriber before trying to enroll them again. ## 3. Send after signup succeeds \{#send-welcome} Once your application has confirmed signup, trigger the prepared welcome from your backend. Replace the sample workflow identifier with the one saved in step 1; the recipient must be the user enrolled in step 2. Trigger the prepared welcome workflow for an enrolled user; replace the workflow and user identifiers. [Request example: Send a notification to a user](/api/notifications/send-notification#example-notifications-sendNotification-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. Inspect [`acknowledged`](/api/notifications/send-notification#response-field-acknowledged), the returned [`transactionId`](/api/notifications/send-notification#response-field-transactionid) and any errors. Save that transaction with the application’s signup event. Descriptive status text such as `processed` means accepted for processing, not delivered. A lost response does not prove that sending failed. Reconcile the original send before issuing a replacement; an optional caller-supplied transaction ID requires a qualified retry contract. Use the [sending recipe](/core-platform/notifications/sending#send-to-one-user) and [send reference](/api/notifications/send-notification) for those boundaries. ## 4. Confirm the person can read the welcome \{#delivery-status} Sign in as the same controlled user and [load their inbox](/core-platform/notifications/inbox#get-inbox-feed). Confirm the welcome appears, then open or mark it read and reopen the app to check the saved state. The feature is complete when the intended person can find the welcome—not when the trigger request returns successfully. If the message is missing, use [`get-delivery-status`](/api/notifications/get-delivery-status) with the saved transaction ID. Check the configured in-app step, the selected recipient and their [preferences](/core-platform/notifications/preferences) before sending another message. For several missing notices, inspect a bounded window through [notification activity](/api/notifications/get-notification-activity). Use its [filter contract](/api/notifications/get-notification-activity#overview) and keep successful recipients usable while investigating. ## Change the welcome without dropping other delivery steps \{#update-a-workflow} [Read the current workflow](/api/notifications/get-workflow), change its wording, then [submit the complete definition](/api/notifications/update-workflow). The supplied definition replaces the stored one; retain every step your application still needs. Send it to a controlled user and verify the new message. Where your account supports separate notification environments, [inspect pending changes](/api/notifications/get-pending-changes) and [promote the selected change](/api/notifications/promote-change) after that test. Bulk promotion can partially succeed; omitting [`changeIds`](/api/notifications/promote-all-changes#request-field-changeids) or sending an empty list selects all pending changes. Inspect each result and recover failed changes individually before treating the rollout as complete. If you retire a template, stop triggering it before [deleting it](/api/notifications/delete-workflow). Deletion does not cancel notices already in flight; [cancel a pending send](/core-platform/notifications/sending#cancel-a-pending-notification) separately using its transaction. ## Variant: add email or push after the inbox works \{#provider-configuration} Obtain credentials for the extra delivery channel and [configure that provider](/api/notifications/configure-provider). Add its supported step to the complete workflow. Email needs the recipient’s address; push needs a [registered device](/core-platform/notifications/push). Update contact details through the [subscriber-data operation](/api/notifications/update-subscriber-data), then send a controlled welcome and verify each intended channel. After changing credentials, test delivery to an already enrolled user. Follow [provider configuration outcomes](/api/notifications/configure-provider#overview) if configuration fails; a status read alone does not prove arrival. ## Remove enrollment when the person leaves your application \{#delete-the-callers-subscriber} Request [subscriber deletion](/api/notifications/delete-subscriber) while authenticated as the departing user, then read back that subscriber to confirm the outcome. Use the [subscriber deletion outcome contract](/api/notifications/delete-subscriber#overview) when the result is absent or uncertain; confirm the read-back before reporting cleanup complete. Removing this enrollment does not erase the application’s user record, every queued notice or external copy. Track those account-cleanup actions separately. For temporary channel choices or device sign-out, use [preferences](/core-platform/notifications/preferences) or [device removal](/core-platform/notifications/push#unregister-a-device) instead. --- URL: https://docs.travila.ai/core-platform/notifications/inbox # Build an in-app inbox \{#build-an-in-app-inbox} Use this recipe for a notification center where a person can see a new coaching update, read it, open its conversation and clear it without losing the underlying message history. Build the REST inbox first: load the first feed page, show the unseen badge, mark messages as the person reads them, and offer archive/restore. Add the live connection after those actions work. A socket outage then affects freshness without preventing the person from opening or managing their inbox. Before starting, [configure an in-app workflow](/core-platform/notifications/administration#get-started) and [authenticate the user](/core-platform/identity-access/authentication). Send an example notification so the completed inbox has an entry to display. ## 1. Show the user’s current notifications \{#get-inbox-feed} Load page 1 after sign-in and render each entry with its text and supported actions. Keep both message and notification identifiers: later actions use different identifiers. Offer another page while [`hasMore`](/api/notifications/get-inbox-feed#response-field-hasmore) is true; use the archive filter for a separate archive view. Request example: [Get inbox feed messages](/api/notifications/get-inbox-feed) · [Request fields](/api/notifications/get-inbox-feed#request). See [Get inbox feed messages](/api/notifications/get-inbox-feed#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `page`: number 1. * `pageSize`: number 20. Use the [feed filters and pagination contract](/api/notifications/get-inbox-feed#overview) when adding the archive view: Request example: [Get inbox feed messages](/api/notifications/get-inbox-feed) · [Request fields](/api/notifications/get-inbox-feed#request). See [Get inbox feed messages](/api/notifications/get-inbox-feed#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `page`: number 1. * `pageSize`: number 20. * `filter.archived`: boolean true. Keep the live and archive views distinct; see [archive filtering](/api/notifications/get-inbox-feed#overview). **Response:** Response example: [Get inbox feed messages](/api/notifications/get-inbox-feed) · [Response fields](/api/notifications/get-inbox-feed#responses). See [Get inbox feed messages](/api/notifications/get-inbox-feed#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `messages[0].messageId`: text 69c0df5391079c0a4596f7d3. * `messages[0].notificationId`: text 69c0df5291079c0a4596f79b. * `messages[0].title`: text Weekly Check-in. * `messages[0].body`: text Time to review your progress.. * `messages[0].data.title`: text Weekly Check-in. * `messages[0].data.body`: text Time to review your progress.. * `messages[0].data.deep_link`: text socayo://screen?name=weekly. * `messages[0].deepLink`: text socayo://screen?name=weekly. * `messages[0].status`: text MESSAGE\_STATUS\_UNSEEN. * `messages[0].createdAt`: text 2026-03-23T06:36:03.578Z. * `totalCount`: number 6. * `page`: number 1. * `pageSize`: number 20. Render missing optional values using the [feed presence rules](/api/notifications/get-inbox-feed#overview). ## 2. Add a badge without loading every message \{#get-unseen-count} Use this count for the app’s inbox badge. It is a bounded indicator, not the number of rows you must download. Refresh it after read/archive changes and when a live update arrives. **Response:** Response example: [Get unseen and unread inbox counts](/api/notifications/get-inbox-unseen-count) · [Response fields](/api/notifications/get-inbox-unseen-count#responses). See [Get unseen and unread inbox counts](/api/notifications/get-inbox-unseen-count#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `unseenCount`: number 3. * `unreadCount`: number 5. Use the [bounded badge-count contract](/api/notifications/get-inbox-unseen-count#overview) to choose the badge label. ## 3. Keep read and seen state in sync with the user \{#mark-messages} Mark a message seen when your app shows it and read when the user reads it, according to your interface’s meaning. Send the returned message identifier; use the all-message operation only for an explicit action whose scope your interface explains. Mark a single message: Request example: [Mark a single inbox message](/api/notifications/mark-inbox-message-as) · [Request fields](/api/notifications/mark-inbox-message-as#request). See [Mark a single inbox message](/api/notifications/mark-inbox-message-as#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `messageId`: text msg\_123. * `markAs`: text MESSAGE\_STATUS\_READ. **Response:** Response example: [Mark a single inbox message](/api/notifications/mark-inbox-message-as) · [Response fields](/api/notifications/mark-inbox-message-as#responses). See [Mark a single inbox message](/api/notifications/mark-inbox-message-as#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `messages[0].messageId`: text msg\_123. * `messages[0].channel`: text in\_app. * `messages[0].seen`: boolean true. * `messages[0].read`: boolean true. * `messages[0].content`: text Time to review your progress.. * `messages[0].status`: text sent. * `messages[0].createdAt`: text 2026-03-23T06:36:03.578Z. * `messages[0].lastSeenDate`: text 2026-03-23T10:24:35.518Z. Confirm the returned [`read`](/api/models/schema-ojt6e86adl#response-field-read) state before treating the entry as read. An absent value means false; HTTP success or a seen flag alone is not that confirmation. Mark all messages: Request example: [Mark all inbox messages](/api/notifications/mark-all-inbox-messages-as) · [Request fields](/api/notifications/mark-all-inbox-messages-as#request). See [Mark all inbox messages](/api/notifications/mark-all-inbox-messages-as#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `markAs`: text MESSAGE\_STATUS\_SEEN. **Response:** Response example: [Mark all inbox messages](/api/notifications/mark-all-inbox-messages-as) · [Response fields](/api/notifications/mark-all-inbox-messages-as#responses). See [Mark all inbox messages](/api/notifications/mark-all-inbox-messages-as#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `updatedCount`: number 5. Choose the [read/seen status](/api/notifications/inbox#inbox-status) that matches the user action. ## 4. Let the user clear and restore a notification \{#archive-messages} Archiving hides a message from the default feed but keeps it — unlike `delete-inbox-message`, it is reversible. Use the notification identifier from the selected feed entry for archive/restore; [identifier rules](/api/notifications/inbox#inbox-identifiers) distinguish it from a message identifier. Request example: [Archive an inbox message](/api/notifications/archive-inbox-message) · [Request fields](/api/notifications/archive-inbox-message#request). See [Archive an inbox message](/api/notifications/archive-inbox-message#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `notificationId`: text 69c0df5291079c0a4596f79b. **Response:** Response example: [Archive an inbox message](/api/notifications/archive-inbox-message) · [Response fields](/api/notifications/archive-inbox-message#responses). See [Archive an inbox message](/api/notifications/archive-inbox-message#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `status.acknowledged`: boolean true. * `status.status`: text archived. Restore it with the mirror call: Request example: [Unarchive an inbox message](/api/notifications/unarchive-inbox-message) · [Request fields](/api/notifications/unarchive-inbox-message#request). See [Unarchive an inbox message](/api/notifications/unarchive-inbox-message#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `notificationId`: text 69c0df5291079c0a4596f79b. **Response:** the same envelope, with `status: "unarchived"`. After an uncertain archive or restore, refresh the entry and apply only the user’s current choice. See [archive outcomes](/api/notifications/inbox#inbox-archive). ## Variant: clear all read notifications \{#archive-in-bulk} Clear the whole inbox, or just the messages the user has already read — the second is what a "clear read" button should call. Request example: [Archive all inbox messages](/api/notifications/archive-all-inbox-messages) · [Request fields](/api/notifications/archive-all-inbox-messages#request). See [Archive all inbox messages](/api/notifications/archive-all-inbox-messages#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `(root)`: empty object. **Response:** Response example: [Archive all inbox messages](/api/notifications/archive-all-inbox-messages) · [Response fields](/api/notifications/archive-all-inbox-messages#responses). See [Archive all inbox messages](/api/notifications/archive-all-inbox-messages#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `archivedCount`: number 12. Request example: [Archive all read inbox messages](/api/notifications/archive-all-read-inbox-messages) · [Request fields](/api/notifications/archive-all-read-inbox-messages#request). See [Archive all read inbox messages](/api/notifications/archive-all-read-inbox-messages#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `(root)`: empty object. **Response:** Response example: [Archive all read inbox messages](/api/notifications/archive-all-read-inbox-messages) · [Response fields](/api/notifications/archive-all-read-inbox-messages#responses). See [Archive all read inbox messages](/api/notifications/archive-all-read-inbox-messages#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `archivedCount`: number 7. To clear one group of notices, use the [tag filter](/api/notifications/inbox#inbox-archive): Request example: [Archive all read inbox messages](/api/notifications/archive-all-read-inbox-messages) · [Request fields](/api/notifications/archive-all-read-inbox-messages#request). See [Archive all read inbox messages](/api/notifications/archive-all-read-inbox-messages#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `tags[0]`: text coaching. * `tags[1]`: text reminders. ## Variant: permanently remove an inbox entry \{#delete-inbox-message} Use deletion only when the user chooses to remove this inbox entry permanently. Prefer archive for ordinary “clear” behavior because it can be undone. Refresh the feed after deletion; the action does not delete the conversation or undo any business action represented by the notice. Request example: [Delete an inbox message](/api/notifications/delete-inbox-message) · [Request fields](/api/notifications/delete-inbox-message#request). See [Delete an inbox message](/api/notifications/delete-inbox-message#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `messageId`: text msg\_123. **Response:** Response example: [Delete an inbox message](/api/notifications/delete-inbox-message) · [Response fields](/api/notifications/delete-inbox-message#responses). See [Delete an inbox message](/api/notifications/delete-inbox-message#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `status.acknowledged`: boolean true. * `status.status`: text deleted. ## 5. Connect a notification action to its business result \{#message-actions} For an “open conversation” or other action, validate the destination and the current user’s access. If the action performs business work, complete that work first, then acknowledge the inbox action. Keep its operation reference so a lost inbox update cannot cause the work to run twice. Render only the actions supplied by the selected notice; see the [action payload contract](/api/notifications/inbox#inbox-actions): Message excerpt: [Inbox message fields](/api/models/schema-1kescd68ar#response). See [InboxMessage](/api/models/schema-1kescd68ar#response) for the full field contract. This excerpt illustrates the relevant choices; replace identifiers with your own authorized values. * `actions[0].actionId`: text log-workout. * `actions[0].label`: text Log it. * `actions[0].url`: text travila://workout/new. * `actions[0].isPrimary`: boolean true. * `actions[0].completed`: boolean false. When the user taps an action, perform its authorized business operation first. After that operation reports success, mark the inbox action complete so other devices can show the result. An inbox acknowledgment neither performs nor rolls back the business operation; refresh the inbox after a lost acknowledgment; do not repeat the business operation just to update the inbox. Request example: [Complete an inbox message action](/api/notifications/complete-inbox-action) · [Request fields](/api/notifications/complete-inbox-action#request). See [Complete an inbox message action](/api/notifications/complete-inbox-action#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `notificationId`: text 69c0df5291079c0a4596f79b. * `actionType`: text ACTION\_TYPE\_PRIMARY. **Response:** Response example: [Complete an inbox message action](/api/notifications/complete-inbox-action) · [Response fields](/api/notifications/complete-inbox-action#responses). See [Complete an inbox message action](/api/notifications/complete-inbox-action#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `status.acknowledged`: boolean true. * `status.status`: text completed. Offer reversal only for the inbox completion marker. Business compensation is a separate user action; see [action states](/api/notifications/inbox#inbox-actions): Request example: [Revert an inbox message action](/api/notifications/revert-inbox-action) · [Request fields](/api/notifications/revert-inbox-action#request). See [Revert an inbox message action](/api/notifications/revert-inbox-action#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `notificationId`: text 69c0df5291079c0a4596f79b. * `actionType`: text ACTION\_TYPE\_PRIMARY. **Response:** the same envelope, with `status: "reverted"` and the action back in its pending state. ## 6. Obtain a session for live updates \{#get-inbox-session} Get a session token and WebSocket URL for real-time inbox updates. Request example: [Get an inbox session token](/api/notifications/get-inbox-session) · [Request fields](/api/notifications/get-inbox-session#request). See [Get an inbox session token](/api/notifications/get-inbox-session#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `(root)`: empty object. **Response:** Response example: [Get an inbox session token](/api/notifications/get-inbox-session) · [Response fields](/api/notifications/get-inbox-session#responses). See [Get an inbox session token](/api/notifications/get-inbox-session#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `token`: text eyJhbGciOiJIUzI1NiIs.... * `socketUrl`: text wss\://inbox.travila.ai. * `expiresIn`: text 1296000. Use the returned connection details following the [session contract](/api/notifications/inbox#inbox-session). ## 7. Refresh the inbox as messages arrive \{#real-time-inbox-updates} Connect with the supported client and refresh the feed and badge when an update arrives. The [session and event reference](/api/notifications/inbox#inbox-session) defines connection fields and event names. **Resilience.** If the socket fails to connect or drops, reconnect with exponential backoff (a handful of attempts), and while disconnected fall back to polling [`get-inbox-unseen-count`](#get-unseen-count) every \~30 seconds so the badge stays roughly current. Use the returned [`expiresIn`](/api/notifications/get-inbox-session#response-field-expiresin) to schedule renewal and call `get-inbox-session` again after expiry. A socket/session failure need not prevent using the authenticated REST feed. ## Finish the interaction and clear the inbox on sign-out \{#actions-and-sign-out} Mark an inbox action complete only after its underlying business operation succeeds. Reading a message or opening a deep link is not proof the requested action ran. Mark-all operations can affect more than the visible page; label their scope clearly. Validate deep links against an allowlist, reauthenticate on cold start, and require explicit user intent before sending a prompt or executing an action. Clear private feed state and close the socket on sign-out. --- URL: https://docs.travila.ai/core-platform/notifications/preferences # Manage notification preferences \{#manage-notification-preferences} Build a settings screen where a user can turn off push across the app while keeping in-app updates, then make a narrower choice for one notification type. Start by reading saved preferences, render inherited values distinctly, send only changed choices, and read back the result before treating a failed or partial save as complete. Show which choices apply app-wide and which apply to one notification type. Explain any critical-message policy separately; see [preference inheritance](/api/notifications/preferences#preference-policy). ## 1. Load saved choices before rendering settings \{#read-preferences} Request example: [Get notification preferences](/api/notifications/get-preferences) · [Request fields](/api/notifications/get-preferences#request). See [Get notification preferences](/api/notifications/get-preferences#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `(root)`: empty object. **Response:** Response example: [Get notification preferences](/api/notifications/get-preferences) · [Response fields](/api/notifications/get-preferences#responses). See [Get notification preferences](/api/notifications/get-preferences#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `global.enabled`: boolean true. * `global.channels.inApp`: boolean true. * `global.channels.push`: boolean true. * `global.channels.email`: boolean false. * `workflows[0].workflowId`: text promotional. * `workflows[0].workflowName`: text Promotional. * `workflows[0].critical`: boolean false. * `workflows[0].tags[0]`: text marketing. * `workflows[0].channels.inApp`: boolean true. * `workflows[0].channels.push`: boolean false. * `workflows[1].workflowId`: text weekly-summary. * `workflows[1].workflowName`: text Weekly Summary. * `workflows[1].critical`: boolean false. * `workflows[1].channels.inApp`: boolean true. * `workflows[1].channels.push`: boolean true. Keep inherited and explicit choices distinct in the controls; follow the [presence rules](/api/notifications/preferences#preference-policy). ## 2. Turn push off across ordinary notifications \{#update-the-global-toggles} Send only the choices the user changed, following the [update contract](/api/notifications/preferences#preference-updates): Request example: [Update global notification preferences](/api/notifications/update-global-preference) · [Request fields](/api/notifications/update-global-preference#request). See [Update global notification preferences](/api/notifications/update-global-preference#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `channels.push`: boolean false. **Response:** `{}` on success. Reload preferences to confirm the saved selections. Confirm the saved ordinary-notification preference and leave other choices intact. [Critical-message handling](/api/notifications/preferences#preference-policy) is a separate policy. ## Variant: change one kind of notification \{#update-one-workflow} Offer this choice when a user wants fewer messages of one kind without changing all notifications. Use the workflow ID returned by the loaded settings, preserve its untouched channels, and leave broader channel preferences in force. Request example: [Update per-workflow notification preferences](/api/notifications/update-workflow-preference) · [Request fields](/api/notifications/update-workflow-preference#request). See [Update per-workflow notification preferences](/api/notifications/update-workflow-preference#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `workflowId`: text promotional. * `channels.push`: boolean false. * `channels.email`: boolean false. **Response:** `{}` on success. Reload preferences to confirm the saved selections. Use the [workflow-specific update contract](/api/notifications/preferences#preference-updates) for this row. ## 3. Save several edited rows together \{#update-many-workflows-at-once} A preferences screen usually lets the user flip several rows before hitting save. Send them in one call rather than one request per row — up to 100 workflows. Request example: [Bulk-update per-workflow preferences](/api/notifications/bulk-update-preferences) · [Request fields](/api/notifications/bulk-update-preferences#request). See [Bulk-update per-workflow preferences](/api/notifications/bulk-update-preferences#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `entries[0].workflowId`: text promotional. * `entries[0].channels.push`: boolean false. * `entries[1].workflowId`: text weekly-summary. * `entries[1].channels.inApp`: boolean true. * `entries[1].channels.push`: boolean true. **Response:** Response example: [Bulk-update per-workflow preferences](/api/notifications/bulk-update-preferences) · [Response fields](/api/notifications/bulk-update-preferences#responses). See [Bulk-update per-workflow preferences](/api/notifications/bulk-update-preferences#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `updatedCount`: number 2. Compare the saved rows with the intended changes and follow [partial-update handling](/api/notifications/preferences#preference-updates) before showing success. ## 4. Confirm the saved choices and recover partial failure \{#save-and-recover-changes} Check the returned count after updating multiple workflows. If only some changed, refetch the affected preferences, show the incomplete result and retry only the choices still needed. If the UI updates optimistically, restore or refetch failed rows and prevent an older response from overwriting a newer user choice. Disabling a preference cannot recall a notification already accepted for delivery. ## Reference: map channel values to settings controls \{#channel-names} Map each control to the [preference channel keys](/api/notifications/preferences#channel-names); channel registration and activity filters use their own documented spellings. --- URL: https://docs.travila.ai/core-platform/notifications/push # Keep push notifications attached to the signed-in user \{#register-push-devices} Keep a coaching update attached to the right person when a phone signs in, rotates its push token or switches accounts. Enroll the signed-in user’s device, send a test update, then remove that enrollment on sign-out. Before starting, obtain the push token with the client SDK and the user’s device permission, and [configure the matching delivery channel](/core-platform/notifications/administration#provider-configuration) on your backend. ## Recipe: receive an update on the signed-in device \{#push-device-registration} Build the device enrollment part of a coaching-update notification. The device must be registered to the person who is signed in when it receives the notice—not to whoever last used the phone. 1. Ask for device notification permission for the feature the user enabled, then obtain the current FCM token with the client SDK. 2. Register that token under the signed-in user below. Keep it out of logs. 3. Read registered channels and confirm push enrollment. If it is absent, repair registration before continuing. Then send a controlled [test notice](/core-platform/notifications/sending#send-to-one-user). Confirm it reaches the intended device, then test opening its destination. 4. Keep registration current when the SDK rotates the token. 5. On sign-out or account switch, remove the old user’s binding before registering the next user. Follow the recovery steps below if removal is uncertain. Registration is setup; it does not prove provider delivery or that the device displayed a notice. ### Register after sign-in or token rotation \{#register-a-device} Request example: [Register a push notification device](/api/notifications/register-push-device) · [Request fields](/api/notifications/register-push-device#request). See [Register a push notification device](/api/notifications/register-push-device#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `fcmToken`: text firebase-cloud-messaging-token. * `platform`: text PLATFORM\_IOS. * `deviceId`: text device-unique-id. **Response:** Response example: [Register a push notification device](/api/notifications/register-push-device) · [Response fields](/api/notifications/register-push-device#responses). See [Register a push notification device](/api/notifications/register-push-device#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `subscriberId`: text user\_123. * `success`: boolean true. ### Check enrollment before testing delivery \{#get-registered-channels} Check which notification channels are available for the current user. Request example: [Get registered notification channels](/api/notifications/get-registered-channels) · [Request fields](/api/notifications/get-registered-channels#request). See [Get registered notification channels](/api/notifications/get-registered-channels#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `(root)`: empty object. **Response:** Response example: [Get registered notification channels](/api/notifications/get-registered-channels) · [Response fields](/api/notifications/get-registered-channels#responses). See [Get registered notification channels](/api/notifications/get-registered-channels#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `channels[0].channel`: text CHANNEL\_IN\_APP. * `channels[0].registered`: boolean true. * `channels[0].credentialCount`: number 1. * `channels[1].channel`: text CHANNEL\_PUSH. * `channels[2].channel`: text CHANNEL\_EMAIL. * `channels[2].registered`: boolean true. * `channels[2].credentialCount`: number 1. * `channels[3].channel`: text CHANNEL\_SMS. This example shows push enrollment is absent. Repair enrollment for the intended user and current device before sending a test; see [registration fields](/api/notifications/delivery#device-registration). Registration alone does not prove delivery. ### Remove this device before account switch \{#unregister-a-device} Request example: [Unregister a push notification device](/api/notifications/unregister-push-device) · [Request fields](/api/notifications/unregister-push-device#request). See [Unregister a push notification device](/api/notifications/unregister-push-device#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `fcmToken`: text firebase-cloud-messaging-token. **Response:** Response example: [Unregister a push notification device](/api/notifications/unregister-push-device) · [Response fields](/api/notifications/unregister-push-device#responses). See [Unregister a push notification device](/api/notifications/unregister-push-device#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `subscriberId`: text user\_123. Use the [remaining-device result](/api/notifications/delivery#device-registration) to confirm this device was removed. ## Recover failed enrollment and sign-out \{#device-lifecycle} Register while the intended user is authenticated. Listen for token rotation. After a reconnect or failed registration, check registered channels and retry the current token with a bounded retry policy instead of waiting for another rotation. Do not log push tokens. Unregister the current device while the old user is still authenticated. If it fails, clear private data from the device, keep track of the pending removal, and retry under that user's authenticated session or ask support before binding the device to a different user. Signing out locally does not remove a server registration. Do not delete the user's persistent schedules when signing out one device. A successful registration does not confirm delivery or display. Send a test to the device and check [delivery status](/core-platform/notifications/administration#delivery-status); receiving, displaying and opening a notification are separate outcomes. Device expiry rules differ by platform, so do not apply Android inactivity rules to iOS. --- URL: https://docs.travila.ai/core-platform/notifications/sending # Send notifications \{#send-notifications} Build the “new coaching update” notification in the example below. Your application first saves the update in its conversation, then sends a short notice to the intended user. Opening the notice returns the user to that conversation. Before sending, [prepare a workflow](/core-platform/notifications/administration#workflows) whose template accepts the shown payload variables, [register the recipient’s device](/core-platform/notifications/push) for push, and decide which updates should be grouped into a digest. Replace sample identifiers with the workflow, user and conversation your application has actually created. Use the prepared workflow and supply the message variables it expects. See [workflow and payload meaning](/api/notifications/send-notification#overview). Call these operations from your backend with a verified key or configured standalone JWT. They do not enforce separate admin roles or recipient permissions. Check that the requesting person may send this notification to this recipient before making the call; an accepted token or supplied user ID is insufficient. ## 1. Notify the user after the update is saved \{#send-to-one-user} Resolve the recipient and conversation from the authenticated application event. Send once for that intended notification, keep its transaction reference, and use the reference for delivery checks or cancellation. Validate the deep link in your app when it is opened; the link itself grants no access. Request example: [Send a notification to a user](/api/notifications/send-notification) · [Request fields](/api/notifications/send-notification#request). See [Send a notification to a user](/api/notifications/send-notification#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `workflowId`: text push-notification. * `userId`: text recipient-user-id. * `payload.title`: text New Message. * `payload.body`: text You have a new coaching update. * `payload.deep_link`: text travila://conversation/conv\_abc. * `transactionId`: text optional-idempotency-key. **Response:** Response example: [Send a notification to a user](/api/notifications/send-notification) · [Response fields](/api/notifications/send-notification#responses). See [Send a notification to a user](/api/notifications/send-notification#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `acknowledged`: boolean true. * `status`: text processed. * `transactionId`: text txn\_abc123. Use the [send contract](/api/notifications/send-notification#overview) for field meanings and acceptance details. Save the returned transaction before following delivery. **Expected result:** the trigger is acknowledged and has a transaction reference. Next, inspect [channel delivery](/core-platform/notifications/administration#delivery-status) and open the notice on the recipient’s device. Reconcile an uncertain send using the original reference before issuing a replacement; acceptance, delivery and opening are separate outcomes. ## Variant: announce the same change to selected users \{#send-to-many-users} Split a larger audience into [supported batches](/api/notifications/send-bulk-notification#overview), and retain a result for each intended recipient: Request example: [Send a notification to multiple users](/api/notifications/send-bulk-notification) · [Request fields](/api/notifications/send-bulk-notification#request). See [Send a notification to multiple users](/api/notifications/send-bulk-notification#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `events[0].workflowId`: text push-notification. * `events[0].userId`: text user-1. * `events[0].payload.title`: text Update. * `events[0].payload.body`: text New feature available. * `events[1].workflowId`: text push-notification. * `events[1].userId`: text user-2. * `events[1].payload.title`: text Update. * `events[1].payload.body`: text New feature available. **Response:** Response example: [Send a notification to multiple users](/api/notifications/send-bulk-notification) · [Response fields](/api/notifications/send-bulk-notification#responses). See [Send a notification to multiple users](/api/notifications/send-bulk-notification#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `results[0].acknowledged`: boolean true. * `results[0].status`: text processed. * `results[0].transactionId`: text txn\_1. * `results[1].acknowledged`: boolean true. * `results[1].status`: text processed. * `results[1].transactionId`: text txn\_2. Confirm each intended recipient separately using the [per-event result](/api/notifications/send-bulk-notification#overview). ## Choose explicit recipients for an announcement \{#broadcast-to-everyone} To reach an explicitly selected group, use [topics](/core-platform/notifications/topics) with authorized subscriber membership, or send a bulk request with explicit recipients. This guide does not provide a tenant-wide broadcast operation. ## Recover: withdraw an update before delivery \{#cancel-a-pending-notification} Requests cancellation through the configured provider. Whether a delayed, digested or queued delivery can still be stopped depends on its provider state; an accepted cancellation is not proof that every delivery was prevented. Already-delivered messages cannot be recalled. Inspect the returned result and reconcile delivery status where available. Request example: [Cancel a pending notification](/api/notifications/cancel-notification) · [Request fields](/api/notifications/cancel-notification#request). See [Cancel a pending notification](/api/notifications/cancel-notification#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `transactionId`: text txn\_abc123. **Response:** Response example: [Cancel a pending notification](/api/notifications/cancel-notification) · [Response fields](/api/notifications/cancel-notification#responses). See [Cancel a pending notification](/api/notifications/cancel-notification#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `cancelled`: boolean true. * `message`: text Notification successfully cancelled. Check the [cancellation result](/api/notifications/cancel-notification#overview) before telling the user the notice was withdrawn. ## Variant: send a reminder at the user’s chosen time \{#scheduling-and-delays} There is no send-at-a-time or send-after-a-delay endpoint on this API. Deferred delivery comes from one of two places: * **Inside a workflow** — add a `delay` step to the workflow definition. Every trigger of that workflow then waits, and `manage/cancel` with the transaction ID requests cancellation; a race with delivery can still leave an already-dispatched message. * **Outside the workflow** — create a [scheduled job](/core-platform/scheduling) that calls `manage/send` when it runs. Use this for calendar-shaped sends (`0 9 * * 1-5`, a one-off timestamp, a repeating interval) and anything a user can reschedule. ## Variant: combine a busy conversation’s updates into one notice \{#digest--batching} Use a digest when several updates can wait for one summary. Configure the grouping and delivery window in the workflow, then feed each eligible update into that digest. Keep individual event references so a retracted update can be removed while the digest is still pending. A digest collapses many events into one message. The window and grouping are configured in the workflow's digest step; this endpoint just feeds events into it. Request example: [Send a notification with digest aggregation](/api/notifications/send-with-digest) · [Request fields](/api/notifications/send-with-digest#request). See [Send a notification with digest aggregation](/api/notifications/send-with-digest#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `workflowId`: text activity-digest. * `userId`: text user-1. * `payload.title`: text Activity Update. * `payload.body`: text New activity in your coaching plan. * `transactionId`: text digest-event-123. **Response:** Response example: [Send a notification with digest aggregation](/api/notifications/send-with-digest) · [Response fields](/api/notifications/send-with-digest#responses). See [Send a notification with digest aggregation](/api/notifications/send-with-digest#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `acknowledged`: boolean true. * `status`: text processed. * `transactionId`: text digest-event-123. Remove a single event from a digest that has not yet been delivered. Once the digest has gone out this is a no-op rather than an error. Request example: [Cancel a pending digest event](/api/notifications/cancel-digest-event) · [Request fields](/api/notifications/cancel-digest-event#request). See [Cancel a pending digest event](/api/notifications/cancel-digest-event#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `transactionId`: text digest-event-123. **Response:** Response example: [Cancel a pending digest event](/api/notifications/cancel-digest-event) · [Response fields](/api/notifications/cancel-digest-event#responses). See [Cancel a pending digest event](/api/notifications/cancel-digest-event#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `cancelled`: boolean true. * `message`: text Digest event successfully cancelled. Confirm the [digest cancellation result](/api/notifications/cancel-digest-event#overview); if delivery already happened, show that outcome instead of promising withdrawal. --- URL: https://docs.travila.ai/core-platform/notifications/topics # Broadcast with topics \{#broadcast-with-topics} Build an opt-in “Weekly Updates” group: users join or leave it in your app, and your backend sends each update to the current subscribers. Prepare the notification workflow and subscriber records first. The topic stores membership; it does not create users or prepare message content. Follow the recipe in order: create one stable topic, show the current user’s subscription, save follow/unfollow changes, check partial failures, then send the update. Use the returned transaction to investigate delivery. A topic is a named group of subscribers you can send to as one. Use it when the recipient list is a property of the content — everyone following a coach, everyone in a challenge — rather than something you can compute per send. Use the topic operations below for an explicitly selected subscriber group. For a recipient list supplied with each send, use [bulk sending](/core-platform/notifications/sending). Keep topic management in your backend. The API accepts a verified key or configured JWT but does not check an admin role simply because a route contains `/manage/`. Your application must authorize who can change membership or send to the topic. See [management authentication](/core-platform/notifications/administration). ## 1. Create the weekly-updates audience \{#create-a-topic} Request example: [Create a notification topic](/api/notifications/create-topic) · [Request fields](/api/notifications/create-topic#request). See [Create a notification topic](/api/notifications/create-topic#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `topicKey`: text weekly-updates. * `name`: text Weekly Updates. **Response:** Response example: [Create a notification topic](/api/notifications/create-topic) · [Response fields](/api/notifications/create-topic#responses). See [Create a notification topic](/api/notifications/create-topic#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `topicKey`: text weekly-updates. * `topicId`: text 6512f0a1c3d4e5f60718293c. Keep your chosen audience key for later actions; see [topic identifiers](/api/notifications/delivery#topic-membership). ## 2. Show the user’s current subscription \{#check-one-subscription} Cheaper than paging the whole list when you only need to render a follow/unfollow button. Request example: [Check if a user is subscribed to a topic](/api/notifications/check-topic-subscription) · [Request fields](/api/notifications/check-topic-subscription#request). See [Check if a user is subscribed to a topic](/api/notifications/check-topic-subscription#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `topicKey`: text weekly-updates. * `userId`: text user-1. **Response:** Response example: [Check if a user is subscribed to a topic](/api/notifications/check-topic-subscription) · [Response fields](/api/notifications/check-topic-subscription#responses). See [Check if a user is subscribed to a topic](/api/notifications/check-topic-subscription#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `isSubscribed`: boolean true. Render the follow button using the [subscription result](/api/notifications/delivery#topic-membership). ## 3. Apply follow and unfollow choices \{#add-and-remove-subscribers} When a person opts in, add their existing subscriber identity. When they opt out, remove it. For an import, batch up to the limit below and check every failure; one missing subscriber must not be shown as enrolled just because another succeeded. Up to 100 users per call. Request example: [Add subscribers to a topic](/api/notifications/add-subscribers-to-topic) · [Request fields](/api/notifications/add-subscribers-to-topic#request). See [Add subscribers to a topic](/api/notifications/add-subscribers-to-topic#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `topicKey`: text weekly-updates. * `userIds[0]`: text user-1. * `userIds[1]`: text user-2. **Response:** Response example: [Add subscribers to a topic](/api/notifications/add-subscribers-to-topic) · [Response fields](/api/notifications/add-subscribers-to-topic#responses). See [Add subscribers to a topic](/api/notifications/add-subscribers-to-topic#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `result.totalCount`: number 2. * `result.successful`: number 2. * `result.failed`: number 0. Inspect [per-user membership results](/api/notifications/delivery#topic-membership) and show failed enrollments separately: Response example: [Add subscribers to a topic](/api/notifications/add-subscribers-to-topic) · [Response fields](/api/notifications/add-subscribers-to-topic#responses). See [Add subscribers to a topic](/api/notifications/add-subscribers-to-topic#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `result.totalCount`: number 2. * `result.successful`: number 1. * `result.failed`: number 1. * `result.errors[0].subscriberId`: text user-2. * `result.errors[0].code`: text not\_found. * `result.errors[0].message`: text subscriber does not exist. Request example: [Remove subscribers from a topic](/api/notifications/remove-subscribers-from-topic) · [Request fields](/api/notifications/remove-subscribers-from-topic#request). See [Remove subscribers from a topic](/api/notifications/remove-subscribers-from-topic#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `topicKey`: text weekly-updates. * `userIds[0]`: text user-1. **Response:** a [`result`](/api/notifications/remove-subscribers-from-topic#response-field-result) object containing the same [`totalCount`](/api/models/schema-p2eb0gb1ln#response-field-totalcount) / [`successful`](/api/models/schema-p2eb0gb1ln#response-field-successful) / [`failed`](/api/models/schema-p2eb0gb1ln#response-field-failed) / [`errors`](/api/models/schema-p2eb0gb1ln#response-field-errors) shape. ## 4. Inspect membership when enrollment is incomplete \{#list-subscribers} Use the membership list to investigate a failed import or unexpected recipient. Compare identities with the intended audience and follow pagination; use the single-subscription check for the current user’s follow button. Request example: [List subscribers of a topic](/api/notifications/list-topic-subscribers) · [Request fields](/api/notifications/list-topic-subscribers#request). See [List subscribers of a topic](/api/notifications/list-topic-subscribers#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `topicKey`: text weekly-updates. * `page`: number 1. * `pageSize`: number 50. **Response:** Response example: [List subscribers of a topic](/api/notifications/list-topic-subscribers) · [Response fields](/api/notifications/list-topic-subscribers#responses). See [List subscribers of a topic](/api/notifications/list-topic-subscribers#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `userIds[0]`: text user-1. * `userIds[1]`: text user-2. * `totalCount`: number 2. * `hasMore`: boolean false. ## 5. Deliver an update to the subscribed group \{#send-to-a-topic} Send only after the update is ready and your backend authorizes the sender. Select the workflow and current topic key. If the initiating user should not receive a notice about their own action, use the documented exclusion below. Request example: [Send a notification to all topic subscribers](/api/notifications/send-to-topic) · [Request fields](/api/notifications/send-to-topic#request). See [Send a notification to all topic subscribers](/api/notifications/send-to-topic#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `workflowId`: text push-notification. * `topicKey`: text weekly-updates. * `payload.title`: text Weekly Update. * `payload.body`: text Your weekly health summary is ready. * `excludeUserId`: text user-admin. **Response:** Response example: [Send a notification to all topic subscribers](/api/notifications/send-to-topic) · [Response fields](/api/notifications/send-to-topic#responses). See [Send a notification to all topic subscribers](/api/notifications/send-to-topic#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `acknowledged`: boolean true. * `status`: text processed. * `transactionId`: text txn\_def456. Use the [sender-exclusion option](/api/notifications/delivery#topic-sends) when the person should not receive their own update. The result acknowledges the topic send. Follow its transaction through [delivery status](/core-platform/notifications/administration#delivery-status) when a subscriber reports a missing message. Check their current membership, channel registration and preferences before sending an individual replacement. ## Retire the group without deleting its users \{#delete-a-topic} Removes the topic and every subscriber association with it. Subscribers themselves are untouched, and notifications already in flight are not cancelled. Request example: [Delete a notification topic](/api/notifications/delete-topic) · [Request fields](/api/notifications/delete-topic#request). See [Delete a notification topic](/api/notifications/delete-topic#request) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `topicKey`: text weekly-updates. **Response:** Response example: [Delete a notification topic](/api/notifications/delete-topic) · [Response fields](/api/notifications/delete-topic#responses). See [Delete a notification topic](/api/notifications/delete-topic#responses) for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values. * `status.acknowledged`: boolean true. * `status.status`: text done. Read the [retirement result](/api/notifications/delivery#topic-sends) before confirming the group was removed. --- URL: https://docs.travila.ai/core-platform/scheduling # Run work on a schedule \{#run-work-on-a-schedule} Send a weekday digest, deliver a reminder at a chosen time, or refresh application data at a regular interval. Create a job that calls your endpoint on that schedule, then follow its delivery history and recover failed attempts. ## Start here \{#start-here} | Build this feature | Recipe | | ----------------------------------------------------- | --------------------------------------------------------------------------------- | | Generate a weekday briefing for a user | [Automate recurring agent work](/core-platform/scheduling/build-scheduled-agents) | | Call your application at a chosen time | [Create a reminder or calendar job](/core-platform/scheduling/creating) | | Let a user reschedule, pause or remove a reminder | [Manage the reminder lifecycle](/core-platform/scheduling/managing) | | Recover a reminder that failed to reach your app | [Trace execution and retries](/core-platform/scheduling/execution) | | Implement the callback receiver used by these recipes | [Accept authenticated callbacks safely](/core-platform/scheduling/verifying) | ## How it works \{#how-it-works} For a daily briefing, the scheduler calls your backend at the selected time; your backend accepts the firing, performs the work and records its business result. 1. Build a callback receiver that verifies the signed request and saves accepted work durably. 2. Create the job with that receiver, the intended user and a calendar/timezone or one-time timestamp. 3. Save the returned schedule identifier and show the next trigger time in your application. 4. Follow the first firing through execution history and your receiver’s business outcome. 5. Give the user a way to change or stop future firings, while accounting separately for work already accepted. A successful scheduler execution means your receiver acknowledged delivery. It does not prove the briefing was generated or shown to the user. The [agent briefing recipe](/core-platform/scheduling/build-scheduled-agents) connects those later steps. ## Choose when the work should run \{#schedule-types} | Your application needs | Recipe variant | | ----------------------------------------- | ------------------------------------------------------------------------------------- | | A weekday digest at the user’s local time | [Use a calendar schedule](/core-platform/scheduling/creating#cron-job) | | One reminder at a chosen instant | [Use a one-time schedule](/core-platform/scheduling/creating#one-shot-job) | | A refresh at regular elapsed intervals | [Use an interval schedule](/core-platform/scheduling/creating#recurring-interval-job) | The [timing reference](/api/scheduled-jobs/create-job#overview) defines timezone handling and field defaults. ## Related \{#related} * [Authentication & API Keys](/core-platform/identity-access/authentication) — Keys and acting on behalf of a user * [Webhooks](/integrations/webhooks) — Receiving platform events rather than scheduling your own * [Scheduler API Reference](/api/scheduled-jobs) — Full endpoint reference --- URL: https://docs.travila.ai/core-platform/scheduling/creating # Create a scheduled job \{#create-a-scheduled-job} Deliver a weekday digest at 9 a.m. in the user’s chosen timezone. Prepare a receiver that turns the scheduled firing into the digest, create the calendar schedule, and show the returned next delivery time in the app. Before enabling the schedule, implement [callback verification and retry handling](/core-platform/scheduling/verifying). Use the [scheduled agent recipe](/core-platform/scheduling/build-scheduled-agents) when an agent writes the digest. ## Recipe: deliver a weekday digest \{#creating-jobs} You need an authenticated user, a backend secret key and an HTTPS receiver that implements [signature verification and durable acceptance](/core-platform/scheduling/verifying). 1. Choose the digest’s calendar time and IANA timezone with the user. 2. Register your receiver and the payload that identifies the intended work using the cron example below. 3. Save the returned schedule ID and show its [`nextTriggerAt`](/api/models/schema-1ld0l8rmvg#response-field-nexttriggerat) to the user. 4. After the first firing, check [execution history](/core-platform/scheduling/execution) and the digest result produced by your receiver. For a single reminder use the one-shot variant; for cache maintenance use the interval variant. All three use the same receiver and recovery contract. ### Schedule the weekday digest \{#cron-job} Use the user’s chosen timezone and weekday time in this request. See [timing fields and defaults](/api/scheduled-jobs/create-job#overview) for other schedule forms. Schedule a weekday digest while acting on behalf of its owner; replace the target URL with your endpoint. [Request example: Create a scheduled job](/api/scheduled-jobs/create-job#example-scheduled-jobs-createJob-request). 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. Use the [cron expression reference](/api/scheduled-jobs/create-job#overview) when the customer needs a different calendar pattern. ### Confirm and save the next scheduled time \{#response} Persist the returned [`scheduleId`](/api/models/schema-1ld0l8rmvg#response-field-scheduleid) with your application’s reminder or digest record. Display the next trigger time in the intended timezone. If it is wrong, correct the timing through [Manage jobs](/core-platform/scheduling/managing) before relying on the schedule. Save the [returned schedule](/api/models/schema-1ld0l8rmvg#overview) with the reminder: [Response example: Create a scheduled job](/api/scheduled-jobs/create-job#example-cookbook-core-platform-scheduling-creating-json-01-response). Example identifiers and values are illustrative; substitute authorized values. Use the [counter representation](/api/models/schema-1ld0l8rmvg#overview) when displaying the reminder’s history. ## Choose how long failed delivery may retry \{#retry-policy-defaults} Choose a delivery window appropriate for the reminder, using the [retry policy](/api/scheduled-jobs/schedules#retry-policy). Let the same accepted firing recover within that window before considering a replacement. ## Recover when repeated failures pause the job \{#auto-pause-threshold} Repair the receiver before resuming a paused reminder. The [auto-pause contract](/api/scheduled-jobs/schedules#retry-policy) defines the threshold and supported overrides. ## Variant: remind the user once at a chosen time \{#one-shot-job} Creates one scheduled firing at the given timestamp. Delivery can be retried, so your receiver must deduplicate acceptance and its business effects. Use a future RFC 3339 timestamp. [Request example: Create a scheduled job](/api/scheduled-jobs/create-job#example-cookbook-core-platform-scheduling-creating-02-request). 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. ## Variant: refresh application data every few minutes \{#recurring-interval-job} Use a recurring interval to refresh a cache or perform routine maintenance every N seconds without tying it to a clock time. The minimum interval is 60 seconds. [Request example: Create a scheduled job](/api/scheduled-jobs/create-job#example-cookbook-core-platform-scheduling-creating-03-request). 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. --- URL: https://docs.travila.ai/core-platform/scheduling/execution # Monitor executions and retries \{#monitor-executions-and-retries} Find out whether a scheduled reminder or recurring task reached your endpoint. Check execution history for failed attempts, follow retries, and resume an automatically paused job after its target is healthy. ## Find where the missing digest stopped \{#execution-history} Use this recipe when a daily digest did not appear. Start with its saved schedule ID, intended firing time and the backend receiver’s work record. 1. List executions for that schedule around the missing digest. 2. If an attempt failed, inspect the HTTP result and error; fix the receiver or dependency it identifies. 3. Check whether retries remain or the firing exhausted its attempts. If the job auto-paused, restore the receiver before resuming future work. 4. If delivery completed, inspect the receiver’s accepted work and generated digest. A successful callback is not proof of a finished message. 5. Reconcile an uncertain accepted action before manually replacing the digest, to avoid producing two. Keep the schedule and execution references with the incident. The fields below explain the delivery portion of that investigation. Every firing is recorded as an execution. Query the history to debug failures or monitor delivery. This request isolates failed deliveries. To inspect a completed delivery as well, omit [`statusFilter`](/api/scheduled-jobs/list-executions#request-field-statusfilter) and match the intended firing in the returned history. [Request example: List executions for a scheduled job](/api/scheduled-jobs/list-executions#example-cookbook-core-platform-scheduling-execution-01-request). 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. Use the [execution fields and failure diagnostics](/api/models/schema-1l7vrun3li#overview) to interpret the attempt you selected. ## Recover a temporary receiver failure \{#retry-policy} A receiver outage can recover within the firing’s retry window. Fix the underlying failure first and let the same firing continue within its configured limit; changing a retry policy is not a substitute for checking whether your receiver already accepted the work. Choose the [retry limits](/api/scheduled-jobs/schedules#retry-policy) that fit this delivery’s useful lifetime. To override the defaults, include a [`retryPolicy`](/api/scheduled-jobs/create-job#request-field-retrypolicy) in your `create-job` request: [Request example: Create a scheduled job](/api/scheduled-jobs/create-job#example-cookbook-core-platform-scheduling-execution-02-request). 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. ## Restart future digests after fixing repeated failure \{#auto-pause} Restore the target, inspect the affected firing and then resume future digests. See [pause state and thresholds](/api/scheduled-jobs/schedules#retry-policy) for the exact behavior. --- URL: https://docs.travila.ai/core-platform/scheduling/managing # Manage jobs \{#manage-jobs} Let a user move their daily digest to a different time, take a temporary break or stop it permanently. Load their saved schedule, apply the requested change and show its returned state so they can see what will happen next. Have the owning account and user, plus the [`scheduleId`](/api/models/schema-1ld0l8rmvg#response-field-scheduleid) saved when you created the reminder or its application-owned [`externalId`](/api/scheduled-jobs/create-job#request-field-externalid). Changes affect future dispatch; check execution history for work already sent. ## Recipe: change or stop a daily digest \{#managing-jobs} Build the “change my weekday digest” flow for a job you previously created. Keep the schedule ID with the application’s reminder record, or use an immutable external ID as described below. 1. Authenticate the owning user and load that job. 2. Show its current timing and next trigger before accepting a change. 3. Apply only the changed timing fields, then display the returned next trigger. 4. Use pause for a temporary break and delete when the user removes the reminder. 5. If a change loses its response, read the same job and its execution history before repeating it. Work already delivered to the receiver needs its own outcome check. The person’s reminder stays tied to the same job. Account-wide cleanup and project teardown below are separate administrative variants, not sign-out behavior. ### 1. Load the reminder being changed \{#get-a-job} Load the saved ID under the same user that created the job. Use its current timing and state to populate the edit form; a different user’s supplied ID is not permission to change their reminder. [Request example: Get a scheduled job](/api/scheduled-jobs/get-job#example-cookbook-core-platform-scheduling-managing-01-request). 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. ### Variant: show the user’s reminder list \{#list-jobs} Returns a page of jobs for the account and user identified by your authentication headers. Follow pagination to enumerate results, and optionally filter by state or target kind. [Request example: List scheduled jobs](/api/scheduled-jobs/list-jobs#example-cookbook-core-platform-scheduling-managing-02-request). 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. ### 2. Save a new delivery time \{#update-a-job} Submit the user’s selected time once. Use the returned next trigger as confirmation; if the response is lost, read the existing job to determine whether the new time was saved before trying again. Send only the edited settings, following the [update contract](/api/scheduled-jobs/update-job#overview): [Request example: Update a scheduled job](/api/scheduled-jobs/update-job#example-cookbook-core-platform-scheduling-managing-03-request). 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. Display the returned next-trigger time and check previously accepted work separately. See [timing-update effects](/api/scheduled-jobs/update-job#overview). ### 3. Let the user take a temporary break \{#pause-and-resume} Use pause to temporarily stop a job without deleting it. Resume returns it to `SCHEDULE_STATUS_ACTIVE`. [Request example: Pause a scheduled job](/api/scheduled-jobs/pause-job#example-cookbook-core-platform-scheduling-managing-04-1-request). Example identifiers and values are illustrative; substitute authorized values. [Request example: Resume a scheduled job](/api/scheduled-jobs/resume-job#example-cookbook-core-platform-scheduling-managing-04-2-request). 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`; `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. ### 4. Remove this reminder \{#delete-a-job} Soft-delete removes the job from future scheduling. It does not retract a callback already in flight. Deleted jobs remain available for audit according to retention policy. [Request example: Delete a scheduled job](/api/scheduled-jobs/delete-job#example-cookbook-core-platform-scheduling-managing-05-request). 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. ### Account cleanup: remove all of the user’s schedules \{#delete-every-job-for-the-caller} Soft-deletes every job owned by the calling subject, within the tenant and project from the verified request context. The body carries no owner selector. A backend using `X-On-Behalf-Of` must establish that beneficiary through its own authenticated application flow. Use this only for an explicit request to remove all of the user's persistent schedules or for authorized account cleanup. Ordinary sign-out should clear the local session and device notification binding; it should not delete reminders on other devices. Keep the cleanup result, list remaining jobs and investigate failures before reporting that all schedules were removed. [Response example: Delete all scheduled jobs for the calling owner](/api/scheduled-jobs/delete-jobs-for-owner#example-cookbook-core-platform-scheduling-managing-json-01-response). Example identifiers and values are illustrative; substitute authorized values. ### Project teardown: remove schedules across all owners \{#delete-every-job-in-the-project} The project-teardown equivalent: soft-deletes every job belonging to the tenant and project in the request context, across **all** owners. The body carries no fields. This operation requires a backend request without a selected user: adding `X-On-Behalf-Of` causes rejection. It currently applies to the legacy `default` project; it does not establish deletion support for arbitrary projects. [Response example: Delete all scheduled jobs for a project](/api/scheduled-jobs/delete-jobs-for-project#example-cookbook-core-platform-scheduling-managing-json-02-response). Example identifiers and values are illustrative; substitute authorized values. > **Warning: No confirmation, no filter** > > Use this operation only for authorized project teardown. It deletes all jobs in its supported project scope, has no filter and cannot undo the deletion. Confirm the account and project in your backend, and require permission for teardown before sending the request. Client-supplied tenant/project headers do not grant that permission. [`deletedCount`](/api/scheduled-jobs/delete-jobs-for-project#response-field-deletedcount) is omitted when zero. ## Variant: use your application’s reminder identifier \{#referencing-jobs-by-external-id} Use an immutable application reminder identifier when you want to keep job lookup tied to your own record. See [identifier rules](/api/scheduled-jobs/update-job#overview): [Request example: Create a scheduled job](/api/scheduled-jobs/create-job#example-cookbook-core-platform-scheduling-managing-08-request). 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. Use the same saved identifier when retrieving or changing the reminder; see [supported lookups](/api/scheduled-jobs/update-job#overview): [Request example: Get a scheduled job](/api/scheduled-jobs/get-job#example-cookbook-core-platform-scheduling-managing-09-request). 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. Choose the application identifier before creation and retain it for the reminder’s lifetime; [reserved values and immutability](/api/scheduled-jobs/update-job#overview) apply. --- URL: https://docs.travila.ai/core-platform/scheduling/verifying # Verify a callback came from Travila \{#verify-a-callback-came-from-travila} Build the receiver behind a daily briefing or one-time reminder. Its job is to turn an authenticated scheduler firing into one durable work item, acknowledge that acceptance, and let a worker complete the business action. Have the schedule’s expected owner, target and payload available in your application, plus a maintained JWT verifier and a durable queue or transactional outbox. Use the receiver sequence below with the deployment’s trusted signing keys and expected claim values. Your job target is a URL on the public internet, so anything can POST to it. Every dispatch the platform makes carries a signed token proving it came from us — verify it before acting on the request. ## What arrives \{#what-arrives} Callback example: [HTTP envelope](/api/scheduled-jobs/callbacks#callback-envelope) · [Signed claims](/api/scheduled-jobs/callbacks#claims). A scheduled callback is an HTTP POST to your application’s configured endpoint. It includes Authorization with a Bearer signed JWT, Content-Type application/json, and an Idempotency-Key shaped as `sched::`. Its body is the schedule’s configured payload verbatim. The endpoint path and token are placeholders. The callback body is your configured payload; it is not converted to an API request format. Check the [callback envelope and body-binding rules](/api/scheduled-jobs/callbacks#callback-envelope) before accepting the work. ## Recipe: accept one firing and hand work to a worker \{#receiver-algorithm} The following is a required sequence, not drop-in server code. Use a maintained JWT library and a durable queue or transactional outbox. 1. Bound the HTTP body and token sizes. Require a bearer token and the expected content type. 2. Select a trusted key by `kid` from the configured issuer's JWKS. Allow only the configured algorithm (`RS256` in the current scheduler contract); never follow a token-supplied key URL. Bound unknown-key refresh and cache behavior. 3. Verify the signature, exact issuer, [expected audience](/api/scheduled-jobs/callbacks#audience) and [required time and identity claims](/api/scheduled-jobs/callbacks#claims). Require the schedule trigger, owner, tenant, project, schedule and firing identities. Return a generic authentication error without disclosing token contents if validation fails. 4. Match the verified identities, target and payload to an allowed schedule in your system. Check that the business action is still permitted. A valid old firing is not permission to access a different recipient or revoked resource. 5. Apply the [verified firing and payload-binding rules](/api/scheduled-jobs/callbacks#replay). In **one database transaction or equivalent durable queue operation**, save the verified firing identity, its scope and a hash of the expected payload together with the pending work item. If an identical record already exists, return its accepted acknowledgement. If the same identity carries a different payload, reject it. If persistence fails, do not return success. 6. Return `2xx` only after durable acceptance. A worker then performs the action, using a stable operation ID and checking uncertain outcomes before retrying. Mark the action completed only after its outcome is known. A separate `already_processed()` read followed by `mark_processed()` and a direct action is unsafe: concurrent requests race, and a crash after marking can lose the work. Likewise, acknowledging before enqueueing can lose an entire firing. ## Getting the public key \{#getting-the-public-key} The platform publishes its signing keys as a standard JWKS, unauthenticated: JWKS verification navigation. * https\://api.travila.ai/.well-known/jwks.json with the usual discovery document alongside it: OpenID discovery navigation. * https\://api.travila.ai/.well-known/openid-configuration Configure your verifier with the [algorithm, key-selection and caching contract](/api/scheduled-jobs/callbacks#signing-keys). ## Claims \{#claims} Keep the expected owner, tenant, project and schedule identity with the registered job. Compare the callback’s [signed claim set](/api/scheduled-jobs/callbacks#claims) to that record before enqueueing its work; a valid signature alone does not select an authorized business action. ### Audience \{#audience} Configure the receiver’s expected audience from its own registered URL, using the [audience normalization rules](/api/scheduled-jobs/callbacks#audience). Reject a signed callback intended for another receiver instead of accepting any audience the token supplies. ### Replay protection and durable acceptance \{#replay-protection-and-durable-acceptance} Test two concurrent deliveries of the same verified firing and confirm that they produce one durable work item. Repeat the test with a changed payload and require rejection. The [firing identity and payload-binding rules](/api/scheduled-jobs/callbacks#replay) define what the receiver must compare; an initial duplicate lookup without an atomic write is insufficient. ## Confirm acceptance and recover delivery failures \{#responding} Return success only after your receiver has durably accepted the work. Follow the [acknowledgement and retry contract](/api/scheduled-jobs/callbacks#acknowledgement) when persistence or delivery fails. Track the worker’s business result separately. The completed receiver rejects a callback for another schedule or user, returns the same acceptance for an identical retry, and preserves accepted work across a restart. Test those cases with controlled data before enabling the recurring job. Track business completion separately so a worker failure can be recovered without asking the scheduler to create a new firing. --- URL: https://docs.travila.ai/core-platform/scheduling/build-scheduled-agents # Automate recurring agent work \{#automate-recurring-agent-work} Some agent work happens on a clock, not on a user tap: a daily briefing, a nightly summary, a weekly report. This guide wires a cron schedule to a Travila agent so a job fires on a timer, drives a conversation turn, and — optionally — delivers the result to your backend as a webhook event. **What you’ll build:** a weekday briefing scheduled to start preparing at 9 a.m. in the selected timezone and appear in the existing user conversation when complete. Your backend receives the scheduled firing, asks the agent for the briefing and tracks the completed reply. Optionally, a webhook lets your backend react when that reply is published. ## Prerequisites \{#prerequisites} * An **API key** (`sk_…`) for your backend (issued through your account administrator or enabled key-management interface). See [Authentication & API Keys](/core-platform/identity-access/authentication). * A conversation thread — create one with `create-thread` if you do not have one. See [Build an AI chat assistant](/managed-agents/conversations/build-chat-assistant) for the full setup. * A **publicly reachable HTTPS URL** for your callback endpoint, e.g. `https://api.example.com/hooks/scheduled-agent`. The scheduler POSTs to it on every firing. ## Step 1: Create the callback endpoint in your backend \{#step-1-create-the-callback-endpoint-in-your-backend} Your backend needs one HTTP endpoint that the scheduler will POST to on each firing. The body will be exactly the payload you configure in the schedule (see Step 4). The scheduler adds the following headers: Callback example: [HTTP envelope](/api/scheduled-jobs/callbacks#callback-envelope) · [Signed claims](/api/scheduled-jobs/callbacks#claims). A scheduled callback is an HTTP POST to your application’s configured endpoint. It includes Authorization with a Bearer signed JWT, Content-Type application/json, and an Idempotency-Key shaped as `sched::`. Its body is the schedule’s configured payload verbatim. The endpoint path and token are placeholders. The callback body is your configured payload; it is not converted to an API request format. Verify and atomically persist acceptance plus a pending work item before returning `2xx`. Process the agent work in a worker; a fast acknowledgement without durable work can lose the firing. Repeated failed deliveries can auto-pause the schedule. ## Step 2: Verify the callback signature \{#step-2-verify-the-callback-signature} Every scheduler dispatch carries a signed JWT in the `Authorization` header. Verify it before acting — an endpoint that acts first and verifies afterwards is one that anyone can trigger. ### Getting the public key \{#getting-the-public-key} The platform publishes its signing keys as a standard JWKS, unauthenticated and cacheable: JWKS discovery URL. * https\://api.travila.ai/.well-known/jwks.json Use the [signing-key contract](/api/scheduled-jobs/callbacks#signing-keys) when configuring your verifier. ### Claims \{#claims} Validate the [signed claims](/api/scheduled-jobs/callbacks#claims), receiver audience and saved schedule before queuing the briefing. Follow the [callback receiver recipe](/core-platform/scheduling/verifying) for durable acceptance and replay handling. ## Step 3: Drive an agent turn from the callback \{#step-3-drive-an-agent-turn-from-the-callback} For this recipe, keep one conversation and the fixed “daily briefing” task with the user’s schedule. The worker uses that saved assignment to request the briefing. The scheduler’s HTTP acknowledgement happens before this slower generation work, so record both outcomes. After saving the firing and pending work, a worker selects the user, conversation and fixed task from the schedule registration saved in your application. Check current business eligibility and the agreed task permissions before generation and again before delivery. Never use an LLM-generated user ID, destination or deep link as authority. The worker may use `send-message-sync` for a bounded wait. Save a work record for the verified firing and the returned run ID. The callback's `jti` does not make that API call idempotent, and colon-separated firing IDs may be invalid as API idempotency keys. If the send times out, check the original run through the [generation recovery flow](/managed-agents/conversations/build-chat-assistant#client-lifecycle-and-recovery) before sending another turn. If you cannot establish the outcome, keep it unknown and investigate; do not automatically submit the same business action again. [Request example: Send a message and wait for the result](/api/conversations/send-message-sync#example-cookbook-core-platform-scheduling-build-scheduled-agents-01-request). 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. **Example completed response** — a queued turn, tool pause or expired wait can instead return a nonterminal outcome: [Response example: Send a message and wait for the result](/api/conversations/send-message-sync#example-cookbook-core-platform-scheduling-build-scheduled-agents-json-02-response). Example identifiers and values are illustrative; substitute authorized values. Continue to delivery only when the agent run completes successfully. Use the [run outcome contract](/api/scheduled-jobs/callbacks#agent-outcome) to handle a wait, tool pause or unsuccessful result without generating the briefing twice. ## Step 4: Create the schedule \{#step-4-create-the-schedule} With your endpoint ready, register the cron job. Point [`target.url`](/api/models/schema-1lbkptb5rj#request-field-url) at your callback endpoint: [Request example: Create a scheduled job](/api/scheduled-jobs/create-job#example-cookbook-core-platform-scheduling-build-scheduled-agents-02-request). 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. **Response:** [Response example: Create a scheduled job](/api/scheduled-jobs/create-job#example-cookbook-core-platform-scheduling-build-scheduled-agents-json-03-response). Example identifiers and values are illustrative; substitute authorized values. Save [`scheduleId`](/api/models/schema-1ld0l8rmvg#response-field-scheduleid) — you'll use it to pause, resume, or delete the schedule later. Use the [calendar/timezone reference](/api/scheduled-jobs/create-job#overview) when adjusting this briefing’s schedule. ## Step 5: Subscribe to the results webhook (Optional) \{#step-5-subscribe-to-the-results-webhook-optional} If you want your backend to receive each assistant message as it lands — rather than only reading the `send-message-sync` response — subscribe to the `llm.message_published` event. Pass [`eventTypes`](/api/webhooks/create-webhook-endpoint#request-field-eventtypes) in a single call to create both the endpoint and its subscription: [Request example: Create a webhook endpoint](/api/webhooks/create-webhook-endpoint#example-cookbook-core-platform-scheduling-build-scheduled-agents-03-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** [Response example: Create a webhook endpoint](/api/webhooks/create-webhook-endpoint#example-cookbook-core-platform-scheduling-build-scheduled-agents-json-04-response). Example identifiers and values are illustrative; substitute authorized values. Store the [`secret`](/api/models/schema-1ffl20kv2k#response-field-secret) — it is the signing key for this webhook endpoint. Use the [message-published Event declaration](/api/events/u1s768tpmf) to interpret the received payload. Apply the [webhook verification procedure](/api/events#delivery-envelope) before accepting the event or updating application state. Follow the [subscription and deduplication contract](/api/scheduled-jobs/callbacks#result-webhook) when adding or changing a result receiver. ## Verify the complete workflow \{#verify-the-complete-workflow} Run one controlled briefing through the complete path: scheduled callback, durable acceptance, agent run and visible completed reply in the intended conversation. Keep the schedule, firing and run references together. Once the user can see the briefing, exercise interruption and duplicate-delivery cases below before enabling ongoing delivery. Use an isolated conversation and a constrained schedule. Confirm all of these outcomes before enabling recurring delivery: * Invalid, expired, wrong-audience or wrong-scope callbacks fail before work is accepted. * Repeated identical deliveries produce one durable work item; changed payloads under the same identity are rejected. Simulate a crash after acceptance and verify the worker resumes. * The accepted firing and generated run can be reconciled after a dropped response, without silently creating another turn. * Failed, queued, timed-out, cancelled or unknown generation outcomes do not become successful notifications. Tool pauses follow the documented continuation flow. * Delivery uses a stable business-effect identity, an authorized recipient and current domain state. Duplicate callbacks and webhook redelivery do not send the same briefing twice. * Pause or deletion stops future scheduling according to the deployment's contract, while previously accepted or in-flight work is accounted for separately. ## Next steps \{#next-steps} | I want to… | Go to | | ------------------------------------------------ | -------------------------------------------------------------------------- | | Pause, resume, or delete a schedule | [Manage scheduled jobs](/core-platform/scheduling/managing) | | Understand retry and auto-pause behavior | [Job execution and retries](/core-platform/scheduling/execution) | | See the complete callback verification algorithm | [Verify a callback came from Travila](/core-platform/scheduling/verifying) | | Browse all scheduler endpoints | [Scheduler API Reference](/api/scheduled-jobs) | | Read the assistant-message event payload | [Message-published Event](/api/events/u1s768tpmf) | | Use async generation with polling instead | [Send messages and get replies](/managed-agents/conversations/generation) | --- URL: https://docs.travila.ai/core-platform/secrets # Connect a private tool without putting its credential in prompts \{#manage-project-secrets} Connect an agent to a private tool without copying its provider credential into a prompt or client application. Store the credential once, configure the approved integration to reference it, and exercise the tool before bringing it into use. The public secrets API returns metadata rather than stored values. Keep your original credential in your own secure store so you can replace or recover it. ## Prerequisites and availability \{#prerequisites-and-availability} Use a backend secret API key issued for your account and a deployment that exposes the [Project Secret APIs](/api/secrets). Keep the key and credential out of browser code, conversations, source control and diagnostic logs. The current API does not enforce separate permissions for each secret operation. A key that can reach this API can manage the project's secrets. Treat that access as sensitive. ## Store and reference a credential \{#store-and-reference-a-credential} Choose this recipe when a custom MCP server needs a provider credential. Obtain that credential from the service owner, decide which server may receive it, and keep a recoverable copy in your own secure store. Store the value once and give the connection only its secret name. 1. Choose a unique project secret name using the [name and value limits](/api/secrets/credentials#store-and-reference-a-credential). 2. Store the credential with [put-secret](/api/secrets/put-secret). Retain its returned metadata and version; the response does not reveal the value. 3. Configure the approved [custom MCP connection](/integrations/tools-connections/custom-mcp-servers) to use that name as its secret reference. Check the destination before supplying it a credential. 4. Test the connection and exercise the intended tool before declaring setup complete. A secret's name is a reference, not an authorization grant. The credential reaches the destination when the integration uses it; only bind it to a destination you intend to trust. Finish by exercising the intended tool through the configured connection. Success means the approved server can perform the permitted task; metadata alone proves only that a secret record exists. If authentication fails, inspect the reference and provider credential before writing another version. ## Find the credential used by a failing connection \{#inspect-and-list} Read the connection’s secret metadata and [page through the project’s secrets](/api/secrets/credentials#inspect-and-list) when investigating a missing credential. These reads do not return the credential value. ## Replace a provider credential and verify the integration \{#rotate-and-recover} Writing an existing name replaces its value without editing each reference. After a confirmed change, inspect metadata and test the connection that uses it. If the write fails or times out, pause further rotation: the value and metadata may no longer agree. Keep the intended credential in your secure store, check its validity with the issuing service, and use the returned metadata and a connection test to investigate. If the active version remains unclear, ask your account contact to resolve it before overwriting a potentially newer value. A request already holding the old credential may finish. Replacing the platform value does not revoke that credential at its issuer. During an incident, separately revoke the compromised credential with its provider and verify the replacement works. ## Disconnect the tool before retiring its credential \{#remove-a-credential} Identify and change connections that use this secret, then verify the replacement path or deliberately disable dependent work. [Delete the retired secret](/api/secrets/delete-secret) and separately revoke the old credential at its issuer. [Inspect the deletion result](/api/secrets/credentials#remove-a-credential); a submitted request does not prove cleanup completed. ## Related reference \{#related-reference} [Project Secret APIs](/api/secrets) gives the current request and response shapes. [Authentication](/core-platform/identity-access/authentication) explains credentials and caller scope; [custom MCP connections](/integrations/tools-connections/custom-mcp-servers) explains their use with tools. The [OWASP secret lifecycle guidance](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html) covers rotation, revocation and recovery practices. --- URL: https://docs.travila.ai/core-platform/console-administration # Administer your account in the console \{#overview} **Status:** Upcoming — not yet available. Bring a teammate into the project they will administer while keeping the application’s service integrations independently owned. The recipe starts with your administrator session, adds the teammate with the access their task needs, and ends by confirming their accepted membership and the application’s continuing operation. You need the organization’s console sign-in route, authority to manage the intended project, and a teammate who can accept the invitation. Use the separate key-rotation and operational guides when the job is to change an existing integration rather than invite a person. **Available today:** Console pages and permissions depend on your account. Expanded workspace/project selection, additional roles, SSO administration, audit and privacy workflows are planned. If an action below is absent, use its linked API guide where available or ask your administrator for the supported route. ## 1. Start from the administrator’s account \{#sign-in-and-account} **Status:** Upcoming — not yet available. 1. Open the console link provided by your account administrator through your established account channel. 2. Use the human sign-in method enabled for that deployment. Application API keys and your application's end-user JWT are not substitutes for a team-member console session. 3. Confirm the signed-in person and the account you intend to administer before viewing or changing resources. 4. Check the capabilities and permissions available to that person. If the required action is absent or denied, request the specific access needed from your administrator. Use the sign-in method issued for your account. Ask your administrator whether SSO is enabled before attempting to configure it; the additional options described here are planned. If your session expires or cannot refresh, sign in again to continue. Do not send session tokens or API key values when requesting help. ## 2. Choose the application the teammate will manage \{#scope-selection} **Status:** Upcoming — not yet available. The console shows the workspace, project, test/live mode and any selected application customer alongside your work. The current public API still uses the legacy default project and does not offer a public test mode. Use only the selections enabled for your account; changing a label or request header does not create isolation. To work in another project or customer account: 1. Choose the workspace and project you are authorized to administer. 2. Choose test or live, plus the customer where relevant. An unassigned selection shows records that do not belong to a customer. 3. Review the records loaded for that selection. 4. Recheck scope when opening a saved link or returning to an old tab. After you switch, the console shows the selected account’s records. Updates from the previous selection cannot replace the new view. If the visible resource and selected scope disagree, stop the action and report both identifiers through your account's support channel. Selecting all customers is an authorized read view, not permission for a bulk mutation. ## 3. Invite the teammate and preserve service ownership \{#people-and-credentials} **Status:** Upcoming — not yet available. For current key issuance or rotation, follow [Managing API keys](/api/authentication#managing-api-keys) through the enabled management surface or your account administrator. To give a teammate access: 1. Select the intended workspace or project and identify the person to invite. 2. Choose the minimum role needed for their tasks and distinguish a direct project assignment from inherited administrator access. 3. Invite the teammate. They verify their identity and accept the invitation before becoming a member. 4. Review the accepted membership and the projects the teammate can access. 5. When their role changes, review their resulting access and any service credentials that need attention. Keys belong to their **project and service**. Record the application/service owner, scope, expiry and responsible contact. The creator remains an audit record; removing that person’s access leaves independently owned service integrations running. If a secret was exposed, make a separate authorized rotation or revocation decision. These expanded ownership controls are not yet available. Human team membership and your application's end-user directory are separate. Creating or editing an end user does not invite that person to administer the workspace. Changes to branding, names or email domains do not grant access. For offboarding, remove the person’s management access and review any credential exposure as a separate decision. Independently owned service keys continue to support the application; rotate an exposed secret through its owning workflow, then verify the integration with the replacement. ## 4. Confirm access and unfinished setup \{#lists-and-status} **Status:** Upcoming — not yet available. After the teammate accepts, confirm which project access they have and whether any required connection setup is still pending. Keep membership status separate from integration readiness. If they can sign in but cannot perform the assigned task, compare the task’s required access with their effective assignment before granting more. When checking the teammate’s membership list, confirm the selected project and follow all result pages before concluding an assignment is absent. A partial page is not a complete access review. For a separate dashboard or usage investigation, inspect freshness and coverage before treating missing data as zero activity. [Trace and observation reads](/insights/evaluation/reading) describe the filters and cursors for that workflow. Provisioning, connection setup and cleanup can finish in separate steps. If activation fails after a connection is created, recover that connection’s setup. Keep the operation or resource reference before retrying an administrative write. ## Recover an interrupted invitation or account change \{#change-recovery} **Status:** Upcoming — not yet available. If a key, permission, connection, payment or deletion action loses its response: 1. Keep the original operation reference, target resource and submitted change. 2. Refresh or reopen the owning capability's status, using the same account and scope. 3. Determine whether the change completed, failed, remains pending or needs a specific follow-up. 4. If the outcome is unknown, ask the responsible account contact to reconcile it before submitting the change again. The console saves progress and outcomes so you can return to an interrupted change. For now, confirm the resource's actual state or ask your account contact; a spinner, success toast or browser error alone does not settle the result. Use this information in an administration request: Console change-recovery request template. * Signed-in account identity (no token): * Workspace / project / mode shown, where available: * Task and target resource reference: * Operation reference, if returned: * Last observed status and time: * Requested access or recovery action: When requesting help from Travila staff, agree which account, resources and actions the support request covers. Support access requires separate authorization and does not give your teammates access to another customer's content. Expanded support, audit and privacy controls are not yet available. ## Variants: rotate a key, inspect a connection or review usage \{#administration-tasks} **Status:** Upcoming — not yet available. Use these guides for the capability-specific workflow and API reference. A linked API operation does not imply that a corresponding console action is available. | Task | Continue with | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Obtain an application credential, select scopes or rotate a key | [Authentication and API keys](/core-platform/identity-access/authentication) and [Scopes and permissions](/core-platform/identity-access/scopes-permissions) | | Set up an application or plan workspace membership | [Workspaces and projects](/core-platform/workspaces-projects) | | Understand usage, an account restriction or payment status | [Billing and spend](/core-platform/billing-spend) | | Prepare an Enterprise offer, onboarding or a plan change | [Commercial agreements and invoicing](/enterprise/commercial-agreements#configure-and-review-quote) | | Manage profiles or inspect conversations | [Managed Agents](/managed-agents) | | Inspect traces, observations, scores or datasets | [Evaluation](/insights/evaluation) | | Configure webhooks or tools | [Integrations](/integrations) | | Store credentials used by a connection | [Project secrets](/core-platform/secrets) | | Request audit evidence, export or erasure | [Governance and privacy](/core-platform/governance-privacy) | --- URL: https://docs.travila.ai/core-platform/billing-spend # Understand usage, allowances and payments \{#overview} **Status:** Upcoming — not yet available. Use this recipe to take a trial agent into paid use without surprising the person responsible for the bill. Begin with the included allowance, choose what further spending the application may incur, and keep the usage and payment records needed to explain the first bill. Have an account administrator, an authorized payer and the applicable account terms available. Project setup, service credentials, spending permission and payment are separate steps; completing one does not complete the others. Negotiated prices, contracting parties and invoice review belong in [Commercial agreements and invoicing](/enterprise/commercial-agreements). For a commercial change, review the [standard-to-Enterprise conversion](/enterprise/commercial-agreements#standard-to-enterprise) or [downgrade path](/enterprise/commercial-agreements#downgrade-or-exit), including the effective date and treatment of existing usage and balances. **Available today:** Use the billing channel and terms supplied for your account. Self-service billing, comprehensive spending controls and separate test/live billing are planned; confirm the controls currently enforced for your account before sending paid traffic. This page publishes no allowance amount, price or payment deadline. ## 1. Try the application within the included allowance \{#included-allowance} **Status:** Upcoming — not yet available. Try the included allowance without entering payment details: 1. Create the [first project](/core-platform/workspaces-projects#first-project-setup), including its permitted region. 2. Review the configured allowance, which usage it covers, its scope and remaining balance. 3. Issue a credential for the application. Key creation does not purchase additional capacity. 4. Make a permitted first call. The same authorization and finite usage controls apply to that call and later calls. 5. When the allowance requires more funding, review the applicable terms before authorizing paid capacity. Project creation and key creation are separate steps. The allowance amount and eligible products remain account-specific, and free allowance does not authorize additional paid use. Self-service onboarding is not yet available. ## 2. Agree who pays before enabling paid use \{#paid-traffic} **Status:** Upcoming — not yet available. Before connecting a model or external service, review your account’s billing setup with the person authorized to approve spending: | Confirm | Why it matters | | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Account, application/project and payer | The person operating an application may differ from the organization responsible for its bill | | Active agreement or price revision and currency | An example price, provider estimate or future proposal does not establish your charge | | Included allowance, eligible usage and any expiry | Free use is finite; an allowance is separate from permission to incur additional charges | | Spending permission and funding limit | Choose how much paid work the application may accept; a usage chart or request-rate setting serves a different purpose | | Connected model, tool and payment accounts | External providers may charge separately; a test label does not make a connected live account free | | Billing contact and a way to track a question or payment | You need to recover an outcome after a lost response without starting a second payment | The current public API has no sandbox or separate test-key type. Use controlled fixtures, bounded concurrency and accounts you are authorized to exercise; see [Test your integration](/developer-experience/local-tooling/testing). A missing rate-limit header or a zero displayed balance is not permission for unlimited use. ## 3. Fund and limit the work you authorize \{#spending-and-funding} **Status:** Upcoming — not yet available. After the trial proves useful, agree the permitted application scope and spending amount with the authorized payer. Spending permission and funding are separate choices: review eligible work, currency, effective time and approval before enabling a limit, subscription or automatic top-up. For a top-up, also review the trigger, purchase terms and limits on further purchases. A saved payment method does not authorize every future purchase. Send a controlled first request, then inspect the usage record and remaining funding before expanding traffic. Spending controls account for concurrent, retried and delayed work before accepting another paid action. A displayed estimate, alert or per-minute request limit does not replace those controls. If required budget settings are missing, paid work stops with an explanation of what to configure. Before increasing a limit after work stops, identify the reason: | Reason to investigate | Next step | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | Allowance exhausted or spending permission insufficient | Review the applicable allowance or spending policy and obtain the required funding authorization | | Payment pending, declined or requiring authentication | Recover that payment's existing status and follow the authorized payment flow | | Security, membership or manual restriction | Resolve that restriction through the responsible administrator; paying alone does not clear it | | Usage or account state unavailable | Ask for reconciliation; do not assume missing state means remaining capacity | After funding is restored, confirm which work may resume. Previously skipped schedules should not be assumed to replay automatically. ## 4. Explain the first bill using the same usage period \{#usage-and-invoices} **Status:** Upcoming — not yet available. At the end of the first billing period, compare the account’s invoice with usage for that same period and timezone. Start with the application and model that incurred the charge, apply the accepted rate revision and account for credits or adjustments. If a row is missing or late, keep the reconciliation incomplete rather than treating it as free usage. Usage records explain consumption; an invoice applies your commercial terms. Model input/output tokens and generation counts can help explain a charge, but a usage report may omit other products or arrive late. Check its coverage and update time before treating it as a complete balance. Within that period, review: * The account and project that incurred the usage, with environment/customer attribution where the deployment supports it. * Quantity and unit, model or other charged capability, currency and the applicable rate revision. * The payer and billing period, including the effective date of any payer or price change. * The report's freshness, missing coverage and later corrections. The detailed usage view shows this attribution and identifies incomplete reporting. Until it is available, request a scoped explanation through your account's billing channel. See [Evaluation traces](/insights/evaluation/reading) for inspecting individual runs and [invoice review](/enterprise/commercial-agreements#invoice-review) for the commercial record. ## Recover an interrupted top-up or payment \{#payment-recovery} **Status:** Upcoming — not yet available. Use only the payment method and checkout route supplied for your account. Keep the original payment, purchase or top-up reference. If the browser closes or a request times out: 1. Reopen the existing operation or ask the billing contact to locate it using that reference. 2. Check whether the authoritative outcome is pending, requires action, failed or completed. 3. Complete any required authentication through the approved payment provider. 4. Reconcile an uncertain outcome before initiating a replacement payment. 5. Match any receipt, credit allocation or refund to the original operation. The account interface preserves payment status across retries. A successful redirect, submitted form or credit note alone does not prove money moved. Purchased credit becomes available only after the required payment confirmation. A granted credit, invoice adjustment and cash refund have different effects; request the applicable record. For a billing question, send a compact record through the agreed channel: Billing payment-recovery request template. * Account and project: * Invoice / payment / operation reference: * Affected period and timezone: * Affected usage or invoice line: * Expected terms or approved revision: * Observed status and when it was observed: * Requested clarification or correction: Do not include API keys, full card details or payment secrets. Keep the original invoice and any linked correction; changes to future terms preserve past charges and their history. The recovered outcome is the original payment’s confirmed status and any linked credit, receipt or refund. If it remains unknown, keep that payment under investigation. A second payment is a new financial action, not a way to refresh the first one. ## Variant: charge your own customers or approve a purchase \{#customer-billing-and-purchases} **Status:** Upcoming — not yet available. Manage catalogs, subscriptions, usage charges, invoices and exports for your application's customers separately from your own Travila bill. These customer-billing operations do not yet have a public API. Paying Travila does not authorize a charge to one of your customers. For a conversational purchase, the shopper reviews the merchant, items, complete amount and currency, delivery details and quote expiry, then approves those exact terms. A changed quote requires renewed approval. Purchase and payment status remain available after an interruption, so the shopper can check whether an order completed before trying again. For account ownership and credentials, continue with [Workspaces and projects](/core-platform/workspaces-projects). For negotiated pricing, payer consent and invoice disputes, use [Commercial agreements and invoicing](/enterprise/commercial-agreements). --- URL: https://docs.travila.ai/core-platform/governance-privacy # Privacy and governance preview \{#overview} **Status:** Upcoming — not yet available. **Available today:** use the privacy or account contact supplied by your application operator or contracting party. Establish identity, authority, application and requested scope through that channel. Account-wide privacy requests, audit exports, configurable retention, regional controls, key IP restrictions and a published webhook address list are planned. This guide does not provide a self-service governance console or current API commands for those features. ## Choose the requested outcome \{#request-types} **Status:** Upcoming — not yet available. Distinguish access or export, profile reset, erasure, withdrawal of optional consent and deletion of one resource. They have different scope and consequences. Deleting a file, memory or profile does not establish platform-wide erasure, and matching email addresses do not authorize combining identities across applications. ## Prepare the request \{#request-scope} **Status:** Upcoming — not yet available. Use the operator’s verified channel and identify the application/account, person, requested action and data categories or time range. Include project, customer and mode where they exist. Ask for the accepted scope, reference and next step; submission alone does not prove that processing has stopped. Send identity evidence only through the approved verification channel. Do not include passwords, API keys, full identity documents or unrelated personal records in an ordinary support message. ## Review an authorized copy \{#export-review} **Status:** Upcoming — not yet available. The planned export path would identify its approved scope, generation time, formats and missing or excluded categories. A file listing is not the original content. Retrieve and store a copy only through authorized routes; link expiry does not erase retained copies or authorize forwarding the archive. ## Cleanup and retained exceptions \{#privacy-progress} **Status:** Upcoming — not yet available. The planned report separates verification, processing restrictions, active cleanup, provider or backup retention, approved holds and unresolved failures. A partial result is not completed erasure. Completion needs evidence accounting for each required system and permitted exception; no universal completion deadline is promised. Delayed jobs and restoration must respect an accepted erasure restriction. Already-dispatched provider actions require separate reconciliation. ## Purpose-specific consent and retention \{#consent-and-retention} **Status:** Upcoming — not yet available. The proposed controls distinguish a purpose’s effective consent from retention, reset or erasure of its existing data. A device permission or notification setting is not consent for every purpose, and unrelated required functionality should remain separate from optional uses. Cross-customer content improvement is intended to be off by default. Use only commitments approved for your account. A retention policy must account for holds, providers, backups and pending cleanup; a general label does not describe every copy. ## Governance evidence \{#audit-evidence} **Status:** Upcoming — not yet available. The planned audit view would identify actor, scope, authorization decision, action outcome, observation time and coverage gaps. Permission to act does not prove an action completed. Bounded exports and security-monitoring integrations require authorized recipients and setup; retained audit records do not establish a certification. ## Region and network requirements \{#region-and-network-controls} **Status:** Upcoming — not yet available. Confirm any offered region and its actual coverage for computation, storage, backups, support and onward transfers with your operator. No regional or IP restriction is enabled by this guide. Project-region changes would require an authorized migration; names and labels are not location commitments. For webhook source allowlisting, obtain the deployment’s verified address list and change policy. Do not derive a permanent range from one delivery. IP matching supplements HTTPS and [signature verification](/integrations/webhooks); it does not authenticate the delivery or account by itself. Use [Files](/core-platform/files-data), [Project secrets](/core-platform/secrets) and [Console administration](/core-platform/console-administration) for individual operations and their limitations. --- URL: https://docs.travila.ai/insights # Insights \{#insights} Find why an agent reply failed, compare a proposed change against known examples, or explain a change in usage and cost. Start with the task below; each guide identifies its availability and setup requirements. | Start with this problem | Follow this recipe | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A user received a poor or slow reply | [Inspect the turn](/insights/evaluation/reading), [review the answer](/insights/evaluation/review), then [keep a regression case](/insights/evaluation/datasets-and-runs) | | A prompt or model change may break working answers | [Compare both configurations on the same examples](/insights/evaluation/datasets-and-runs) | | Users need to tell you whether a reply helped | [Build message feedback](/insights/evaluation/message-feedback) | | Usage or cost increased unexpectedly | [Investigate the changed population and representative requests](/insights/usage-cost) | | Your team needs to hear about sustained failures | [Configure and follow an alert](/insights/alerts) — Upcoming, not yet available | Start with one real problem and retain the result: a reviewed turn, a versioned comparison, a saved user rating or an explanation of cost. [Evaluation setup](/insights/evaluation) identifies the account and credential prerequisites. Use the [API reference](/api/evals) for complete request fields. --- URL: https://docs.travila.ai/insights/evaluation # Measure and improve quality \{#measure-and-improve-quality} Improve an answer your customers struggle to use, and keep that improvement from breaking other answers. Start with one real reply, have a reviewer explain the problem, then compare a change against the same known examples. ## Choose the problem to solve \{#start-here} | The problem in your application | Recipe | | ------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | A reply was slow, failed or received a poor rating | [Investigate the turn and its recorded steps](/insights/evaluation/reading) | | Your team needs to judge replies consistently | [Run a review queue with a shared rubric](/insights/evaluation/review) | | A prompt or model change might break a previously good answer | [Compare both versions on a regression dataset](/insights/evaluation/datasets-and-runs) | | Users need to say whether a reply helped | [Add message feedback to the conversation](/insights/evaluation/message-feedback) | ## Before you start \{#projects} Have evaluation enabled for your account, permission to inspect the selected conversations, and controlled test data and spending for any reruns. An HTTP `424` means evaluation is not provisioned; ask your operator to enable it rather than repeating the request. The current API uses the legacy `default` project, without separate project, test/live or customer isolation created by a header. Use the account’s supported API version. The [trace recipe](/insights/evaluation/reading) explains redaction and collecting complete results; the [review recipe](/insights/evaluation/review) explains reviewer identity and current mutation limits. Use the [Evaluation API reference](/api/evals) for exact operation fields. ## Turn one poor reply into a tested improvement \{#the-two-loops} 1. [Find the reply’s recorded steps](/insights/evaluation/reading#find-traces) and identify what went wrong. Keep missing or redacted context visible; absent telemetry does not prove an action never occurred. 2. [Review the answer](/insights/evaluation/review) against a shared rubric and save the reason for the judgment. Keep customer sentiment, expert review and automated scores separate. 3. [Create a regression case](/insights/evaluation/datasets-and-runs) with the input needed to reproduce the problem and an expert-reviewed expectation or objective validator. An observed model answer is not automatically ground truth. 4. Run the baseline and candidate against the same eligible cases in your test harness. Constrain tools and spending; recording a dataset run does not execute its cases. 5. Compare actual outcomes with failed, excluded and missing cases visible, then decide whether to adopt the change. Save the configuration and results with that decision. You finish with a specific problem, its reviewed explanation and a comparison another reviewer can inspect. The current API stores evaluation evidence; it does not automatically change the serving prompt or train a model. The recipes cover the current workflow; the additions below describe the upcoming review and comparison experience. ## Upcoming: revise a review without losing its history \{#review-provenance} **Status:** Upcoming — not yet available. Open the reviewed item and rubric version, edit under your own reviewer identity, and save. If the review changed meanwhile, resolve the conflict against the current version. The history keeps the author, rubric and earlier judgments attached to the item, with customer opinion, expert annotation and automated results distinguishable. Withdrawal requires the permitted author or administrator action. These revision and ownership controls are not available in the current scoring and comment APIs. Keep current score deletion in trusted administrative tooling as described in [review withdrawal](/insights/evaluation/review#withdraw-a-rating). ## Upcoming: repeat a release comparison from saved versions \{#reproducible-comparisons} **Status:** Upcoming — not yet available. Select a versioned dataset, saved baseline and candidate configurations, and scoring rubric. Run both on the same eligible cases, then inspect per-item scores and the evaluated, failed, excluded and missing counts. Review incomplete coverage and uncertainty before approving the change. Keep those versions with the decision so another reviewer can repeat the comparison. All permitted result pages remain available to inspect, and a deleted result keeps an explicit outcome. For the current API, save the full harness configuration and reconcile outcomes using the [dataset recipe](/insights/evaluation/datasets-and-runs); mutable dataset records or a supplied profile hash alone do not capture a reproducible experiment. --- URL: https://docs.travila.ai/insights/evaluation/datasets-and-runs # Replay datasets and runs \{#replay-datasets-and-runs} Check that a prompt or model change still handles the examples your application depends on. Build a **dataset** of those examples with expected behavior or a stated scoring rubric, then use your test harness to run the baseline and candidate against the same set. A **run** records the outcomes your evaluation harness submits. For reproducible comparisons, keep the versioned eligible set and failed or excluded cases in your harness manifest; a stored run does not guarantee that every item was evaluated. Dataset and run management accepts a public API key. Replaying cases through a conversation also needs the authorized user identity required by the message operation. Recording human scores needs a verified reviewer identity; see [review and scoring](/insights/evaluation/review). ## The loop \{#the-loop} Use a failed customer reply as a regression case before changing the prompt. You need evaluation enabled, permitted source input, a reviewed expectation and a test harness that can run both configurations. Keep real recipients and effectful tools out of the replay unless the test explicitly authorizes them. The workflow below creates the dataset, curates its inputs and expectations, runs your harness, and compares the results. Current APIs do not automatically freeze full conversation/tool context or execute the dataset. Keep the harness manifest and item outcomes as the comparison record when platform run association is unavailable. [Dataset replay and comparison loop](/diagrams/1qobmu47dp) An application creates a dataset, curates inputs and expectations, runs its harness, records the experiment and reads stored run results. ```mermaid flowchart LR accTitle: Dataset replay and comparison loop accDescr: An application creates a dataset, curates inputs and expectations, runs its harness, records the experiment and reads stored run results. A["create-dataset"] --> B["add-dataset-item\n(harvest the turn)"] B --> C["update-dataset-item\n(author the expectation)"] C --> D["your harness runs"] D --> E["record and verify the experiment"] E --> F["list-dataset-runs"] F --> G["get-dataset-run"] ``` ## 1. Create the dataset \{#1-create-the-dataset} [Request example: Create a dataset](/api/evals/create-dataset#example-cookbook-insights-evaluation-datasets-and-runs-01-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. Name it for what it protects. Runs are addressed by dataset name plus run name, so the name is a durable handle, not a label. ## 2. Save the input needed to reproduce the problem \{#2-harvest-turns-into-it} A turn address establishes source lineage. The current operation does not fetch the trace or conversation input; supply the intended [`inputJson`](/api/evals/add-dataset-item#request-field-inputjson) explicitly, after applying your data policy: [Request example: Add a dataset item](/api/evals/add-dataset-item#example-cookbook-insights-evaluation-datasets-and-runs-02-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. Read and curate the permitted source input explicitly. Keep its redaction, omissions and fixture provenance with the case; see [input capture and replacement behavior](/api/evals/add-dataset-item#overview). ## 3. Define what an acceptable answer must do \{#3-author-the-expected-output} Use an expert-reviewed answer, a deterministic validator or another qualified reference with recorded provenance. Automated construction can be useful, but a candidate model's own answer is not ground truth. Some evaluations use a rubric instead of an exact expected answer; specify which contract each item requires. List cases that still need an expected output: [Request example: List dataset items](/api/evals/list-dataset-items#example-cookbook-insights-evaluation-datasets-and-runs-03-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. Use the identifier expected by each operation; the [dataset identifier reference](/api/evals/datasets#dataset-identifiers) records the current differences. Then fill each one in: [Request example: Update a dataset item](/api/evals/update-dataset-item#example-cookbook-insights-evaluation-datasets-and-runs-04-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. > **Warning: Curate and count exclusions explicitly** > > The current record/replay operations do not automatically skip items with missing expectations. Your harness must enforce the evaluator's prerequisites and report failed, excluded and unevaluated counts separately. Never count an item with nothing scored as a pass, or silently reduce the denominator. ## 4. Run both configurations and retain their outcomes \{#4-record-the-run} Before sending the evaluation turns: 1. Freeze the cases and the inputs/tools/memory fixtures the harness will use. 2. Run the baseline and candidate under the same relevant conditions and limits. 3. Keep a result for every eligible case: evaluated, failed, excluded or not evaluated, with the reason. 4. Preserve the configuration, rubric and item versions with those outcomes. 5. Attribute each turn to its run when you send it, then read the expected run back. A turn joins a dataset run only through the [`experiment`](/api/conversations/send-message-sync#request-field-experiment) block on the message that starts it — `send-message-sync` or `send-message`. There is no call that associates a trace with a run after it has been recorded. Send one turn per case, each carrying the dataset, the run name and the case's dataset item: [Request example: Send a message and wait for the result](/api/conversations/send-message-sync#example-cookbook-insights-evaluation-datasets-and-runs-05-request). 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. * [`datasetId`](/api/models/schema-1icbr3lltu#request-field-datasetid) is the dataset's ID as returned by `create-dataset` or `list-datasets`, not its name. * [`runName`](/api/models/schema-1icbr3lltu#request-field-runname) names the run. Reusing a run name for the same dataset adds turns to that run. * [`datasetItemId`](/api/models/schema-1icbr3lltu#request-field-datasetitemid) identifies the case this turn exercises. Set it on every turn of a run: turns sent without it currently land in a different run from turns that carry it, even under the same run name. * [`description`](/api/models/schema-1icbr3lltu#request-field-description), [`metadataJson`](/api/models/schema-1icbr3lltu#request-field-metadatajson) and [`profileRevisionHash`](/api/models/schema-1icbr3lltu#request-field-profilerevisionhash) are optional run metadata; see [association limits](/api/evals/datasets#run-association). With `send-message`, the call returns before the turn finishes; wait for the turn to complete before reading the run back or scoring it. A run name or success response is not a substitute for the harness’s actual results: read the expected run back with `list-dataset-runs`, which takes the dataset **name**, and keep the harness manifest and item outcomes when an expected run or item is missing. ## 5. Decide whether the change fixes the problem without regressions \{#5-compare} Join baseline and candidate by the same versioned case, inspect changed outcomes, and review failures alongside score differences. Accept a change only against your stated criteria; keep inconclusive or missing results visible. Use the following reads to locate supported platform run records, then reconcile them with your harness report. [Request example: List dataset runs](/api/evals/list-dataset-runs#example-cookbook-insights-evaluation-datasets-and-runs-06-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** [Response example: List dataset runs](/api/evals/list-dataset-runs#example-cookbook-insights-evaluation-datasets-and-runs-json-01-response). Example identifiers and values are illustrative; substitute authorized values. Continue through all result pages and compare them with the harness record. Use the [pagination and enrichment contract](/api/evals/datasets#run-reading) when a count or expected run is missing. Then pull one run by **dataset name and run name** — not by [`runId`](/api/models/schema-1jehhpchdc#response-field-runid): [Request example: Get a dataset run](/api/evals/get-dataset-run#example-cookbook-insights-evaluation-datasets-and-runs-07-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** [Response example: Get a dataset run](/api/evals/get-dataset-run#example-cookbook-insights-evaluation-datasets-and-runs-json-02-response). Example identifiers and values are illustrative; substitute authorized values. Use the harness manifest to join baseline and candidate by the same versioned [`datasetItemId`](/api/models/schema-1icbr3lltu#request-field-datasetitemid). `get-dataset-run` returns a run summary, not item-level results. Read scores through [list-scores](/insights/evaluation/reading#read-scores) using verified run associations, and reconcile them with expected, failed and excluded cases; a returned run ID alone does not establish complete results. ### Browse the datasets \{#browse-the-datasets} [Request example: List datasets](/api/evals/list-datasets#example-cookbook-insights-evaluation-datasets-and-runs-08-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** [Response example: List datasets](/api/evals/list-datasets#example-cookbook-insights-evaluation-datasets-and-runs-json-03-response). Example identifiers and values are illustrative; substitute authorized values. Confirm execution from the expected run and harness record; [history enrichment limits](/api/evals/datasets#run-reading) can leave summary counts incomplete. ## Maintain the regression set as the application changes \{#keeping-a-dataset-honest} Two failure modes are worth designing against, because neither announces itself: **Frozen context ages.** Explicitly captured inputs and fixtures preserve selected context from a turn. The current API does not automatically capture memory, tools or prompt variables as a frozen fixture. A complete versioned manifest helps make runs comparable, and it is also what makes a two-year-old golden set measure a world that no longer exists. Re-harvest from recent traffic periodically and version the dataset name so a run declares which vintage it measured. **Control the comparison.** Hold unrelated variables and the dataset version fixed when isolating one cause. If you intentionally test a combined change, label it as such. Report sample sizes, missing outcomes and uncertainty; a score difference alone does not establish causation. ## Experiment context at message ingress \{#experiment-context-at-ingress} A turn is attached to a dataset run when you send it: set the [`experiment`](/api/conversations/send-message-sync#request-field-experiment) block on `send-message-sync` or `send-message`. [Step 4](#4-record-the-run) shows the request. * [`datasetId`](/api/models/schema-1icbr3lltu#request-field-datasetid) and [`runName`](/api/models/schema-1icbr3lltu#request-field-runname) are required. Use the dataset ID returned by `create-dataset` or `list-datasets`, not the dataset name. * There is no later association call; a turn sent without the block is not part of any run. * A successful send does not confirm the run was recorded. Read the run back with `list-dataset-runs` and keep your harness manifest. --- URL: https://docs.travila.ai/insights/evaluation/message-feedback # Collect message feedback \{#collect-message-feedback} Let users say whether an assistant reply helped, with a thumbs-up/down or a 1–10 rating and optional explanation. Each rating belongs to a specific message and rater and is stored with the conversation. Use a completed assistant reply for this control. See [message rating and analytics projection](/api/evals/scoring#message-rating) for eligibility and when the saved rating appears in analytics. ## Save the user’s judgment beside the reply \{#rate-a-message} Build the thumbs-up/down control beside a completed assistant reply. Load the conversation’s existing ratings, render the current user’s choice, then send their change for that message’s sequence. Allow an optional explanation, especially when the reply did not help. 1. Keep the conversation key and assistant message sequence with the rendered reply. 2. Authenticate the rater; do not let the client supply another person as the author. 3. Submit the selected rating below and render the returned stored result. 4. On a lost response, reload the conversation’s ratings before sending another change. 5. Let the user withdraw the rating and show the stored state again. A rating saved on the message is the immediate result. Its evaluation copy can arrive later, so analytics delay must not make the conversation’s saved rating disappear. Messages are addressed by their per-conversation [`messageSequence`](/api/conversations/rate-message#request-field-messagesequence), not by an ID. [Request example: Rate an assistant message](/api/conversations/rate-message#example-cookbook-insights-evaluation-message-feedback-01-request). 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. **Response:** [Response example: Rate an assistant message](/api/conversations/rate-message#example-cookbook-insights-evaluation-message-feedback-json-01-response). Example identifiers and values are illustrative; substitute authorized values. Render the returned stored rating state; the [rating response contract](/api/evals/scoring#message-rating) defines replacement and the list of raters. ### Variant: use a 1–10 scale instead of thumbs \{#two-rating-styles} Choose thumbs for a simple helpful/not-helpful choice, or a 1–10 scale for a more detailed survey. Use the corresponding [rating fields](/api/conversations/rate-message#overview). [Request example: Rate an assistant message](/api/conversations/rate-message#example-cookbook-insights-evaluation-message-feedback-json-02-request). Example identifiers and values are illustrative; substitute authorized values. Collect an optional explanation, especially when a reply did not help. Serialize rapid changes and show the stored result; [attribution and ordering rules](/api/conversations/rate-message#overview) apply. ## Restore the same feedback after reopening the conversation \{#reading-ratings-back} Load the conversation history and render its stored ratings; see [feedback reads](/api/evals/scoring#rating-reading) for the response field and supported write paths. For aggregate analysis — how a profile scores across conversations, user ratings next to reviewer ratings — read them through the [Evals scores API](/insights/evaluation/reading#read-scores) instead of walking conversations. ## Let the user remove their judgment \{#withdraw-a-rating} When the user clears their selected rating, submit the withdrawal request below. [Request example: Withdraw your rating on a message](/api/conversations/delete-message-rating#example-cookbook-insights-evaluation-message-feedback-02-request). 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. **Response:** [Response example: Withdraw your rating on a message](/api/conversations/delete-message-rating#example-cookbook-insights-evaluation-message-feedback-json-03-response). Example identifiers and values are illustrative; substitute authorized values. Reload the stored rating state after withdrawal. The [withdrawal response](/api/evals/scoring#rating-reading) distinguishes removal from an already-absent rating. --- URL: https://docs.travila.ai/insights/evaluation/reading # Find out why a customer’s reply was slow \{#read-traces-and-scores} A customer reports that the assistant took too long to answer. Find that reply, identify the recorded model or tool step involved, and save the evidence needed to fix or reproduce the problem. **Before you start:** have evaluation enabled, an authorized backend credential, and the conversation/source-message identity or a profile and time window for the report. Restrict who can inspect the trace: configured redaction can make its text incomplete, and does not guarantee that all confidential information is removed. Show [`contentRedacted`](/api/evals/list-observations#response-field-contentredacted) results as redacted. These examples use the cursor API. Confirm it is available for your account; older deployments use `page`. Use the exact schema for your deployment. Replace the sample identifiers and times with those from the reported interaction. ## Find the reply the customer reported \{#find-traces} If your application saved the conversation and source user message, skip to the [detail read](#open-one-trace). Otherwise, search the affected profile and time window: [Request example: List traces](/api/evals/list-traces#example-cookbook-insights-evaluation-reading-01-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. Match the returned conversation, user and timestamp to the report and keep its trace ID. Use the recorded error counts and latency to choose a candidate, then confirm its identity before diagnosing it. Missing telemetry is a gap to investigate, not proof that the turn succeeded or never ran. Narrow the profile and time window when you need fewer candidates. See [supported trace filters](/api/evals/list-traces#overview) before adding search criteria. ## Locate the slow or failed step \{#open-one-trace} Open the selected trace using its ID or the conversation and source user message: [Request example: Get a trace](/api/evals/get-trace#example-cookbook-insights-evaluation-reading-02-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. Use the saved source user message or trace identity, following the [trace address contract](/api/evals/get-trace#overview). Inspect the returned observations for the relevant model, memory or tool step. Compare its timing and status with what the customer saw. Separate a slow tool request from the model's own generation time before choosing a fix. The [get-trace reference](/api/evals/get-trace) defines the detail response. If an expected step is missing, continue with [observation search](#observations-across-traces) and retain the known coverage limits from the [detail contract](/api/evals/get-trace#overview). ## Read judgments about that same reply \{#read-scores} Read the conversation's scores and select those attached to the trace you are investigating: [Request example: List scores](/api/evals/list-scores#example-cookbook-insights-evaluation-reading-03-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. An illustrative reviewer result looks like: [Response example: List scores](/api/evals/list-scores#example-cookbook-insights-evaluation-reading-json-01-response). Example identifiers and values are illustrative; substitute authorized values. Match the trace ID and score source. A reviewer saying that the answer buried the useful number explains a different problem from a tool timeout; preserve both observations when both apply. Keep customer sentiment, expert review and automated measurements separate using the [review guide](/insights/evaluation/review#never-blend-score-sources). Collect all continuation pages before comparing judgments. The [score filter contract](/api/evals/list-scores#overview) explains narrowed pages and the current zero-bound limitation. You finish the investigation with the reported turn, a specific observed delay or failure, relevant judgments, and any missing context. Save that permitted evidence for a [review](/insights/evaluation/review) or [regression case](/insights/evaluation/datasets-and-runs). Copy source input explicitly when creating a case; a trace address does not automatically capture it. ## Check whether the same tool keeps failing \{#observations-across-traces} If the affected step is a tool call, look for similar errors in other permitted traces. This query selects error observations: [Request example: List observations](/api/evals/list-observations#example-cookbook-insights-evaluation-reading-04-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. [Response example: List observations](/api/evals/list-observations#example-cookbook-insights-evaluation-reading-json-02-response). Example identifiers and values are illustrative; substitute authorized values. In this illustrative result, the weather tool reports an upstream timeout after 30 seconds. Open the related trace and inspect the connection and retry outcome; do not assume the model alone caused the delay. [`parentObservationId`](/api/models/schema-1ju9tclufp#response-field-parentobservationid) links the tool step to the generation that requested it. Compare the same tool and relevant time window, keeping incomplete coverage visible. The [observation reference](/api/evals/list-observations) supplies the exact filters and result fields. ## Investigate a complaint that spans several turns \{#sessions} When one turn looks normal but the customer describes a poor overall interaction, [list sessions](/api/evals/list-sessions) for the intended user and time window. Open the relevant [session](/api/evals/get-session), then inspect its traces using the steps above. Deduplicate collected sessions and keep incomplete coverage visible; see [session summary limits](/api/evals/get-session#overview). ## Decide whether the incident reflects a broader trend \{#the-overview-dashboard} Use the [evaluation overview](/api/evals/get-overview) to compare the affected profile's latency and scores with broader activity. Keep each measure’s population, time window and full configuration explicit before attributing a difference to one change. The [overview reference](/api/evals/get-overview#overview) explains sampling and configuration identity. ## Narrow a follow-up investigation \{#structured-filters} When the profile/time query is too broad, use a supported column predicate from the [trace reference](/api/evals/list-traces). Match the value field to the predicate's declared type. For a single slow step, query observations or analyze an explicitly collected dataset. See [supported aggregate filters](/api/evals/list-traces#overview). ## Recover incomplete or interrupted result collection \{#version-and-pagination-boundary} Continue through every returned cursor while keeping the original filters and time window. Preserve collected identities and known coverage when interrupted; follow the [cursor contract](/api/evals/datasets#pagination) to resume safely. --- URL: https://docs.travila.ai/insights/evaluation/review # Review and score turns \{#review-and-score-turns} Review replies that need a person’s judgment, such as an answer that is accurate but hard to use. Give reviewers a common rating scale, queue the turns and record both scores and explanations. Use the reviewed examples to improve regression datasets and calibrate automated judges. > **Warning: This loop needs a user identity** > > `record-score` rejects a bare API key because the score must be attributable to a reviewer. Use an authorized public API key with verified [`X-On-Behalf-Of`](/api/authentication#acting-as-a-user--x-on-behalf-of); console JWTs belong to the separate console surface. Score configs, queues and comments accept a bare key. See [record-score](/api/evals/record-score) for the exact contract. ## The loop \{#the-loop} Build a weekly review queue for coaching replies whose helpfulness needs a person’s judgment. You need evaluation enabled, a backend credential, a verified reviewer identity for scoring, and trace IDs from the [investigation recipe](/insights/evaluation/reading). 1. Define a shared helpfulness scale and an explanation of what each rating means. 2. Create a queue using that score configuration and add the selected traces. 3. Let the reviewer read a queued trace, record the score and explain it. 4. Complete the queue item only after the review is saved. 5. Turn a useful failure into a curated regression case. The result is a completed work item plus an attributable judgment. Completing the queue is a separate operation from saving the score; neither guarantees that the judgment is correct. Record the score and any explanatory comment before completing the queue item. These are separate actions: 1. [Create the score configuration](/api/evals/create-score-config) 2. [Create the annotation queue](/api/evals/create-annotation-queue) 3. [Enqueue items](/api/evals/enqueue-for-annotation) 4. [List queue items](/api/evals/list-annotation-queue-items) 5. [Record a score](/api/evals/record-score) 6. [Create a comment](/api/evals/create-comment) 7. [Complete the annotation queue item](/api/evals/complete-annotation-queue-item) ## Keep reviewer judgments separate from user sentiment \{#never-blend-score-sources} Keep customer sentiment, expert review and automated measurements separate. Choose the [score source](/api/evals/scoring#score-sources) for the question you are answering before computing an aggregate; use reviewer scoring for this workflow. ## 1. Define the dimensions first \{#1-define-the-dimensions-first} A score config is a rating scale. Reviewers pick from it rather than inventing their own, which is what makes two reviewers' labels comparable. [Request example: Create a score config](/api/evals/create-score-config#example-cookbook-insights-evaluation-review-01-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. Create and save a numeric or boolean trace-scoring configuration before recording ratings. Use the [supported write and configuration contract](/api/evals/scoring#score-writes) when designing a different scale. ## 2. Queue what needs reviewing \{#2-queue-what-needs-reviewing} Save the returned configuration ID and replace `cfg_helpfulness` below with it. A queue is a worklist bound to a fixed set of configs, so everyone reviewing from it scores the same dimensions. `create-annotation-queue` requires at least one entry in [`scoreConfigIds`](/api/evals/create-annotation-queue#request-field-scoreconfigids) — a queue with no configs is rejected. [Request example: Create an annotation queue](/api/evals/create-annotation-queue#example-cookbook-insights-evaluation-review-02-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. Save the returned queue ID and replace `q_weekly` in later requests. Enqueue the trace you want reviewed, using `EVAL_TARGET_TYPE_TRACE` for the currently qualified score path. The [target-type contract](/api/evals/enqueue-for-annotation#request-field-targettype) lists other target kinds; their presence in the enum does not qualify them for this scoring recipe. [Request example: Enqueue an item for annotation](/api/evals/enqueue-for-annotation#example-cookbook-insights-evaluation-review-03-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. ### Pull the worklist \{#pull-the-worklist} [Request example: List annotation queue items](/api/evals/list-annotation-queue-items#example-cookbook-insights-evaluation-review-04-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** [Response example: List annotation queue items](/api/evals/list-annotation-queue-items#example-cookbook-insights-evaluation-review-json-01-response). Example identifiers and values are illustrative; substitute authorized values. Open the queued trace and retain separate evidence when you need durable completion attribution; see [queue addressing](/api/evals/list-annotation-queue-items#overview) and [completion attribution](/api/evals/complete-annotation-queue-item#overview). ## 3. Record the rating \{#3-record-the-rating} Read the trace and apply the configured rubric before submitting the score. Use the reviewer’s verified identity and the saved score-config ID. After saving, read the stored score; serialize repeat actions so a delayed request cannot silently become a second review. [Request example: Record a score](/api/evals/record-score#example-cookbook-insights-evaluation-review-05-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `X-On-Behalf-Of: reviewer@yourcompany.com`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. Reconcile the stored score after repeated actions; see [reviewer identity and replacement limits](/api/evals/scoring#score-writes). ## Save the explanation with the reviewed turn \{#comments} Explain why the reply received its rating, such as a tool returning stale data. Attach the comment to the same reviewed trace and supply the reviewer’s identity so another person can understand who made the observation: [Request example: Create a comment](/api/evals/create-comment#example-cookbook-insights-evaluation-review-06-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `X-On-Behalf-Of: reviewer@yourcompany.com`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. Keep the returned comment ID, then [read the trace’s comments](/api/evals/list-comments) to confirm the explanation was saved before completing the review. Keep the note relevant and under the 3000-character limit; longer content is rejected. A bare-key comment has no author. The [comment reference](/api/evals/create-comment) defines other supported targets. For this queue, continue using the trace you scored. If an authorized administrator needs to remove a note, [delete-comment](/api/evals/delete-comment) suppresses it from the list while retaining the record for audit. It does not erase every retained copy. ## 4. Complete the saved review \{#mark-it-done} Call this after recording the rating and any explanatory comment, not when the reviewer merely opens the task. If recording failed, leave the item pending while you recover the score. Keep separate evidence if you need durable completion-author attribution: the current completion operation does not retain it. [Request example: Complete an annotation queue item](/api/evals/complete-annotation-queue-item#example-cookbook-insights-evaluation-review-07-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `X-On-Behalf-Of: reviewer_9`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** [Response example: Complete an annotation queue item](/api/evals/complete-annotation-queue-item#example-cookbook-insights-evaluation-review-json-02-response). Example identifiers and values are illustrative; substitute authorized values. Completing is what stops an item being handed out again — it is **not** implied by recording a score. A reviewer who scores but never completes leaves the item in the pending pool for the next person. ## Closing the loop \{#closing-the-loop} A reviewer who finds a bad turn should not stop at scoring it — add it to a dataset so it becomes an explicit regression case. Supply the input and reviewed expectation as described in [dataset curation](/insights/evaluation/datasets-and-runs#2-harvest-turns-into-it); the turn address alone does not capture the context. Human review can provide calibration examples for an automated judge. Use a clear rubric, resolve reviewer disagreements and evaluate the judge on separate examples. Completing a queue alone does not establish that its labels are correct or that the judge will be reliable on other cases. ## Choose a different rating scale \{#score-config-types-in-depth} The recipe uses a 1–5 helpfulness rating. Use boolean trace scoring when a simple pass/fail judgment better matches the criterion. The schema also names categorical/text and other target types, but the current score write path supports numeric/boolean values on traces only. Numeric bounds are UI hints, not enforced score limits; validate the reviewer’s choice in your application. The data type and categorical values cannot change after creation. For a different scale, create a new configuration so earlier scores retain their meaning. See the [score-configuration reference](/api/evals/create-score-config) for exact settings. ## Retire a rubric without reinterpreting earlier scores \{#list-and-retire-configs} When the helpfulness rubric changes, [list its configurations](/api/evals/list-score-configs), archive the old one through [update-score-config](/api/evals/update-score-config), and create a replacement. Configurations are archived rather than deleted so earlier scores keep their reference. Include archived configurations when displaying historical reviews. Changing a used configuration’s numeric bounds does not rescale its earlier scores; prefer a replacement when the meaning of the scale changes. Use the returned new configuration ID for future queues and scores. ## Return to an existing review queue \{#find-the-queues} Save the queue ID created for weekly review. When reviewers return, use that identity to [load its pending items](#pull-the-worklist) rather than creating another queue. If the application needs a queue picker, use [list-annotation-queues](/api/evals/list-annotation-queues) and its pagination contract. Confirm the chosen queue’s rubric before presenting its work; a similarly named queue can use a different scoring configuration. ## Withdraw a rating \{#withdraw-a-rating} [Request example: Delete a score](/api/evals/delete-score#example-cookbook-insights-evaluation-review-08-request). Example identifiers and values are illustrative; substitute authorized values. Example request headers: `X-API-Key: sk_your_key_here`; `X-On-Behalf-Of: reviewer@yourcompany.com`; `Content-Type: application/json`. Replace the credential and user placeholders with your own authorized values. **Response:** Illustrative response shape; omitted default fields and actual outcomes depend on the operation. [Response example: Delete a score](/api/evals/delete-score#example-evals-deleteScore-response). Example identifiers and values are illustrative; substitute authorized values. Use trusted administrative tooling for this operation and read back the result, allowing for delayed views. The [score deletion contract](/api/evals/delete-score#overview) explains the current authorization limit. --- URL: https://docs.travila.ai/insights/usage-cost # Interpret usage, cost and diagnostics \{#interpret-usage-cost-and-diagnostics} Use usage evidence to explain activity, investigate a request and compare the cost of operating an agent. Start by identifying what each number measures: provider-reported usage, an estimate, an allocation and a customer charge answer different questions. Generation responses/events and evaluation reads expose selected usage and cost information. Use the schema deployed for your project and keep unavailable values distinct from zero. ## 1. Compare the same application usage before and after the change \{#choose-a-comparable-population} Use this recipe when the cost of your coaching assistant rose after a change. Start with the previous and current periods, the affected model/profile and the release or configuration change you want to investigate. 1. Choose comparable periods and the same application/customer population. 2. Separate higher usage from a changed model rate or a changed allocation method. 3. Inspect representative runs for extra attempts, longer prompts, tool activity or failures. 4. Account for missing or delayed observations before estimating the size of the change. 5. If the invoice still differs, take the period, scope and rate basis into [billing review](/core-platform/billing-spend#usage-and-invoices). The result is an explanation with a known measurement basis and remaining gaps, not a claim that a trace estimate is the final charge. Before comparing two periods or models, keep the project, test/live environment, customer audience, timezone and time window explicit. Check whether a chart counts logical runs, provider attempts, messages or observations. Retries can add attempts and cost without adding a new user turn. A useful report identifies its source, unit, time range, last refresh and known gaps. A missing observation is not a measured zero. Keep filters and time bounds fixed while paging or exporting, and discard results from a previous scope after changing project or audience. [Evaluation overview cards](/insights/evaluation/reading#the-overview-dashboard) currently mix sampled coverage/profile values with wider volume metrics. Do not combine them as though they describe one complete cohort. For a controlled comparison, retain a versioned dataset and reconcile evaluated, failed and excluded cases. ## 2. Separate consumption, allocation and the amount billed \{#keep-four-kinds-of-cost-separate} | Value | What it tells you | How to use it | | ----------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | Provider spend | Usage or cost reported by a model or another upstream provider | Check its coverage, currency and reporting basis | | Allocated infrastructure cost | A modeled share of compute, storage, idle capacity or shared services | Compare methods and source windows; retain unallocated amounts | | Customer price or charge | The amount determined by the applicable commercial terms and metering | Refer to the billing record and the pricing basis effective when usage occurred | | Invoice amount | The billed financial statement, including applicable adjustments | Reconcile through billing; a dashboard estimate does not settle an invoice | A price multiplied by usage is not automatically a measurement of provider cost. Likewise, request counts or tokens can be allocation weights without proving how many CPU cycles one customer consumed. Forecasts and allocations should name their method and uncertainty. Historical source corrections may revise an estimate. They must not silently move old usage to a new payer or reprice it with today's rates. Retain the original currency, payer and commercial basis when investigating a discrepancy. Reporting also does not authorize additional spend: a stale or empty dashboard is not an available-balance check. ## 3. Look for longer prompts, repeated work or changed tool use \{#understand-tokens-and-tools} Prefer provider-reported counters when available, keeping their field definitions and missing values intact. Input, output, cached, reasoning, audio and image fields can use different accounting bases. Do not assume they always form a disjoint sum or derive text usage by subtracting unrelated counters. Tool evidence also needs a clear stage: * **Offered:** the model request included that tool definition. * **Requested:** the model asked to call it. * **Executed:** the platform actually attempted the authorized operation. * **Succeeded:** that execution reported success. A requested call rejected by policy was not executed. “Never requested” is useful only across observations where that exact tool/version was offered. A rare tool is not automatically unnecessary. Run usage is not necessarily conversation-lifetime usage. Compaction changes the active prompt; it does not erase previously incurred consumption. A branch or revert can remove visible messages without refunding prior calls. An unknown context-window size should remain unavailable, not appear as 0% used. See [context management](/managed-agents/conversations/context-management). ## 4. Follow a representative request to its outcome \{#investigate-a-request} Keep the server request ID, approximate time, authorized project/environment, endpoint and observed outcome. Distinguish a network attempt from a retried business operation, and use available run/turn/trace links to follow what happened. An HTTP response or client disconnect does not, by itself, describe every later tool or generation outcome. [Generation outcomes](/managed-agents/conversations/generation) and [trace inspection](/insights/evaluation/reading) cover the existing documented surfaces. Share safe request identifiers with support; never include API keys, authorization headers or signed download URLs in a diagnostic report. ## Upcoming: consolidated usage views \{#consolidated-insights} **Status:** Upcoming — not yet available. Investigate a cost or quality change in one view. Select the project, audience and time window, compare usage and performance, then open the related run or integration evidence. Each chart identifies what it counts, its source and unit, when it was refreshed and any gaps. Filtering and export preserve those choices. Infrastructure-cost allocations will remain labeled models with their methods and uncertainty, separately from provider spend, customer prices and invoices. Correcting a report must not silently reprice prior usage or change its payer. The current generation and evaluation reads above remain the available sources. A dashboard query API is not yet available. **Example:** Select a project, customer audience and a fixed seven-day window; compare provider spend and model usage, open a related run, then export the same filtered rows. The view labels estimates and incomplete periods. ## Upcoming: prompt contribution estimates \{#prompt-attribution} **Status:** Upcoming — not yet available. Find which parts of a prompt contribute to its size: conversation history, memory, tool definitions and prompt fragments. The attribution view distinguishes measured contributions from tokenizer estimates and estimates scaled to a known input total. A scaled breakdown can add up correctly while its per-source allocation remains modeled; it cannot establish a separate billable charge for a memory, tool definition or prompt fragment. The view also separates tools offered to the model from tools requested, attempted and completed. Missing observations and an unknown context-window size will remain unavailable rather than becoming zero usage or 0% used. Compaction and history edits will not erase already incurred consumption. **Example:** Inspect one generation’s prompt breakdown across history, memory, tool definitions and prompt fragments. Each contribution says whether it is measured, estimated or scaled; an unknown contribution stays unknown. ## Upcoming: request capture and retention controls \{#request-capture-and-retention} **Status:** Upcoming — not yet available. For recurring support investigations, choose which project/environment may retain request bodies and for how long. Review the effective capture policy, use a safe request ID to find a failing attempt, and inspect only its permitted content. After changing capture or retention, review the effect on new requests and any cleanup still pending for older copies. Use request logs to investigate what an application sent and why a response failed. When content is missing, the log explains whether capture was unavailable, disabled, excluded, redacted, truncated, dropped or still pending. Eligible request payloads are captured by default. Turn capture off for a project and environment when you do not want that content retained. Mandatory exclusions apply even when capture is enabled. Screenshots, computer-use recordings and retained voice recordings require separate choices. If policy checks or redaction fail, only permitted metadata and a safe failure reason remain. Redaction cannot guarantee that arbitrary free text contains no sensitive information. Before changing retention, review its effective date, applicable price changes and effect on existing copies. Immediate access withdrawal and completed physical deletion are separate states; backups and external copies have their own consequences. These controls are not currently available through a public request-log or retention endpoint in this guide. **Example:** Disable eligible payload capture for one project/environment while retaining permitted request metadata. Before shortening retention, review the effective date, price impact and cleanup consequences; the result distinguishes access removal from pending physical cleanup. ## Upcoming: customer-managed telemetry export \{#telemetry-export} **Status:** Upcoming — not yet available. To use your organization’s monitoring system, select a supported destination and the metadata records it needs, authorize that destination, then follow an initial delivery. Inspect rejected or retrying records before expanding the feed. When pausing an export, review its buffer and missing intervals so resume does not appear to recover history that expired. Send telemetry to your own monitoring or storage system, starting with metadata-only records. Including payload content requires explicit permission for both the source and destination; permission to capture locally is not permission to export. Self-hosted options support OTLP, a standard telemetry protocol, and object-storage destinations. Each destination documents the records it accepts and how fields are mapped. Delivery status will distinguish accepted, delivered, rejected, retrying and irrecoverably missing records. Pause and resume must explain whether accepted records remain buffered and which intervals were skipped. A finite buffer can expire, so resume is not a promise to recover all history. Copies already delivered remain subject to the destination's policy. A public export-management endpoint is not yet available. **Example:** Choose an OTLP or object-storage destination and start with metadata only. Including payloads requires a separate explicit choice. After pausing and resuming, the view lists buffered deliveries and any unrecoverable interval. ## Next steps \{#next-steps} * [Read traces and scores](/insights/evaluation/reading) for supported quality and usage evidence. * [Build comparable dataset runs](/insights/evaluation/datasets-and-runs) with explicit failure accounting and a reproducibility manifest. --- URL: https://docs.travila.ai/insights/alerts # Understand alerts and delivery \{#overview} **Status:** Upcoming — not yet available. Catch rising failures or missing activity before they go unnoticed. Define the condition that needs attention, send it to the people who can act, and follow the incident through recovery. Alerts report what is happening; spending limits and safety controls enforce their own rules. Configurable Insights alert rules, incident history and acknowledge/mute controls are not yet available. Existing [notifications](/core-platform/notifications) provide sending, inbox and preference operations; a notification destination alone does not create an alert rule. ## 1. Configure an actionable error-rate alert \{#alert-conditions} **Status:** Upcoming — not yet available. Build an alert for a sustained rise in request errors, with a notice to the people who can fix it. Before starting, have a supported error signal, an authorized project/audience, a destination you control and an agreed action for the recipient. 1. Choose the signal and population, then select a threshold and observation window suitable for that workload. 2. Save the rule inactive and inspect its scope, missing-data handling and destination. 3. Enable it after those choices are reviewed. 4. Follow the resulting incident and its delivery attempt separately. 5. During an outage, acknowledge or mute optional notices without hiding the incident; close the investigation only after its recovery evidence is current. A useful alert identifies the condition, the affected audience and the next action. It does not grant additional spending or prevent work by itself. Choose a condition your team can act on, such as a rise in errors or a missing heartbeat. The rule catalog identifies the event sources and conditions supported by your deployment, including event-count thresholds, error rates and missing-heartbeat checks. Statistical conditions require enough baseline data before they can be evaluated. Before enabling a supported rule, review these choices: | Choice | What to specify | | ------------ | ------------------------------------------------------------------------------------------------- | | Scope | Project, test or live environment, and exact customer audience; unassigned is a specific audience | | Condition | Supported event/metric, unit, threshold and observation window | | Data quality | How recent and complete observations must be before a result is trustworthy | | Confirmation | How long a breach or recovery must persist before changing incident state | | Destination | Authorized recipients and channel, with an owner who can fix delivery failures | | Reminders | When another notice is useful while the same incident remains active | For this example, scope the rule to one project’s live, unassigned customer audience and send an email to the operations inbox after the selected request-error threshold holds over a complete five-minute window. The threshold and window are policy choices for this recipe, not defaults, a latency guarantee or a claim that this signal is available today. Suggested rules start inactive. After explicitly creating your first project, inspect its scope and destinations before enabling suggestions. A cross-project rule requires an explicit authorized project set. A project rule does not override a broader rule: independently configured matching rules can both notify their permitted audiences. ## 2. Follow the condition through recovery \{#incident-lifecycle} **Status:** Upcoming — not yet available. Incident history separates the condition being observed from notification delivery. One incident can have an initial notice and several reminders. | State or event | Meaning | | ---------------- | ------------------------------------------------------------------------------ | | New incident | A supported condition met its breach confirmation rule | | Reminder | The same incident remains active and its reminder period elapsed | | Recovery | Fresh, sufficiently complete observations met the recovery condition | | Unknown or stale | The source or evaluation cannot establish the current condition | | Cancelled | The rule was disabled/deleted or authority ended; this does not prove recovery | Missing data must not appear as a healthy zero. For a heartbeat rule, distinguish “the monitored activity stopped” from “the observation pipeline stopped.” Check source freshness before interpreting silence. Total notification delay includes source delay, evaluation, confirmation and delivery; it is not an instantaneous enforcement guarantee. A later breach after recovery creates a new incident. Keep its first occurrence and recovery separate from earlier incidents when measuring duration or frequency. **Example:** After an error-rate breach, a missing observation window shows **Unknown**, not **Recovered**. Fresh observations that meet the recovery condition close that incident; a later breach opens a new one. ## 3. Recover a notice that did not arrive \{#alert-delivery} **Status:** Upcoming — not yet available. Detection, queued delivery, provider acceptance and recipient visibility are different outcomes. When a notice is missing, check the destination, recipient permissions, delivery failure and any declared suppression before concluding that the condition never fired. A test or dry run must say whether it sends a real message or contacts a paid provider. Send notices through SMTP or webhook destinations in a self-hosted deployment, or choose an optional hosted destination. Delivery history shows pending notices and missing intervals after an interruption, so you can distinguish an undelivered notice from a condition that never fired. **Example:** An incident can show **Detected**, an email attempt **Failed**, and another destination **Delivered**. Retrying delivery remains attached to the same incident. ## Variant: reduce reminders while the team investigates \{#acknowledge-and-mute} **Status:** Upcoming — not yet available. Acknowledge an incident to record that it has your attention, or mute optional notices for a limited time. Neither action changes the observed facts. A personal mute applies to your delivery only; shared suppression requires authority over the entire rule audience. Required notice classes remain identified and follow their own delivery policy. Before applying suppression, check the incident, audience and expiry. Muting leaves evaluation running and the incident visible to other authorized operators. Existing [notification preferences](/core-platform/notifications/preferences) are separate controls; do not assume they implement these future alert semantics. **Example:** Mute optional notices for yourself until a chosen time while a colleague continues to receive them and both can see the incident. Shared suppression requires permission for the whole audience. ## Next steps \{#related-workflows} **Status:** Upcoming — not yet available. * Use [notification sending](/core-platform/notifications/sending) and the [inbox](/core-platform/notifications/inbox) for their documented, deployment-supported tasks. * Read [usage and cost](/insights/usage-cost) before choosing a threshold based on sampled, estimated or delayed reporting. * Use [evaluation](/insights/evaluation) to investigate permitted quality evidence behind an incident. --- URL: https://docs.travila.ai/workflows # Workflows \{#overview} **Status:** Upcoming — not yet available. Start with one business result that agents and people can complete together. The recommended first recipe is an approved customer document: draft it, validate the exact revision, obtain human approval and confirm the save in the owning system. 1. Name the final record that proves success and the inputs/actions permitted for producing it. 2. Follow [draft, approve and save](/workflows/agent-coordination) for the bounded procedure. 3. If the work grows into changing evidence, recurring activities and several human tasks, use [the customer-case recipe](/workflows/process-management). 4. Keep the original operation references through interruption; a partial draft, pending review and confirmed save are different results. **Finished result:** a confirmed business outcome, or visible unfinished work with a recovery path. Workflow interfaces are upcoming; the linked recipes describe the completed-product experience. | Use case | Recipe | | ---------------------------------------------------------------------------- | -------------------------------------------------------------- | | Produce one reviewed document and confirm it was saved | [Agent coordination](/workflows/agent-coordination) | | Gather changing evidence and route eligible human work before closing a case | [Processes and case management](/workflows/process-management) | Browse the [platform overview](/overview) for related capabilities. --- URL: https://docs.travila.ai/workflows/agent-coordination # Document coordination preview \{#overview} **Status:** Upcoming — not yet available. For current interactions, use [tool use and approvals](/managed-agents/delegation-approvals/using-tools). The complete document-coordination journey and customer API described here are not available. The planned flow connects drafting, validation, an authorized person’s review and a confirmed save in the system that owns the document. A draft or approval alone is not the final business result. ## Scope and completion \{#business-completion} **Status:** Upcoming — not yet available. The planned task records the authorized organization, project, environment, customer, source revisions and permitted actions. A finite budget bounds parent and child work. Completion means the owning system confirms the approved document revision; changed inputs can require validation and review again. ## Draft, validate, review and save \{#coordination-flow} **Status:** Upcoming — not yet available. The proposed sequence validates a candidate, presents that exact revision to an eligible reviewer, and saves only after the required decision. Missing validation or review leaves work incomplete. Coordination references owning records instead of duplicating private application data. Planned reminders require permitted consent, time zone, quiet hours and frequency. A reminder does not imply continuous human monitoring or a completed review. ## Partial and uncertain outcomes \{#progress-and-results} **Status:** Upcoming — not yet available. Progress would distinguish a candidate, approval wait, confirmed save, failure and unknown external outcome. Useful partial results stay visible when a child task or budget ends. A late result cannot replace a newer accepted revision. ## Recovery boundaries \{#coordination-recovery} **Status:** Upcoming — not yet available. The planned recovery path reconciles the original operation and its input/output revisions before repeating a save. Revoked access or deletion must not be undone by delayed callbacks or restored state; already-dispatched effects need separate accounting. See [process recovery](/workflows/process-management#process-recovery) for the related preview and [tool approvals](/managed-agents/delegation-approvals/using-tools) for the current interaction path. --- URL: https://docs.travila.ai/workflows/process-management # Processes and cases preview \{#overview} **Status:** Upcoming — not yet available. Process, case, task-inbox and comparison interfaces are not yet available. Use [current tool approvals](/managed-agents/delegation-approvals/using-tools) for supported human decisions. This preview describes future coordination of evidence and an authorized decision, not current start commands. ## Processes and cases \{#process-or-case} **Status:** Upcoming — not yet available. A planned process has a reviewed sequence of tasks, decisions and waits. A case organizes changing evidence around a subject, with fixed processes for individual sequences. Source documents remain in their owning systems; coordination does not become another private-data store or billing authority. ## Definition and scope \{#model-preparation} **Status:** Upcoming — not yet available. The proposed model records customer scope, immutable task and decision versions, required evidence, assignees, deadlines, budgets and failure paths. Parallel joins must expose missing branches rather than presenting incomplete evidence as a complete packet. Recurring starts have one scheduling owner; retries retain the original deadline. ## Authorized decisions \{#human-task-review} **Status:** Upcoming — not yet available. A planned human task binds its occurrence, assignment, deadline and exact proposal/form revision. A changed claim or evidence requires refresh before a decision; approval cannot expand the reviewer’s access or the task’s limits. The final owning record and confirmed outcome establish completion. ## Incomplete and external outcomes \{#run-outcomes} **Status:** Upcoming — not yet available. The proposed view distinguishes completion, failure, cancellation, deadline expiry and uncertain external effects. Preserve versions, evidence and original operation references so an action that may have completed is reconciled before retry. Partial lists are not proof that no other scoped records exist; lifecycle actions affect new and already-dispatched work differently. ## Comparing a revised process \{#comparison-and-promotion} **Status:** Upcoming — not yet available. Planned comparisons use the same immutable cases and labels for baseline and candidate. Keep human labels separate from automated judgments, and retain incomplete samples, coverage, quality, safety, latency and cost. Promotion requires an authorized decision; an inconclusive result or confident grader does not approve a change. ## Upgrade and restore \{#process-recovery} **Status:** Upcoming — not yet available. The planned recovery path accounts for active versions, pending approvals, deadlines, delayed events and unresolved external operations. A new definition must not silently reinterpret a running case. Current access and deletion restrictions must apply after restoration. Use the operating channel for unresolved outcomes. See [deployment operations](/enterprise/deployment-operations) and [agent coordination](/workflows/agent-coordination) for related guidance and previews. --- URL: https://docs.travila.ai/platforms # Travila for Platforms \{#overview} **Status:** Upcoming — not yet available. Build an application for many customers with separate data and usage for each one. Add customer accounts within your Travila project, or connect to a business that owns its own workspace and authorizes your platform to work there. Use [customer management](/platforms/customer-management) to add or remove customers, request access to a client's workspace, monitor permitted usage and status summaries, and recover an interrupted signup. Clients keep control of their workspace access; your platform console does not expose their individual conversations. These customer-management interfaces are upcoming. Collecting payments from your customers is not included; you can use your own billing system. Browse the [platform overview](/overview) for related workflows. --- URL: https://docs.travila.ai/platforms/customer-management # Customer management preview \{#overview} **Status:** Upcoming — not yet available. The customer-management API and platform console are not available. Start with the [workspace and project guidance](/core-platform/workspaces-projects) and confirm your operator’s supported arrangement. This preview distinguishes hosting companies as customers from delegated work in a workspace they own. Your billing system remains responsible for collecting payments from your customers. ## Hosted and client-owned relationships \{#customer-relationships} **Status:** Upcoming — not yet available. The proposed hosted relationship gives each company a customer identity within a project, without creating a separate workspace or subscription. A client-owned workspace remains independent and requires separately authorized delegated access. Paying for it would not itself grant access to its content. ## Customer and environment isolation \{#customer-isolation} **Status:** Upcoming — not yet available. The planned scope binds each authenticated company to its own customer identity and separates test/live data. An omitted customer, where permitted, would select unassigned records rather than every customer. Combined views need separate authorization; validate isolation before enabling a deployment. ## Delegated access \{#delegated-workspace-grants} **Status:** Upcoming — not yet available. The proposed workspace administrator chooses permitted projects, environments, customers, actions and expiry. A grant cannot enlarge the integration’s own key permissions. Revocation must stop new grant-dependent work while separately tracking actions already sent to external services; an invitation is not permanent authority. ## Operations summaries \{#managed-console-boundary} **Status:** Upcoming — not yet available. The planned platform console exposes permitted usage and health summaries, not private employee conversations or transcripts through drill-down, exports or embedded sessions. Access to a client’s own console still requires that client’s membership and permissions. ## Usage and payment attribution \{#usage-and-payment-attribution} **Status:** Upcoming — not yet available. The proposed workflow attributes usage under the agreement effective when it occurred, including late-arriving usage. Customer identities and test/live modes have no separate entity fee in this design; metered usage and accepted terms remain distinct. Your billing system collects customer payments. See [commercial agreements and invoicing](/enterprise/commercial-agreements) for your agreement with Travila. ## Relationship recovery and offboarding \{#relationship-recovery} **Status:** Upcoming — not yet available. The planned recovery path reconciles the original creation request before creating another customer. Offboarding one company would block its new work and account for cleanup, retained records and uncertain external effects while other customers continue. Delayed updates must not reactivate it; deletion does not close a shared payment account. Retain the usage and payment references required for outstanding charges; see [billing and spend](/core-platform/billing-spend). --- URL: https://docs.travila.ai/enterprise # Travila for Enterprise \{#overview} **Status:** Upcoming — not yet available. Choose commercial terms for your organization and plan how the application will operate. The upcoming deployment choices include customer-operated self-hosting, Travila-managed dedicated single tenancy, customer-selected cloud providers (AWS or Google Cloud) and supported regions, and VPC peering for private applications. Each has its own qualified configuration, operating responsibilities and readiness checks. | The organization needs to… | Complete recipe | | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Move an existing application onto negotiated commercial terms | [Compare the offer, activate it and reconcile the first invoice](/enterprise/commercial-agreements) | | Operate the application on infrastructure it controls | [Choose self-hosting and assign operating responsibilities](/enterprise/deployment-operations#deployment-scope) | | Reserve application compute and customer-data stores for one organization | [Review a Travila-managed dedicated single-tenant deployment](/enterprise/deployment-operations#dedicated-deployment) | | Use the cloud platform approved by your organization | [Choose AWS or Google Cloud and a qualified deployment](/enterprise/deployment-operations#hosting-cloud) | | Choose where application data is processed, backed up and recovered | [Select supported hosting regions and review data residency](/enterprise/deployment-operations#hosting-region) | | Connect applications and services on a private network | [Prepare, verify and operate VPC peering](/enterprise/deployment-operations#private-connectivity) | | Approve a deployment and prepare the operating team | [Gather applicable evidence and establish support](/enterprise/assurance-support) | Begin with the application and operating requirements, use those to choose the offer, and retain the approved terms and evidence. The handover is complete when the agreed services are ready and the team knows how to operate them and recover a failure. Self-hosting is a product capability independent of Enterprise commercial entitlement. A commercial upgrade does not move existing workloads into a dedicated deployment, change their cloud provider or region, or connect a private network; those changes follow the separate deployment and acceptance plan. **Available today:** Use the terms and contacts supplied for your account. Self-service Enterprise buying, deployment and assurance interfaces are not yet available. Browse the [platform overview](/overview) for documented capabilities. --- URL: https://docs.travila.ai/enterprise/commercial-agreements # Commercial agreements and invoicing \{#overview} **Status:** Upcoming — not yet available. An organization already runs an application and now needs negotiated rates, purchasing approval and invoices its finance team can reconcile. Follow the buying recipe below: agree the offer, retain the approved revision, activate the covered services in the existing workspace, then verify the first invoice. Have an authorized buyer and payer, the workspace and projects covered, expected usage, deployment/support needs and any procurement requirements. A new customer also completes first-project onboarding; an existing customer keeps its projects unless it chooses a separate migration. **Availability:** Quote, onboarding, plan-change and invoice interfaces are planned. For an agreement or billing question now, use the approved terms and contacts supplied by your contracting parties. This page sets no price, payment deadline or service commitment. ## 1. Compare a complete offer for the application \{#configure-and-review-quote} **Status:** Upcoming — not yet available. Work with the Travila commercial team to assemble an offer for your intended workload: capabilities, quantities, usage assumptions, commitments, add-ons, deployment and support. Resolve unavailable options or incompatible combinations before purchasing approval. Compare the complete recurring and usage-based cost; a lower fixed fee is not necessarily a lower total bill. Record the selected [cloud provider](/enterprise/deployment-operations#hosting-cloud), [operating arrangement](/enterprise/deployment-operations#deployment-scope), any [dedicated deployment](/enterprise/deployment-operations#dedicated-deployment), [primary, backup and recovery regions](/enterprise/deployment-operations#hosting-region), and [private connections](/enterprise/deployment-operations#private-connectivity). The offer identifies the agreed charges for these choices, including any setup, reserved capacity, cloud- and region-specific infrastructure or transfer, connection operation and support charges. Review what is included, how additional usage is measured and which prerequisites must be ready; no deployment choice becomes available merely by appearing on a quote. Compare the recurring, usage-based and one-time charges, currency, applicable discounts, expected tax treatment and the assumptions behind any estimate. Check the offer's validity and required approvals. An estimate based on expected usage is not a promise that your final invoice will equal that amount. Keep the exact revision you accept. A revised scope or price needs the applicable approval again; an expired or withdrawn offer cannot be newly accepted. Accepting the quote and activating the agreed services are separate steps. ## 2. Approve the exact terms and payer \{#agreement-review} **Status:** Upcoming — not yet available. Before accepting an agreement, review the scope and the people authorized to approve it: 1. Identify the contracting organizations, the offering and accounts or projects covered, and the people authorized to approve on each party's behalf. 2. Identify the legal payer and confirm that its authorized representative approves the covered billing scope and obligations. A billing contact or invoice recipient may have a different role. 3. Review the proposed currency, charging units, custom rate revision, commitments, allowances and overage rules. Record any agreed allowance expiry, carryover or renewal treatment explicitly. 4. Confirm the agreement's effective dates, renewal or termination terms, billing cadence and negotiated payment terms. Check which revision will apply when usage crosses a change date. 5. Provide the applicable billing name, contact and addresses, required invoice identifiers and a purchase-order reference where agreed. Have the contracting parties confirm applicable invoicing and tax requirements. 6. Retain the exact approved agreement and its references. A revised price or expanded payer obligation needs the applicable approval before it becomes effective. Keep the approved revision with its scope, dates, prices and payer consent. Missing approval or an incomplete charging rule leaves the proposal unresolved. Historical price examples and informal account settings do not establish the agreed terms. ## 3. Bring the agreed services into use \{#enterprise-onboarding} **Status:** Upcoming — not yet available. Follow one onboarding plan with your sponsor and Travila contact. It covers the workspace, security and procurement reviews, billing, deployment prerequisites and handover. Each milestone shows its progress; a blocked step names the person responsible and the next action. For a new organization, creating the first project is part of onboarding. Obtaining its credentials is a separate explicit step. For an existing workspace, onboarding reuses the projects and integrations you already operate unless you expressly choose a separate migration. Your onboarding plan shows readiness separately for the deployment, sign-in policy, support arrangement and any regulated-data use. Signing the quote does not complete those steps. See [first-project onboarding](/core-platform/workspaces-projects) and [assurance and support](/enterprise/assurance-support). For the selected deployment, carry the approved cloud provider, deployment configuration, dedicated scope, data locations and private connection requirements into the setup plan. Assign customer and Travila owners for provisioning, access, network approvals, a representative application check and recovery checks. Handover records the supported configuration, operating responsibilities and any blockers before the affected services can become ready. Keep any move from an existing deployment, cloud provider or region in a separate approved migration plan. ## Existing customer: apply the agreement to the current workspace \{#standard-to-enterprise} **Status:** Upcoming — not yet available. Apply accepted Enterprise terms to your existing eligible workspace without recreating its projects. Review the payer, covered scope, effective date, billing treatment and readiness work before approving the transition. The conversion preserves project and resource identities, authorized credentials and integrations, usage records and invoice history. It does not merge organizations, move data to another cloud provider or region, reset a signup allowance or grant a person more access. A separate migration or identity change requires its own approved plan. Until all required steps are confirmed, the transition shows what is pending or blocked and which terms are active. A successful billing update alone does not establish that every contracted capability is ready. ## 4. Reconcile the first invoice against the agreement \{#invoice-review} **Status:** Upcoming — not yet available. Use the approved agreement revision and billing period from the buying steps above. Match each line to its project or agreed scope, quantity, unit and rate, then account for allowances, credits and adjustments. Keep any unexplained difference tied to the original invoice for the dispute workflow. The invoice should identify the following information: | Information | What it explains | | ------------------------------------------------------------ | ------------------------------------------------------------------ | | Issuer, billed organization and invoice identifier | Which parties and document the invoice concerns | | Agreement and rate revision | Which accepted commercial terms produced the charges | | Billing period and attributable scope | Which project or agreed billing scope incurred the charge and when | | Quantities, units and prices | How usage or commitments contribute to each line | | Allowances, overage and credits | How the applicable agreed rules change the amount due | | Currency, issue date, due date and PO reference where agreed | How to match the invoice to approved purchasing and payment terms | | Payments, adjustments and remaining balance | What has been reconciled and what remains outstanding | A later price, billing address or renewal does not rewrite an issued invoice. Corrections identify the original invoice and preserve its history. ## 5. Follow payment and any remaining balance \{#invoice-and-payment-status} **Status:** Upcoming — not yet available. An invoice can be issued while delivery is pending or failed. **Sent** records delivery status; it does not mean the invoice is paid. **Due** and **overdue** depend on the agreed payment terms and remaining balance. **Paid** requires reconciled payment or applicable credit allocation. A **partial payment** leaves a visible remainder. An uncertain payment stays pending or unknown until reconciled. **Voided** preserves the original document and its history under the applicable correction rules. If money was already allocated, its disposition needs a separate explanation. A credit note or adjustment can change the amount due; it does not by itself confirm a cash refund. ## Recover a disputed charge or uncertain payment \{#billing-disputes} **Status:** Upcoming — not yet available. Keep the invoice identifier, affected line references, agreement/rate revision and relevant payment references. Use the billing dispute channel agreed with the contracting parties and request a tracked outcome. Avoid sending payment secrets or complete card details. The dispute record identifies what is under review and any resulting approved correction. Raising a dispute does not itself establish a changed due date, waived charge or refund. If a payment outcome is uncertain, have it reconciled before initiating a replacement payment. Preserve both the original invoice and any linked credit note or adjustment. See [billing and spend](/core-platform/billing-spend) for allowances, spending controls, usage records and payment uncertainty. See [assurance and support](/enterprise/assurance-support) for evaluating service commitments, and [Travila for Enterprise](/enterprise) for the documentation map. ## Variant: expand, reduce or renew the agreement \{#change-enterprise-plan} **Status:** Upcoming — not yet available. Start an expansion, reduced commitment or renewal by reviewing the proposed replacement terms. Compare what changes, which services are ready, who pays and when the new terms take effect. The agreed date may depend on the contract and required preparation; this guide sets no immediate-upgrade default. Changing the cloud provider, dedicated capacity, the operating arrangement, a hosting region or private connectivity also needs the applicable deployment change and readiness checks. Review any setup, ongoing, transfer or retirement charges in the revised offer. A commercial tier change alone does not move data, hand over operations or remove a private connection. Before accepting, inspect the treatment of the remaining billing period, incurred and late-reported usage, commitments, unused allowances, paid or promotional credits, possible prorations and outstanding invoices. A lower fixed fee can still have higher usage charges, so compare the complete offer. The transition status distinguishes a proposed or scheduled change from one already applied. If confirmation is lost, recover the original transition before submitting another. After an effect has occurred, an authorized correction preserves the earlier terms and financial history. ## Variant: return to a smaller or standard plan \{#downgrade-or-exit} **Status:** Upcoming — not yet available. Begin before the requested change date. Choose a narrower Enterprise package or an eligible standard plan, then review notice terms, remaining obligations and the exact capabilities, limits and support arrangements that would change. Downgrading is separate from deleting the workspace. Before the change takes effect, Travila identifies features and resources that the target plan cannot support, including Enterprise sign-in, user provisioning, retention, regional controls and active integrations. Review the affected items and complete the stated prerequisites, including a working sign-in and recovery route for an authorized administrator. Required protections, held records and customer data stay protected while you resolve the transition. The transition explains blockers, permitted remedies, any restriction on new work and the approved read/export arrangements. If the target cannot support required security or processing commitments, the affected change needs an approved alternative or migration. This guide promises no automatic grace period, refund, debt waiver or release from a processing agreement. Withdraw or reschedule a pending change when the agreement and current state permit it. An already applied change needs a separately authorized correction; it cannot erase issued invoices or reverse a payment by changing a plan label. --- URL: https://docs.travila.ai/enterprise/assurance-support # Assurance and support \{#overview} **Status:** Upcoming — not yet available. Prepare the evidence package your organization needs to approve a specific agent application, then establish the support route the operating team will use. The result connects the application’s approval decision to supporting evidence and keeps unresolved items visible to the operating team. Bring the planned deployment, data categories, integrations and applicable organizational requirements. Include the security reviewer, procurement owner and operating contact who will use the resulting commitments. **Availability:** Use the actual reports, agreements, status address and support channels supplied for your organization. The assurance portal, status subscriptions and support journeys below are planned. No independent assessment, staffed coverage or response-time commitment is announced here. ## 1. Request evidence for the application you will operate \{#evidence-review} **Status:** Upcoming — not yet available. Describe the offering, deployment, user population, data categories, processing locations and external integrations you intend to use. Request evidence for that scope and compare it with your approval requirements. Keep its date and scope with the decision; leave missing or differently scoped evidence unresolved with a named follow-up. Travila provides the evidence relevant to your requested scope, identifying its date, applicable release and configuration, responsible contact and known exceptions. The review makes clear which claims have been independently assessed and which remain unresolved. | Review area | Evidence to evaluate | | ------------------------ | ------------------------------------------------------------------------------------------------------------------ | | Identity and access | Supported login and account lifecycle, authorized roles, delegation and access-review results | | Audit and administration | Covered actions, record completeness, permitted viewer/export scope and unresolved gaps | | Data handling | Actual processing chain, retention, export, deletion, regional handling and applicable approved terms | | Security | Relevant control tests, vulnerability handling and remediation status for the offered deployment | | Reliability | Measured workload and observation scope, disruption assumptions, recovery exercises and known limits | | Billing | Attributable usage, accepted rates and terms, invoice reconciliation and correction procedures | | Support | Agreed contact channels, coverage, severity/escalation process and the evidence supporting any response commitment | An independent report should identify its actual scope, period, exceptions and sharing restrictions. Use the authorized access process and retain those restrictions when sharing internally. An expired or differently scoped report needs clarification before it can support your review. You receive a review record that connects your requirements to supporting evidence, with a responsible contact and next action for each unresolved exception. ## 2. Resolve the requirements that affect approval \{#compliance-requirements} **Status:** Upcoming — not yet available. Prepare the requirements your intended use must meet, together with the relevant service, deployment, data categories and responsibilities. Our design targets include SOC 2 Type II, HIPAA, ISO/IEC 27001 and GDPR. Naming a target records a requirement; it does not establish that Travila has completed an assessment or enabled regulated-data processing. | Requirement | What to clarify in your review | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | SOC 2 Type II | The service and controls covered, report period, findings and applicable customer responsibilities. See [AICPA's SOC resources](https://www.aicpa-cima.com/resources/landing/system-and-organization-controls-soc-suite-of-services). | | HIPAA | The parties' roles, intended health-data processing, required agreements and eligible scope. A selected requirement is not a signed business associate agreement or permission to submit PHI. See [HHS cloud guidance](https://www.hhs.gov/hipaa/for-professionals/special-topics/health-information-technology/cloud-computing/index.html). | | ISO/IEC 27001 | The information-security management scope and the edition and assessment evidence relevant to your use. See [ISO's overview](https://www.iso.org/standard/27001). | | GDPR | The personal-data uses, controller/processor responsibilities, relevant rights, retention and processing locations. See [EDPB's role guidance](https://www.edpb.europa.eu/sme/learn-the-basics/data-controller-or-data-processor_en). | Your review shows the applicable obligations, supporting evidence and the person responsible for each unresolved question. Changed scope or expired evidence needs a new review. Use the actual report or agreement supplied for the offering; no assessment completion date is announced here. ## 3. Confirm the processing commitments in the agreement \{#processing-commitments} **Status:** Upcoming — not yet available. Before approving the intended use, verify the exact documents, versions, parties and authorized signers that apply. Identify the appointed processing chain and distinguish customer-directed integrations from services supplied as part of the offering. Request clarification when the actual deployment or data flow differs from the reviewed scope. Keep these commitments separate when evaluating them: | Commitment | What needs its own confirmation | | -------------------------- | ------------------------------------------------------------------------------------ | | Training exclusion | Which data uses and processing paths the approved restriction covers | | Retention and deletion | Which stores and copies are covered, applicable exceptions and verified handling | | Regional processing | Actual processing and storage locations across the selected chain | | Sensitive or regulated use | Applicable eligibility, agreements and operating controls for the specific use | | Service commitment | Agreed measurement scope, period, exclusions, remedies and tested operating capacity | One confirmed setting does not establish all these commitments. A declaration, provider key or commercial agreement also does not grant platform permissions or authorize an otherwise unsupported use. Resolve an unknown processing path or unsupported use with the responsible parties before relying on it. See [commercial agreements and invoicing](/enterprise/commercial-agreements) for negotiated pricing, payer approval, payment terms and invoice disputes. This assurance review concerns whether the actual commitments are supported by controls and evidence. ## 4. Establish the operating team’s support route \{#support-arrangements} **Status:** Upcoming — not yet available. Before handover, record the authorized reporters, contact channels, coverage, severity definitions, escalation route and any agreed response commitments for your offering. Identify the information needed to verify the affected organization. This guide supplies no response-time or availability guarantee. For a support request, prepare the affected capability and deployment, impact, relevant time range, request or incident references and the steps already taken. Supply diagnostic data only through an approved channel; omit secrets and unrelated customer information. Security, privacy, abuse and billing issues may require different authorized handling. Keep the request's tracking reference and review its current state, assigned route and next action. A request acknowledgement is distinct from a resolved issue. If an outcome is uncertain—for example, a timed-out financial operation—retain its reference and request reconciliation before repeating the effect. ## During an incident: follow updates and recovery \{#status-and-subscriptions} **Status:** Upcoming — not yet available. Follow incidents on a status page that remains independent of the affected application. Subscribe by email, webhook or feed for updates. These subscriptions are not yet available; use the status address and support contact currently supplied for your account. Check the affected components and the observation time. The status page identifies cached information and marks missing or stalled observations as stale or unknown. An automated recovered component signal may coexist with an ongoing manual incident investigation. Component history does not by itself define contractual availability or service credits. Choose the events you want, verify your own address or endpoint, and keep the subscription’s update or unsubscribe route. A webhook destination requires authorized ownership and the documented verification process. Status notifications contain public incident information and exclude private customer diagnostics. During an outage, use the published independent fallback and agreed support route. If the status page or observations are unavailable, record that uncertainty; a reachable cached page is not proof of current platform health. See [deployment and operations](/enterprise/deployment-operations) for adoption and recovery reviews, [billing and spend](/core-platform/billing-spend) for usage and payment boundaries, and [Travila for Enterprise](/enterprise) for related guides. --- URL: https://docs.travila.ai/enterprise/deployment-operations # Deployment and operations \{#overview} **Status:** Upcoming — not yet available. Choose how your organization will run Travila: operate a complete self-hosted installation or use a Travila-managed dedicated single-tenant deployment. Choose AWS or Google Cloud (GCP), select a supported hosting region on that cloud and, when your application needs private systems, arrange an approved VPC peering connection. Complete the setup and recovery checks before moving real workloads. Have an operating owner, required application capabilities, permitted model and software licenses, your approved cloud provider, data locations and network requirements. Use these to select a supported release and deployment configuration with clear installation, maintenance and recovery responsibilities. **Availability:** Self-hosting, managed dedicated single tenancy, cloud-provider choice, customer-selected hosting regions and VPC peering are upcoming. AWS and Google Cloud are the initial cloud targets. This guide announces no currently available deployment profile, region list or recovery commitment. Confirm the qualified cloud, release, locations, connection options and operating terms before choosing a deployment. Self-hosted capability is not an Enterprise-only entitlement. A managed dedicated deployment has its own agreed scope, pricing and operating responsibilities. Commercial plan selection and deployment readiness are separate decisions. ## 1. Choose the operating arrangement for your application \{#deployment-scope} **Status:** Upcoming — not yet available. Start with the workloads, data and operating responsibilities that matter to your organization: | Operating choice | Who runs the application | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | Customer-operated self-hosting | Your team installs and operates the complete supported release on infrastructure it controls, including upgrades, monitoring and recovery | | Travila-managed dedicated single tenancy | Travila operates an agreed deployment reserved for your organization, with explicit customer responsibilities and support-access terms | Infrastructure ownership and operating ownership are separate. Record both; owning a cloud account does not by itself establish who operates Travila there. Choose from the supported configurations and resolve an unsupported arrangement before proceeding. | Decision | Record before selecting a deployment | | --------------------- | ------------------------------------------------------------------------------------------------------------- | | Application scope | Required capabilities, users, traffic patterns, model workloads and expected storage growth | | Hosting cloud | AWS or Google Cloud, the supported deployment configuration, account ownership and provider-specific costs | | Operating ownership | Who installs, upgrades, monitors, responds to incidents, manages credentials and performs recovery | | Data handling | Approved primary, backup and recovery locations, retention, exports, deletion and external integrations | | Private connectivity | Applications to connect, traffic direction, supported network layout and responsibility for both ends | | Dependencies | Required local components, optional hosted integrations and the effect of disabling each optional integration | | Capacity and recovery | The tested workload, disruption assumptions, recovery procedure and any agreed recovery objectives | | Release and support | Exact supported release/configuration, update responsibility, known limitations and agreed support channel | The complete self-hosted offering lets you sign up, create a project and credentials, run an agent, use memory and files, receive events, evaluate results and manage usage limits without a mandatory hosted control service. Local model and embedding backends support operation without a hosted model account, subject to the models’ use terms. Release documentation identifies the supported configuration and any limits. Payment networks, mobile push networks and customer-connected external systems still require their respective external services. When an integration is disabled, its status explains the unavailable action and the features that remain usable, such as in-app events or invoice records. ## 2. For managed hosting, reserve dedicated capacity \{#dedicated-deployment} **Status:** Upcoming — not yet available. Choose managed dedicated single tenancy when your organization needs application compute and customer-data stores reserved for its use. Identify the organization and projects covered, required capacity and features, then review the allocation with Travila before accepting the offer. The deployment record describes the dedicated scope for application execution, queues, caches, databases, files, secrets and backups. It also identifies any shared management, monitoring or support services, the information they receive and who may access it. Isolation between your organization's projects continues to apply within the dedicated deployment. Confirm the allocation, capacity checks and access checks during handover. The agreed boundary prevents another organization from accessing your deployment or consuming its reserved capacity. The offering describes which resources are reserved; it does not imply dedicated physical hardware. Keep maintenance, backup, incident response and support-access responsibilities with the deployment record. ## 3. For managed hosting, choose an approved cloud \{#hosting-cloud} **Status:** Upcoming — not yet available. Choose AWS or Google Cloud (GCP) for your managed dedicated deployment when your organization standardizes its infrastructure, operating expertise or purchasing commitments on that provider. Select the cloud first, then a supported region and deployment configuration on that cloud. 1. **Match your cloud requirements.** Record the approved provider, required capabilities and network connections. Review the supported regions, capacity, backup and recovery options for that provider. 2. **Agree on ownership and costs.** Keep the cloud provider, infrastructure owner and application operator explicit in your [quote](/enterprise/commercial-agreements#configure-and-review-quote). The quote identifies the agreed charges and who pays for infrastructure, transfers and operation. A cloud choice alone does not establish that Travila operates inside your own cloud account. 3. **Verify the selected deployment.** At handover, confirm that the deployment uses the agreed provider, region and configuration, that your application works, and that the approved private connection and recovery procedure pass their checks. **Finished result:** your application runs in the agreed cloud configuration, with its operating responsibilities, data paths and charges recorded. Unsupported combinations stay blocked; Travila does not silently provision on the other cloud. Any approved external model, integration or shared support path is disclosed separately. Moving to a different cloud requires a supported migration and your approval of its data transfers, active-work handling, networking, retained copies, recovery and costs. Selecting a cloud does not enable automatic failover to another provider. ## 4. Choose hosting, backup and recovery regions \{#hosting-region} **Status:** Upcoming — not yet available. Select a primary hosting region from the qualified choices on your selected cloud, then agree where backups and disaster recovery may run. Review the locations against your organization's requirements before creating or moving workloads. A requested region becomes an option only when the required capabilities and dependencies are supported there. Review where each part of the application stores or processes information: | Information or activity | What to confirm | | --------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Application records, files, memory and evaluation results | Primary processing and storage locations, temporary copies, exports and deletion handling | | Backups and disaster recovery | Approved copy locations, restore destinations and recovery restrictions | | Logs, traces and monitoring | Destinations, retained content and who can access it | | Models and integrations | Provider processing locations and permitted fallback destinations | | Support and diagnostics | Where support artifacts may be stored and from where authorized support may access them | An incompatible model, integration or monitoring destination blocks that configuration until an approved alternative is selected. Routing, fallback and recovery stay within the agreed restrictions; a failure does not silently move protected data elsewhere. Each project's primary region remains fixed. Moving an existing application to another region requires a separately approved migration to a new project, with a supported data transfer, active-work plan, validation, rollback and retained-copy handling. Changing a billing plan does not relocate the application. ## 5. Connect private applications through VPC peering \{#private-connectivity} **Status:** Upcoming — not yet available. Use an approved VPC peering connection when Travila needs to reach applications or services on your private network, or your network needs private access to the selected deployment. VPC peering connects the agreed virtual private cloud networks. Confirm that the deployment supports your cloud, network layout and required traffic direction before planning the connection. 1. **Define the connection.** List the applications, allowed destinations and ports, traffic direction and owners of both network ends. Identify the deployment and projects allowed to use it. 2. **Check prerequisites.** Have the network owners review network identifiers, non-overlapping IP address ranges (CIDRs), routing and return paths, firewall rules and private domain-name resolution (DNS). Confirm whether the supported layout meets your needs; do not assume the connection also reaches a third network through another peer. 3. **Prepare both ends.** Complete the required approvals, configure the agreed routes and DNS, and retain the connection reference with its owners. The onboarding record shows what is pending or blocked before activation. 4. **Verify the intended access.** Test name resolution and a permitted application request from each approved direction. Confirm that unauthorized callers and unrelated destinations remain blocked. Keep application authentication, access controls and encryption in place across the private connection. 5. **Operate and retire the connection.** Monitor its status and use an approved change plan for new destinations, network changes or removal. Recheck access after a change and confirm that removed routes and permissions no longer allow traffic. A failed or removed connection visibly stops affected work without silently switching protected traffic to a public route. If the supported configuration offers a private endpoint instead, review it as a separate connection option with its own prerequisites and limits. Keep private connectivity in the deployment handover and [commercial offer](/enterprise/commercial-agreements#configure-and-review-quote). ## 6. Prepare the deployment and complete handover \{#release-adoption} **Status:** Upcoming — not yet available. Carry the approved operating arrangement, dedicated scope, cloud provider, regions and private connections into one onboarding plan. Your team installs a self-hosted release; Travila provisions a managed dedicated deployment. Each side completes its assigned setup and acceptance steps before admitting customer workloads: 1. Review the release’s supported features, known limits, prerequisites and use terms. Travila supplies installation, configuration, secret-management and recovery instructions for that release. 2. Confirm the selected cloud and account ownership, agreed compute and data allocation, stores, locations and permitted network destinations. For self-hosting, configure the components your team operates. Connect only the optional external services your application needs. 3. Run a representative application journey, such as creating an account, sending an agent message and retrieving a stored file. Record the release and configuration used. 4. Follow the documented upgrade, rollback and restore procedures with your application data. Review any work that needs intervention after recovery. 5. Verify any private connections and approved data paths. Record the operating owner, support route, monitoring, access, backup and recovery responsibilities, and any unresolved limitations. The result is an accepted deployment with a known configuration, a working application journey and a recovery procedure the operating team can follow. The handover records which services are ready, which are blocked and who owns each remaining action. Signing a quote or changing a plan does not activate a deployment that has not passed its readiness checks. A later move between deployment types, operating owners, cloud providers or regions needs a separate supported change plan. Review data transfers, credentials, active work, private connections, retained backups, recovery and charging consequences before approval. Preserve existing protections and history through the move or exit, and confirm the destination before retiring the old deployment. ## 7. Practice recovery with the application’s data \{#recovery-and-data-boundaries} **Status:** Upcoming — not yet available. Use a controlled copy of the application’s data and the release’s restore procedure. Recover application state, credentials and file references together, then repeat the customer journey exercised during installation. Honor revoked access and applicable deletion restrictions. Before serving work, inspect missing data and unresolved external operations; retain the recovered point, time taken and remaining operator steps. Recovery and availability commitments need the tested workload, observation period and failure assumptions. This guide supplies no universal uptime, recovery-time or data-loss guarantee. Confirm any contractual commitments through the approved [commercial agreement](/enterprise/commercial-agreements). If your deployment consumes infrastructure or object-change events, use the supported source and recovery procedure. Travila reconciles duplicate, delayed and missing events with the current object: an old delete cannot remove its replacement, and an old completion cannot recreate deleted data. Repeated delivery of the same notification does not create another usage charge. ## 8. Upgrade while accounting for active work \{#active-work-and-upgrades} **Status:** Upcoming — not yet available. Before an upgrade, agree on the affected capabilities, admission or pause behavior, active-work handling, customer communication and recovery procedure. Follow the release’s update steps, confirm the application can accept work again and identify previously admitted work that still needs intervention. Use the compatible rollback procedure if the update cannot complete. A lost connection, timeout or stopped process may leave an external action's outcome uncertain. Preserve its request or operation reference and reconcile it before repeating an action that could create another effect. A rollback preserves the history and status of work accepted before the change. The operating view shows which capabilities and modes can accept work, which dependency needs attention and when the status was last observed. Missing monitoring data appears as a gap, so a running process does not conceal an unavailable application feature. ## Recover a failed or uncertain application operation \{#operational-incidents} **Status:** Upcoming — not yet available. Record the affected capability, deployment release/configuration, time range, visible errors and request or operation references. Use the approved support channel and share only the diagnostic information it authorizes. Keep credentials and customer content out of general incident reports. Distinguish failed work from pending or uncertain work, and identify whether the observation itself is stale. Follow the supported recovery procedure and reconcile outstanding external effects before resubmission. If independent incident information is available for your deployment, check its observation time and affected scope. See [assurance and support](/enterprise/assurance-support) for reviewing operating evidence and incident communication, [billing and spend](/core-platform/billing-spend) for usage and payment boundaries, and [Travila for Enterprise](/enterprise) for related guides. --- URL: https://docs.travila.ai/api # API Reference \{#api-reference} Use this reference when implementing a request or diagnosing a response. For a complete workflow, start with [building a chat assistant](/managed-agents/conversations/build-chat-assistant), [adding tools](/managed-agents/delegation-approvals/build-agent-with-tools) or [receiving events](/integrations/webhooks), then follow the operation links for exact fields and errors. ## Base URL \{#base-url} Example deployment base URL. * https\://api.travila.ai ## Request Format \{#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](/api/conversations/send-message#request) 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](/api/conversations/send-message#example-cookbook-core-platform-identity-access-scopes-permissions-01-request). 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 \{#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 \{#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](#postman-collection) and let it fill the field names in. ## Authentication \{#authentication} Every request must include one of: | Method | Header | Use Case | | --------------------- | --------------------------------------------------------------------------- | ------------------------------------------------ | | Secret key | `X-API-Key: sk_...`, plus `X-On-Behalf-Of: ` for user-scoped calls | Backend-to-backend; follow the operation's scope | | Publishable key + JWT | `X-API-Key: pk_...` + `Authorization: Bearer ` | 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 \{#user-impersonation} | Header | Required | Description | | --------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | `X-On-Behalf-Of: ` | 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](/api/authentication) for credential configuration, required headers, key limits and authentication errors. For a complete integration, follow the [signed-in conversation recipe](/core-platform/identity-access/authentication). ## APIs \{#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](/api/conversations) | Threads, messages, feedback, tools, memories and voice sessions. | | [End users](/api/end-users) | Profile self-service, location, locale, generation preferences and metadata. | | [Notifications](/api/notifications) | Push, inbox, preferences, topics, subscribers, workflows and providers. | | [Scheduled jobs](/api/scheduled-jobs) | Cron, one-shot and recurring schedules, with execution history. | | [Webhooks](/api/webhooks) | Outbound endpoints, subscriptions, delivery history and retries. | | [Agent profiles](/api/agent-profiles) | Agent profiles and shared prompt fragments: create, version, delete and import. | | [Custom MCP servers](/api/mcp-servers) | Register, update, remove and test your own HTTP MCP servers. | | [Project secrets](/api/secrets) | Store project credentials; retrieve their metadata without returning secret values. | | [Connected apps](/api/connected-apps) | App discovery, account connections, authenticated app API calls and offboarding. | | [Evaluations](/api/evals) | Traces, scores, reviewer feedback, datasets, runs and annotation queues. | | [Storage](/api/storage) | Upload and access application files using the storage operations. | Use the [Domain models](/api/models) index for reusable business types and their uses. Operation pages own their request and response bodies. The [Event catalog](/api/events) links lifecycle events, payload fields, examples and receiver verification guidance. Shared error support types include [ErrorDetails](/api/models/schema-1f7d7kh0s1), [ErrorInfo](/api/models/schema-1es9uii84j), [FieldViolation](/api/models/schema-1eu5noj3g1), [HelpLink](/api/models/schema-1f0qdi91b8), [ModelError](/api/models/schema-1f2939tg20), [RetryInfo](/api/models/schema-1f439vae2d), [RpcError](/api/models/schema-1fajlacjs0), [UpstreamError](/api/models/schema-1f66rlcp5a). Follow each model’s uses and the error fields on [synchronous message results](/api/conversations/send-message-sync#response-field-error), [synchronous client-tool results](/api/conversations/submit-client-tool-results-sync#response-field-error) and [generation completion](/api/events/u1u0sjgmch). 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](/api/events#delivery-envelope). ## Idempotent requests \{#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 \{#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](/core-platform/scheduling/verifying) and [webhook deliveries](/integrations/webhooks/deliveries) for receiver requirements and the [current event metadata and signature format](/api/events#delivery-envelope). ## Postman collection \{#postman-collection} Every endpoint above, ready to import: * **[Collection](/postman/travila-platform.postman_collection.json)** — one folder per API, 180 requests * **[Environment](/postman/travila-platform.postman_environment.json)** — `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 (`""`, `""`) 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 \{#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 \{#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 \{#publication-status\_definitions-current-contract} Describes the current API contract. Check the page’s prerequisites and the API version available in your deployment. ## Preview \{#publication-status\_definitions-preview} Preview behavior has the scope and limitations stated by the section. Check those limitations before depending on it. ## Upcoming \{#publication-status\_definitions-upcoming} Proposed behavior that is not yet available. ## Mixed availability \{#publication-status\_definitions-mixed} This page contains sections with different availability. Use the label on the specific section you need. ## Deprecated contract \{#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 \{#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 \{#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 \{#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](/api/mcp-servers) | Declared contract | 6 | | [Scheduler APIs](/api/scheduled-jobs) | Declared contract | 10 | | [Eval APIs](/api/evals) | Declared contract | 27 | | [Notification APIs](/api/notifications) | Declared contract | 48 | | [Third-Party Integrations APIs](/api/connected-apps) | Declared contract | 8 | | [Webhook APIs](/api/webhooks) | Declared contract | 9 | | [Agent Profile APIs](/api/agent-profiles) | Declared contract | 14 | | [End User APIs](/api/end-users) | Declared contract | 5 | | [Project Secret APIs](/api/secrets) | Declared contract | 4 | | [Storage APIs](/api/storage) | Declared contract | 15 | | [LLM APIs](/api/conversations) | Declared contract | 34 | --- URL: https://docs.travila.ai/api/agent-profiles/selection-and-versioning # Profile selection and prompt versions \{#overview} An active profile supplies reusable configuration and renders prompt variables at generation time. Profile versions, fragment versions and the selected conversation settings describe different parts of the resulting prompt. ## Profile and fragment version resolution \{#how-it-works} Unpinned conversations read later profile changes on a later turn. A nonzero profile version pin keeps the selected profile content, but fragments currently resolve from the latest fragment set even when the profile is pinned. Keep the resolved generation context when investigating a past turn; a saved profile does not capture every input or guarantee the same model response. ## Version history \{#version-history} There is no rollback endpoint. To revert, `get` the old version and `update` with its contents; that appends a new version rather than rewriting history. ## Fragment-set versions \{#prompt-fragments-set-versions} Fragments are versioned as a **set**, not individually: any fragment write bumps one project-wide [`setVersion`](/api/agent-profiles/get-prompt-fragment-set#request-field-setversion), reported by `prompt-fragments/list`. Record that number alongside the profile version and resolved inputs. These identify source content; they do not by themselves establish the final prompt. Prompt processing and any context added during the turn can change what the model receives. A profile version tells you what its own prompt looked like; the fragment-set version tells you what the blocks it included looked like. Keep both versions and the values supplied for that turn with its diagnostic trace when one is available. Profile pins currently do not pin the fragment set; reading an older set does not select it for future generation. These records do not guarantee identical model output. [`setVersion`](/api/agent-profiles/get-prompt-fragment-set#request-field-setversion) is `0` when no fragment has ever been written in the project. ## Profile selection and tool inheritance \{#configuration-agent-profiles} Read the resulting conversation configuration and inspect a later reply. An empty [`setActiveProfileId`](/api/conversations/send-message#request-field-setactiveprofileid) leaves the selection unchanged: the current API cannot return a selected conversation to unprofiled operation. A conversation that needs to remain unprofiled must not select an active profile. Recheck attached services as well. A profile’s [`mcpServers`](/api/models/schema-1hmbcecg1j#request-field-mcpservers) replaces the conversation list, including when the profile list is empty. Use [`overrideMcpServers`](/api/conversations/send-message#request-field-overridemcpservers) for a supported per-turn selection; see [agent tools](/api/tools/selection#per-turn-servers). ## Prompt-variable persistence \{#configuration-prompt-variables} A profile's system prompt can carry `{{.variable}}` placeholders declared in its [`variableSpecs`](/api/models/schema-1hmbcecg1j#request-field-variablespecs). Prompt variables are where the values come from — set on the conversation, re-rendered into the prompt on **every** subsequent turn, so the last value you set is reused. Update it when the underlying fact changes. This is a **merge**, not a replace: variables you do not send keep their current values. Pass [`updateMask`](/api/conversations/update-prompt-variables#request-field-updatemask) to restrict the write to named variables. ## Prompt rendering per send \{#configuration-render-timing} Variables are rendered into the active profile's system-prompt template at **generation time, per send** — late-binding. An update takes effect on the next `send-message` call; it never changes an in-flight turn. ## When the active profile cannot be used \{#configuration-when-the-active-profile-cannot-be-used} A conversation's profile has to exist and be enabled, both when you name it and on every turn after. The call fails before anything else happens: | Error code | HTTP | Meaning | | -------------------------- | ---- | ---------------------------------------------- | | `ACTIVE_PROFILE_NOT_FOUND` | 404 | No profile with that id exists in the project. | | `ACTIVE_PROFILE_DISABLED` | 400 | The profile exists but is switched off. | You get these from [`activeProfileId`](/api/conversations/create-thread#request-field-activeprofileid) on `CreateThread`, from [`setActiveProfileId`](/api/conversations/send-message#request-field-setactiveprofileid) on `SendMessage` / `SendMessageSync`, and from any `SendMessage` on a conversation whose bound profile has since been deleted or disabled. A rejected `SendMessage` changes nothing: no message is appended, no event is published, and the conversation stays on the profile it had. A conversation stuck on an unusable profile is not lost. Re-enable the profile, or move the conversation with [`setActiveProfileId`](/api/conversations/send-message#request-field-setactiveprofileid) to one that works, and the next send goes through. The one exception is a message **queued** behind a running turn (see [`interruptPolicy`](/api/models/schema-ph6avse89k#request-field-interruptpolicy)): the profile is not checked when a queued message is accepted, and when its turn comes it runs on the conversation's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig) instead of failing, with [`generationContext.profileId`](/api/models/schema-1im79fphmq#response-field-profileid) empty and [`promptSource`](/api/models/schema-1im79fphmq#response-field-promptsource) not `PROMPT_SOURCE_PROFILE_TEMPLATE`. --- URL: https://docs.travila.ai/api/connected-apps/account-selection # Connected account selection \{#overview} Discovered integration tools depend on the connected accounts and provider schemas. A completed tool call can represent a request to connect rather than completion of the requested business action. ## Discovered tool schemas \{#connected-apps-what-a-tool-call-looks-like} Tool names, arguments and result shapes come from the enabled integration. The optional component-action mode exposes component keys and `exports`/`ret` outputs; other modes can differ. Some account-dependent inputs or missing required fields are supplied only after an attempted call. Use the discovered schema and actual error; do not hardcode a Slack, GitHub or calendar action's fields into a generic connected-app handler. ## Multiple account selection \{#connected-apps-when-a-user-has-more-than-one-account} Run Connect again to add another account for the same app. When discovery sees multiple accounts, the app's tools require `x_account_id` with an allowed account ID. With one account, the integration binds that account without the extra selector. The discovered list can be up to a minute old. Recheck the connection when a call fails, and do not treat an account still appearing in a list as consent for a new action. Recurring work needs particular care: the current API does not provide a control that preserves the intended account consent across connection changes. ## Account connection tools \{#connected-apps-the-account-meta-tools} The `pd_list_accounts` and `pd_connect_account` tools bypass [`allowlistToolPatterns`](/api/models/schema-1hik90rmo1#request-field-allowlisttoolpatterns), but a blocklist matching `pd_*` or `*` excludes them. Include that distinction when deciding whether this assistant may initiate a connection flow. ## Unconnected app results \{#connected-apps-what-an-unconnected-app-does} An unconnected app can still expose tools. Calling one may return a connect link with `TOOL_EXECUTION_STATUS_COMPLETED`; that status does not mean the requested calendar action happened. The model can omit the link from its answer. ## Connection-link answer deadline \{#connected-apps-option-2--hand-the-link-back-with-a-client-tool} The run has a bounded wait: read [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat) and configure [`toolPolicy.clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for the interaction. The default is five minutes. If the user cannot finish in time, report the unsuccessful attempt and let them continue through your normal connection screen. --- URL: https://docs.travila.ai/api/conversations/context-and-compaction # Context and compaction \{#overview} Context assembly selects the content supplied to generation. Compaction changes that input independently of the run outcome and the stored conversation history. ## Context from the latest user message \{#client-context-understand-when-it-applies} The current generation path takes client context from the latest user message. Resend relevant current context on each user message that needs it; an earlier message is not a persistent context setting. [`append-message`](/api/conversations/append-message) stores a message without starting generation. If a subsequent user message becomes the latest one, its context is the one considered for generation. Appending context does not guarantee that the next reply will use it. ## History strategies \{#configuration-context-management} Three strategies control how message history is trimmed before each generation: `CONTEXT_STRATEGY_WINDOWING` (default, drops old messages), `CONTEXT_STRATEGY_COMPACTION` (summarizes old messages, keeping the gist), and `CONTEXT_STRATEGY_NONE` (full history). Selective exclusion of images, files, tool results, and reasoning composes with any strategy. For threshold calculations, modes, pending records and failure effects, use the [compaction semantics](/api/conversations/context-and-compaction#context-management-how-compaction-works) and [failure behavior](/api/conversations/context-and-compaction#context-management-failure-behavior) below. The [context-management guide](/managed-agents/conversations/context-management) walks through a compaction task. ## Pending compaction records \{#context-management-watch-a-compaction-complete} `compactionInProgress: true` means a compaction is recorded as pending. It can be queued, running or stale. Inspect the record and reconcile within a bounded wait; neither this flag nor conversation inactivity proves completion. ## Live compaction updates (Preview) \{#context-management-realtime-events-preview} If your deployment has a supported conversation update transport, use `CompactionStarted`, `CompactionCompleted` and `CompactionFailed` as cues to refresh the compaction record. These events appear on `conversations/{id}/compaction`; see [streaming availability](/managed-agents/conversations/streaming). ## Compaction failure effects \{#context-management-failure-behavior} | Mode | Failure effect | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `COMPACTION_MODE_SYNC` | The send call fails. No generation runs. Retry the send after the underlying issue is resolved. | | `COMPACTION_MODE_ASYNC` | The current turn proceeds with uncompacted context and can succeed or fail independently. The failure is visible via `compactions[].status = "COMPACTION_STATUS_FAILED"` and the `CompactionFailed` realtime event (Preview). | For a synchronous failure, resolve the summarizer/configuration problem before retrying the rejected send. For an asynchronous failure, first inspect the original run because that turn can still have completed. Do not resend a user question merely to retry background compaction. ## Strategy updates \{#context-management-choose-a-strategy} Use windowing when the customer no longer needs older details in later replies. It avoids a summarizer call and excludes older messages from model input; its default window is 100 messages. Choose before storing an explicit strategy: the current update path rejects switching to another strategy. Updates within the selected strategy are separate. Use [the settings reference](/api/conversations/update-context-management-settings) to configure the chosen path. ## Compaction threshold estimates \{#context-management-how-compaction-works} Use [the context settings reference](/api/conversations/update-context-management-settings) for exact configuration fields. The estimate uses the latest available assistant [`usage.promptTokens`](/api/models/schema-1j1vov2uoh#response-field-prompttokens) plus estimates for newer content. Until usage is available, it falls back to roughly four characters per token, 1,000 tokens per image and size-based file/audio estimates. A percentage threshold uses the resolved model window, with a current 128,000-token fallback when positive metadata is unavailable. That fallback is not proof of the actual provider limit. The threshold is checked before generation after applying the selected strategy and does not include every later request change. Changed prompts, tools or models can also make an earlier measured count a poor predictor. ## Synchronous and asynchronous compaction \{#context-management-sync-vs-async} Synchronous compaction finishes the summary and reassembles context before generation, so the next answer waits for the summary. The [compaction recipe](/managed-agents/conversations/context-management) uses this mode when the answer needs the new summary. Use `COMPACTION_MODE_ASYNC` only when the current answer can use uncompacted context. Inspect that run independently and wait for the compaction record before assuming a later turn has a summary. Background acceptance does not promise uninterrupted concurrent messaging; compaction can still delay other messages. ## Stale pending compactions \{#context-management-stale-pending-compactions} A compaction stuck in `COMPACTION_STATUS_PENDING` for more than 10 minutes is marked `COMPACTION_STATUS_FAILED` on the next send. Refresh its record before deciding whether another compaction is needed; pending does not necessarily mean it is still running. ## Content exclusion \{#context-management-trim-content-selectively} [`selectiveExclusionConfig`](/api/models/schema-1hgrvsu34j#request-field-selectiveexclusionconfig) strips specific content types from the assembled context **before it is sent to the model**. It composes with any strategy — including NONE — and is applied per-request. It never mutates stored message history. Excluding tool results removes [`resultJson`](/api/models/schema-1it6mqsqoo#response-field-resultjson) while retaining the call. Excluding an image can leave an empty message, which is then omitted from model input. Files and reasoning can also be excluded; use the [settings reference](/api/conversations/update-context-management-settings) for those options. --- URL: https://docs.travila.ai/api/conversations/messages-and-runs # Messages and runs \{#overview} Conversation activity, accepted runs and persisted messages have distinct identities. These rules apply across asynchronous sends, synchronous replies and state reads. ## Required attachments \{#attachments-decide-whether-the-file-is-required} Omitting the resolution mode skips content it cannot resolve. Use `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` when answering without the file would be misleading. If omission is acceptable, your application should still tell the user when required context is unavailable rather than presenting a complete analysis. ## Conversation activity and submitted-run outcomes \{#build-chat-assistant-step-4-render-the-conversation} Conversation activity answers whether a run is executing now. It does not answer whether a particular submitted question has finished. Keep those two states separate in the chat display: | State read | Display and next action | | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | [`activeRunning`](/api/conversations/get-conversation-state#response-field-activerunning) is `true` | Show current activity. For one outstanding turn at a time, keep another send disabled until the retained run is resolved. | | [`activeRunning`](/api/conversations/get-conversation-state#response-field-activerunning) is absent | No run is currently active. Match the submitted run to its reply and terminal outcome before showing completion. | This distinction matters after a queued send or a lost connection: the conversation can be idle without providing a correlated outcome for that request. Preserve the request as unresolved and follow [send reconciliation](/managed-agents/conversations/generation#polling-recipe) before offering a retry. ## Interrupt policy \{#configuration-interrupt-policy} Controls what happens when a user sends a new message while a generation run is already in progress. Use the full enum value in the wire format: | Policy | Behavior | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `INTERRUPT_POLICY_REJECT_NEW` | The send fails immediately with an active-run error. The new message is **not** appended to history. | | `INTERRUPT_POLICY_CANCEL_ONGOING` | The active run is cancelled; the new run starts immediately. The cancelled run's response is marked `interrupted: true`. | | `INTERRUPT_POLICY_QUEUE` | The message goes into a **pending queue** (not yet history). When the active run completes, messages drain FIFO — each dequeued message is re-evaluated against the **current** policy at that moment. The queue has no depth cap. | | `INTERRUPT_POLICY_IGNORE` | The message is accepted but **not persisted** to history. The active run is unaffected and never sees it. | ## Run outcomes \{#generation-interpret-the-outcome} | [`status`](/api/conversations/send-message-sync#response-field-status) | Meaning and next step | | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AGENT_STATUS_COMPLETED` | The run finished. Read the returned messages; check the assistant's [`finishReason`](/api/models/schema-1j3dcf7kvu#response-field-finishreason) to understand why the model stopped. | | `AGENT_STATUS_FAILED`, `AGENT_STATUS_CANCELLED`, `AGENT_STATUS_TIMED_OUT` | The run ended unsuccessfully. Do not turn absent messages into a successful empty reply. | | `AGENT_STATUS_QUEUED` | The message was queued behind an in-flight run; this response does not contain its completed reply. Reconcile using the [asynchronous polling recipe](/managed-agents/conversations/generation#async-generation); the current queued-operation correlation is incomplete, so idle alone does not establish this request's outcome. | | `AGENT_STATUS_AWAITING_CLIENT_TOOLS` | Execute [`pendingClientTools`](/api/conversations/send-message-sync#response-field-pendingclienttools) and echo [`clientToolCursor`](/api/conversations/send-message-sync#response-field-clienttoolcursor) when submitting results, following the [client-tool loop](/managed-agents/delegation-approvals/using-tools#client-side-tools). | | `AGENT_STATUS_ACTIVE` | The bounded wait ended while the run was still going. Do not start another run. Reconcile the same run through `get-conversation-state`, preserving unknown state when correlation is unavailable; see also the [tool recovery guidance](/managed-agents/delegation-approvals/using-tools#if-the-connection-drops). | | *absent* | No [`status`](/api/conversations/send-message-sync#response-field-status) key at all. Treat the outcome as unknown and reconcile the same run. Do not assign an unrelated [`lastRunStatus`](/api/conversations/get-conversation-state#response-field-lastrunstatus) to it. | `COMPLETED`, `FAILED`, `CANCELLED`, and `TIMED_OUT` are recognized terminal outcomes, each with the `AGENT_STATUS_` prefix. Agent run status has no `SUCCESS` alias; the legacy alias belongs only to tool execution status. An absent or unrecognized value is an unknown outcome. Reconcile it with a bounded wait; it is not proof of success, failure or continued activity. See [Run status and model finish reason](/api/tool-execution/policies#using-tools-two-rules-for-clients). > **Caution: [`status`](/api/conversations/send-message-sync#response-field-status) can be missing entirely** > > The field is omitted rather than sent as an empty string, so read it with a default — `body.status ?? ""` — not a presence check that throws. The reachable case is `submit-client-tool-results-sync` for a run that had already finished before your results arrived: the response carries [`runId`](/api/conversations/send-message#response-field-runid) and [`clientToolCursor`](/api/conversations/send-message-sync#response-field-clienttoolcursor) and nothing else. This response does not establish success or failure. The run ended before this submission; consult a correlated outcome, and retain uncertainty if the most recent state now belongs to another run. ## Failed responses and diagnostics \{#generation-failed-responses-and-diagnostics} Empty [`messages`](/api/conversations/send-message-sync#response-field-messages) can be omitted. Do not require an inline `error` or `failureReason` to recognize this failure: an explanation is not guaranteed in this response. Other failures propagate as HTTP errors with an error body, so handle both non-success HTTP responses and unsuccessful run statuses. Immediate model validation failures are described in [Model selection failures](/api/model-controls/routing#errors-error-payload). ## Conversation, run and message identities \{#payloads-keep-identities-distinct} | Field or identity | Meaning | | ------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | Conversation key | The thread to read; it is not an access token | | Accepted [`runId`](/api/conversations/send-message#response-field-runid) | The generation operation returned by the send | | [`activeRunId`](/api/conversations/get-conversation-state#response-field-activerunid) | The run currently recorded as active on the conversation | | Message [`sequence`](/api/models/schema-1j3dcf7kvu#response-field-sequence) | The persisted message's order within the conversation | | Conversation activity sequence | An activity update sequence, separate from message ordering | | Tool-call ID | The complete call whose approval or result is being submitted | Message [`sequence`](/api/models/schema-1j3dcf7kvu#response-field-sequence) values are JSON strings containing 64-bit integers. Keep them as strings for transport and use a 64-bit integer or big-integer type for numeric comparison; converting large values to floating point can change their order. An assistant message need not have the user message's sequence plus one: tool rounds and other messages can appear between them. ## State reconciliation \{#payloads-render-and-reconcile} An absent or false [`activeRunning`](/api/conversations/get-conversation-state#response-field-activerunning) means the conversation has no recorded active run; false is normally omitted. [`lastRunStatus`](/api/conversations/get-conversation-state#response-field-lastrunstatus) reports its latest recorded outcome, which can belong to a newer run. It does not provide a complete history of outcomes for concurrent or queued sends. Refresh state after disconnects and retain an unknown outcome when correlation is unavailable. ## Persisted message reads \{#subscribing-read-the-current-conversation} Use returned persisted messages to refresh the display. While [`activeRunning`](/api/conversations/get-conversation-state#response-field-activerunning) is true, compare [`activeRunId`](/api/conversations/get-conversation-state#response-field-activerunid) with the accepted run. Once activity ends, [`lastRunStatus`](/api/conversations/get-conversation-state#response-field-lastrunstatus) describes the latest run recorded on the conversation. It is not a receipt for every earlier send: a newer or concurrent run can replace it. Keep an unresolved outcome visible when you cannot correlate it. --- URL: https://docs.travila.ai/api/evals/datasets # Dataset identity and run provenance \{#overview} An evaluation harness executes cases and preserves their inputs. Dataset identities, recorded run associations and enriched read models describe different parts of that evidence. ## Dataset and run identifiers \{#dataset-identifiers} | Operation context | Dataset identity | | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | List dataset items or list dataset runs: [`datasetName`](/api/evals/list-dataset-items#request-field-datasetname) | Human-readable dataset name. | | List dataset items: [`datasetId`](/api/evals/list-dataset-items#request-field-datasetid) | Actual dataset ID returned by the API. | | Add dataset item: [`datasetId`](/api/evals/add-dataset-item#request-field-datasetid) | Dataset name, despite the field name. | | Update dataset item: [`datasetId`](/api/evals/update-dataset-item#request-field-datasetid) | Dataset name, despite the field name. | Follow the selected operation's contract; there is no global substitution between a dataset name and ID. ## Run association and scoring limits \{#run-association} Your harness executes the cases under its configured permissions and budget; the platform does not execute a dataset. A turn joins a dataset run only when the message that starts it carries an [`experiment`](/api/models/schema-1icbr3lltu) block on `send-message` or `send-message-sync`, naming the dataset ID (not the name), the run name and, per case, the dataset item ID. There is no operation that associates an already-recorded trace with a run. Turns that carry a dataset item ID and turns that do not currently land in different runs even under the same run name, so set it on every turn of a run. Read back the run and expected items before treating the experiment as recorded; keep your harness manifest and item outcomes, and contact your Travila operator if an expected run remains absent. A run item links a dataset item to the trace produced by the harness, optionally narrowed to an observation. It does not itself carry a score. The current public `record-score` operation supports qualified trace scoring; `EVAL_TARGET_TYPE_DATASET_RUN` appearing in the schema does not establish working dataset-run scoring. Keep harness results in a versioned report and use only verified score-ingestion paths until that gap is closed. [`profileRevisionHash`](/api/models/schema-1icbr3lltu#request-field-profilerevisionhash) is supplied run metadata. It is not the same as the producer's current [`configHash`](/api/models/schema-1k4mjul65u#response-field-confighash), and neither alone recreates an experiment. Save immutable profile and fragment revisions, resolved settings, model/provider, code, tool fixtures, memory/index versions, dataset item versions, evaluator/rubric version and environment. Frozen inputs must be explicitly captured; the current add-item endpoint does not capture them for you. ## Run reads and incomplete enrichment \{#run-reading} | Read behavior | Interpretation | | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Current run-list pagination | Continue with [`cursorPage.nextCursor`](/api/models/schema-oi1c4l4i8b#response-field-nextcursor) while preserving dataset and time bounds. Older deployments may expose page-based pagination. | | Dataset-name lookup | Searches only the first dataset page. | | Item-count enrichment | Can be capped or fail; zero does not prove that no cases ran. | | [`lastRunAt`](/api/models/schema-1ja63aqvqo#response-field-lastrunat) and [`runCount`](/api/models/schema-1ja63aqvqo#response-field-runcount) | History hints that can remain absent or zero after failed enrichment. | Read the expected run directly and compare it with the harness record before concluding that the suite has not been executed. ## Cursor pagination \{#pagination} Start without a cursor, then pass the exact [`cursorPage.nextCursor`](/api/models/schema-oi1c4l4i8b#response-field-nextcursor) returned by the previous response. Keep the original scope, filters and time bounds. Continue until no cursor remains; a short or empty page alone does not finish the search. Preserve your collected identities and known coverage if retrieval is interrupted. Do not infer page numbers or totals from a cursor, treat a missing total as zero, or treat sampled facets as every value in the account. Large integer fields use decimal strings; preserve their precision as described in the [common API contract](/api#field-names). --- URL: https://docs.travila.ai/api/evals/scoring # Feedback and score attribution \{#overview} Message ratings, human review and automated scores have distinct producers and update paths. Preserve source attribution and reconcile stored results independently of delayed analytics projections. ## Message rating and analytics projection \{#message-rating} | Property | Contract | | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | Eligible messages | Only `ROLE_ASSISTANT` messages can be rated. | | [`ratedMessage.feedback`](/api/models/schema-1j3dcf7kvu#response-field-feedback) | Complete feedback list across raters. | | [`isUpdate`](/api/conversations/rate-message#response-field-isupdate) | True when the caller replaced their previous rating on the message. | | Evaluation projection | Asynchronous ingestion can produce `SCORE_SOURCE_USER` analytics. This copy can be delayed, absent or stale and is separate from the stored message rating. | ## Reading and withdrawing message feedback \{#rating-reading} | Operation | Feedback behavior | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Get conversation state | Returns assistant-message feedback with the message history. | | Send a message | Ignores supplied feedback; it is not a feedback-write path. | | Rate a message | Creates or replaces the caller's own rating. | | Delete a message rating | Removes only the caller's entry and preserves other raters. An absent rating is an idempotent success; omitted [`removed`](/api/conversations/delete-message-rating#response-field-removed) means false. | ## Score sources \{#score-sources} | Source | Producer or interpretation | | ---------------------- | --------------------------------------------------------------------- | | `SCORE_SOURCE_USER` | Feedback from an end user, projected through the message-rating path. | | `SCORE_SOURCE_HUMAN` | A human reviewer's annotation. | | `SCORE_SOURCE_JUDGE` | An automated judge result. | | `SCORE_SOURCE_EVAL` | A managed evaluator result reported by the evaluation provider. | | `SCORE_SOURCE_HARNESS` | A harness or other API-based score producer. | Keep these populations separate when aggregating. Equal numeric scales do not make end-user sentiment, reviewer assessment and automated measurements interchangeable. Use the supported [`source`](/api/evals/list-scores#request-field-source) filter and retain the provider's [`sourceLabel`](/api/models/schema-1jm5lo00e7#response-field-sourcelabel) when exact upstream attribution matters. Reviewer assessment belongs in the evaluation review path, separate from end-user message feedback and its product behavior. Declared source values alone do not establish that every source is supported for public writes; see [supported score writes](/api/evals/scoring#score-writes). ## Supported score writes and configuration \{#score-writes} | Write concern | Current contract | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Qualified score values and targets | Use numeric or boolean values on trace targets. Categorical/text values and observation/session/dataset-run writes are not supported by the qualified write path, even though the enum vocabulary names them. | | Human-review source | Use `SCORE_SOURCE_HUMAN`. A missing [`configId`](/api/evals/record-score#request-field-configid) for this source returns HTTP 400. Create its score configuration first. | | Rater attribution | Derived from verified caller context, not a body field. | | Score configuration retirement | Archive with [`isArchived`](/api/evals/update-score-config#request-field-isarchived); retrieve archived configurations with [`includeArchived`](/api/evals/list-score-configs#request-field-includearchived) when needed for historical scores. | The platform derives a score ID from target, rater and score name. Repeat scoring across days is not qualified as replacement of the earlier provider record. Serialize review actions and reconcile the stored result; a stable ID alone does not guarantee duplicate-free ingestion or event ordering. --- URL: https://docs.travila.ai/api/events # Event catalog \{#event-catalog} Choose an event by lifecycle, then follow its payload fields and examples. Use [the receiver recipe](/integrations/webhooks/endpoints) to connect it to your backend or [delivery recovery](/integrations/webhooks/deliveries) to investigate a missing update. The [verification procedure](#delivery-envelope) explains the configured webhook signature format. Domain payload examples are not complete HTTP deliveries. ## Webhook events \{#webhook-events} Manage the receiver through the [endpoint](/api/webhooks/create-webhook-endpoint) and [subscription](/api/webhooks/create-webhook-subscription) contracts. Use the lifecycle and payload references below to interpret the declared event data. ### Delivery envelope \{#delivery-envelope} Webhook deliveries use HTTP POST. Preserve the original request body bytes and verify the delivery before parsing or acting on its contents. Event examples on the linked pages describe the event-specific payload; runtime metadata and the HTTP delivery contract are separate. For a receiver configured for Convoy’s timestamped SHA-256/hex signatures, the signature header is `X-Convoy-Signature: t={unix_seconds},v1={hex}`. Confirm the endpoint’s configured signature header, algorithm and encoding before enabling the receiver. An unrecognized or missing signature is a rejection, not a reason to bypass verification. | Header | Meaning | | -------------------------- | ------------------------------------------------------------------------------------------------- | | `X-Convoy-Event-Type` | Routing event name. Check it against authenticated event metadata before use. | | `X-Convoy-Idempotency-Key` | `{event_id}:{endpoint_id}`. Bind it to authenticated event identity and your configured endpoint. | | `X-Convoy-Signature` | Signing timestamp and one or more versioned signatures for the configured verification scheme. | Obtain the endpoint’s [`secret`](/api/models/schema-1ffl20kv2k#response-field-secret) when creating it, or retrieve the endpoint through [List webhook endpoints](/api/webhooks/list-webhook-endpoints). Keep the secret on your backend. In the timestamped format above, compute HMAC-SHA256 over the timestamp text, a comma, and the raw request body bytes. Decode the received digest as hex; neither a body-only HMAC nor base64 matches this format. 1. Bound body/header size and the number of signature fields. Reject missing separators, malformed hex, invalid timestamps and repeated timestamp fields without an unhandled error. 2. Require one signing timestamp and at least one supported signature version. Preserve multiple `v1` values during a qualified key-overlap period. 3. Enforce a bounded timestamp tolerance with an explicit clock-skew policy. Five minutes is an example receiver setting, not a platform-imposed acceptance window. 4. Compare equal-length decoded digests in constant time against the small configured set of current and overlap secrets. Never log a signing secret or signature. Do not re-serialize parsed JSON: whitespace or key-order changes alter the signed bytes. 5. After signature verification, validate the expected event schema, tenant/project scope and event identity from authenticated delivery metadata. Reject conflicting event-type or idempotency headers; these separate headers are not covered by the body HMAC. 6. Atomically persist the scoped event identity, payload digest and pending work before returning `2xx`. Acknowledge an identical duplicate without repeating the work; reject an identity reused with a different payload. If durable acceptance fails, return a non-success response so the configured delivery/reconciliation process can recover it. Runtime event metadata is supplied in `ctx`. Use these fields only with a deployment supporting this event contract. The domain payload examples omit runtime metadata and are not complete HTTP deliveries. The Convoy delivery format uses protobuf field names in snake\_case, while canonical API model views use their JSON field names. | Delivered metadata field | Meaning | | ------------------------ | ----------------------------------------------------------------------------------- | | `ctx.event_name` | Stable event name; compare with the event-type header. | | `ctx.version` | Event schema version. | | `ctx.event_id` | Unique event identity; bind duplicate detection to this value and the endpoint. | | `ctx.correlation_id` | Correlation identifier. | | `ctx.emitted_at` | Event emission time in RFC3339 form; this is separate from the signature timestamp. | | `ctx.caller_key` | Publisher-provided routing key. | | `ctx.metadata` | Application metadata as a string-to-string map. | | `ctx.tenant_id` | Tenant owning the event. | | `ctx.project_id` | Project within that tenant. | | `ctx.session_id` | End-user application session identifier. | After verifying the signature, use signed `ctx.event_name` for event type and signed `ctx.event_id` for event identity. Validate `ctx.tenant_id` and `ctx.project_id` against the expected scope. Reject conflicting type or idempotency headers. Do not treat a routing header or an invented context field as authenticated metadata. Timestamp tolerance limits old replays; it does not prevent duplicates inside the window. **Secret rotation:** [Update webhook endpoint](/api/webhooks/update-webhook-endpoint) does not accept a `secret` field, and this public API has no secret-rotation operation. An endpoint metadata update is not evidence that a signing key changed. Qualify any separately supported rotation procedure, receiver overlap and behavior of new/retried deliveries before relying on it. ### Event types \{#event-types} Choose the lifecycle your application needs, then inspect its selected payload contract: * [Message published](/api/events/u1s768tpmf) — [payload fields](/api/models/schema-po1qsocerv#response). An assistant or tool message is produced. * [Generation started](/api/events/u20phhssrl) — [payload fields](/api/models/schema-pnv14jb39g#response). A generation run starts. * [Generation completed](/api/events/u1u0sjgmch) — [payload fields](/api/models/schema-pntuu08p80#response). A generation run reaches a terminal outcome; inspect its status and run identifier. * [Tool call started or awaiting approval](/api/events/u22bdqd1kd) — [payload fields](/api/models/schema-po5rioe4il#response). A tool call begins execution or waits for human approval; inspect the ToolCall state. * [Tool call completed](/api/events/u249vf7739) — [payload fields](/api/models/schema-po3pkfshjg#response). A tool call reaches a terminal execution result. Message publication and generation completion can concern the same assistant turn. Keep their lifecycle handlers distinct and correlate their identifiers so they do not trigger the same business action twice. ### Payload shapes \{#payload-shapes} Follow each selected model to read its field names, types, presence and validation rules. The response view is a canonical domain-data reference; it is not a separate webhook wire contract. #### llm.message\_published \{#llmmessage\_published} [The message-published Event](/api/events/u1s768tpmf) describes a new assistant or tool message. Read [`message`](/api/models/schema-po1qsocerv#response-field-message) and the [Message model](/api/models/schema-1j3dcf7kvu#response) for its content and generation information. Message publication alone is not evidence that a run has reached its terminal outcome. #### llm.generation\_started \{#llmgeneration\_started} [The generation-started Event](/api/events/u20phhssrl) marks the start of a run. Inspect [`runId`](/api/models/schema-pnv14jb39g#response-field-runid), [`startingSequence`](/api/models/schema-pnv14jb39g#response-field-startingsequence) and the optional [`config`](/api/models/schema-pnv14jb39g#response-field-config) snapshot. The [GenerationConfig model](/api/models/schema-1h82h7ri5p#response) describes that configuration. Retain the run identifier with the application work it belongs to. #### llm.generation\_completed \{#llmgeneration\_completed} [The generation-completed Event](/api/events/u1u0sjgmch) marks a terminal run outcome. Inspect [`runId`](/api/models/schema-pntuu08p80#response-field-runid), [`status`](/api/models/schema-pntuu08p80#response-field-status), [`loopCount`](/api/models/schema-pntuu08p80#response-field-loopcount), [`durationMs`](/api/models/schema-pntuu08p80#response-field-durationms), [`usage`](/api/models/schema-pntuu08p80#response-field-usage), [`error`](/api/models/schema-pntuu08p80#response-field-error), [`usageByModel`](/api/models/schema-pntuu08p80#response-field-usagebymodel), [`turnKey`](/api/models/schema-pntuu08p80#response-field-turnkey). Use [Usage](/api/models/schema-1j1vov2uoh#response), [RpcError](/api/models/schema-1fajlacjs0#response) and [UsageByModel](/api/models/schema-po7orad6ac#response) for related values. A terminal outcome requires application-specific handling; do not mark every completed run as successful. ##### Values of status \{#llm-generation-completed-values-status} Lifecycle state of a workflow execution, distinct from the reason a terminal execution ended. Use [the selected workflow-status field and its generated enum values](/api/models/schema-pntuu08p80#response-field-status) for the canonical workflow lifecycle values, numeric values, wire spellings and descriptions. The source distinguishes lifecycle state from the reason a terminal execution ended, and retains the CANCELED wire spelling. The generated contract owns this enum table. Full payload: [LLMGenerationCompletedEvent](/api/models/schema-pntuu08p80#response). #### llm.tool\_call\_started \{#llmtool\_call\_started} [The tool-call-started Event](/api/events/u22bdqd1kd) describes a call that begins execution or waits for human approval. Read its [`toolCall`](/api/models/schema-po5rioe4il#response-field-toolcall) and the [ToolCall model](/api/models/schema-1it6mqsqoo#response). Use [`isClientTool`](/api/models/schema-1it6mqsqoo#response-field-isclienttool) to distinguish client execution and [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat) for the result deadline. Match the tool name against the client tools your application declared. For an approval wait, inspect [`status`](/api/models/schema-1it6mqsqoo#response-field-status) and [`requiresApprovalAt`](/api/models/schema-1it6mqsqoo#response-field-requiresapprovalat). The approval timestamp is a decision deadline, not the time the call began waiting. Reconcile pending work before retrying an action. #### llm.tool\_call\_completed \{#llmtool\_call\_completed} [The tool-call-completed Event](/api/events/u249vf7739) describes a terminal tool execution result. Read [`toolCall`](/api/models/schema-po3pkfshjg#response-field-toolcall) and [`executionTimeMs`](/api/models/schema-po3pkfshjg#response-field-executiontimems). Inspect the [ToolCall state and result](/api/models/schema-1it6mqsqoo#response) before changing application state. A terminal result can require failure handling as well as success handling. #### Approval waits \{#llmtool\_call\_approval\_required} Human approval is part of the declared [tool-call-started lifecycle](/api/events/u22bdqd1kd). Inspect [`status`](/api/models/schema-1it6mqsqoo#response-field-status) and [`requiresApprovalAt`](/api/models/schema-1it6mqsqoo#response-field-requiresapprovalat) on the [ToolCall model](/api/models/schema-1it6mqsqoo#response). The selected catalog does not declare a separate approval-required Event. Use [List pending tool approvals](/api/conversations/list-pending-approvals) to reconcile calls awaiting a decision and [Submit tool approvals](/api/conversations/submit-tool-approvals) to resolve them. Treat a missing deadline as unknown; do not assume the call can wait indefinitely. Check pending state before submitting or repeating a decision. ## Conversation updates \{#conversation-updates} Conversation updates and scheduled callbacks have their own contracts; do not infer their delivery or recovery rules from a generation Event. Never substitute a conversation activity sequence for a message sequence, or treat an idle conversation as proof that a particular run completed. --- URL: https://docs.travila.ai/api/notifications/delivery # Push registration and topic delivery \{#overview} Recipient registration and topic membership describe who can receive a notification. Trigger acceptance and provider acknowledgements do not establish arrival. ## Device registration presence \{#device-registration} | Response condition | Interpretation | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | A channel omits [`registered`](/api/models/schema-1kaqut27uf#response-field-registered) and [`credentialCount`](/api/models/schema-1kaqut27uf#response-field-credentialcount) | It has no registered credentials. Check the intended signed-in user and current device token. | | [`remainingCredentialCount`](/api/notifications/unregister-push-device#response-field-remainingcredentialcount) is present after removal | Its positive value counts credentials still registered for other devices. | Follow [enrollment recovery](/core-platform/notifications/push#device-lifecycle) before retrying a test notice. Confirming registration does not establish delivery. ## Topic identity and membership results \{#topic-membership} Use the [topic operation reference](/api/notifications/create-topic) to distinguish the key you choose from the topic identifier returned by the service. Check the [membership result](/api/notifications/check-topic-subscription#response-field-issubscribed) and the [per-user failure results](/api/models/schema-p2eb0gb1ln) before treating a batch as complete. ## Topic delivery and retirement \{#topic-sends} | Field | Behavior | | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | [`excludeUserId`](/api/notifications/send-to-topic#request-field-excludeuserid) | Excludes one recipient, commonly the person who triggered the event. | | [`acknowledged`](/api/notifications/send-to-topic#response-field-acknowledged) | Indicates acceptance of the topic send. | | [`status`](/api/notifications/send-to-topic#response-field-status) | Provider acknowledgement text. Do not treat it as a closed set of delivery states. | Deleting a topic returns an operation result in [`status`](/api/notifications/delete-topic#response-field-status). Its acknowledgement reports the deletion outcome; provider text defaults to `done` when no text is supplied. Stop future triggers and handle pending notifications separately when retiring a topic. See [delete topic](/api/notifications/delete-topic). --- URL: https://docs.travila.ai/api/notifications/inbox # Inbox state and actions \{#overview} Inbox messages expose read, seen and archive state alongside action identities. Live updates are cues to reconcile that state, and reversing inbox state does not reverse an external business action. ## Read and seen status values \{#inbox-status} | Value supplied to a mark operation | Requested change | | ---------------------------------- | ---------------------- | | `MESSAGE_STATUS_SEEN` | Mark the message seen. | | `MESSAGE_STATUS_UNSEEN` | Clear its seen state. | | `MESSAGE_STATUS_READ` | Mark the message read. | | `MESSAGE_STATUS_UNREAD` | Clear its read state. | Returned inbox status reflects archive, read and seen state in that order of precedence. `UNREAD` is an update choice; reads report `UNSEEN` or `SEEN` when the message is neither read nor archived. ## Inbox action identifiers \{#inbox-identifiers} Feed entries expose two different identities: | Identity | Operations that use it | | ------------------------------------------------------------------------------- | ------------------------------------------------------- | | [`messageId`](/api/models/schema-1kescd68ar#response-field-messageid) | Mark or delete an inbox message. | | [`notificationId`](/api/models/schema-1kescd68ar#response-field-notificationid) | Archive, unarchive, complete or revert an inbox action. | Passing [`messageId`](/api/models/schema-1kescd68ar#response-field-messageid) to an operation addressed by [`notificationId`](/api/models/schema-1kescd68ar#response-field-notificationid) fails to find the intended message. ## Archive outcomes and retries \{#inbox-archive} | Operation | Scope or result | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Archive or unarchive one message | An absent message returns `acknowledged: true` and `status: "not_found"`. | | Archive all inbox messages | Optional [`tags`](/api/notifications/archive-all-inbox-messages#request-field-tags) restrict the sweep; matching any supplied tag includes the message. | | Archive all read inbox messages | The same tag selection applies, restricted to read messages. | After a dropped response, refresh the stored state. Retry only if the action remains the user's current choice: a delayed archive must not undo a later unarchive. Inspect [`status`](/api/models/schema-ok4lj6t1ka#response-field-status) to distinguish an absent message from a completed mutation. ## Action payloads and outcomes \{#inbox-actions} | Property or operation | Meaning | | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | [`actions`](/api/models/schema-1kescd68ar#response-field-actions) | Up to two call-to-action buttons on a feed entry. | | [`isPrimary`](/api/models/schema-1kcu6c9rot#response-field-isprimary) | Identifies the primary action. | | `ACTION_TYPE_PRIMARY` / `ACTION_TYPE_SECONDARY` | Selects which action to complete or revert. | | Revert action | Clears the inbox completion state. It does not undo a business operation; any authorized business compensation requires a separate operation. | ## Session fields and live events \{#inbox-session} The [inbox session response](/api/notifications/get-inbox-session) provides the connection URL, token and validity period. Read its field definitions for the exact response types and units. The [`socketUrl`](/api/notifications/get-inbox-session#response-field-socketurl) + [`token`](/api/notifications/get-inbox-session#response-field-token) from `get-inbox-session` open a **Socket.IO** connection that pushes inbox changes live — no polling needed for the common case. Confirm the supported client SDK and its token authentication handshake before enabling live updates. Do not copy the token into multiple headers/query parameters on the assumption they are interchangeable. The server emits these events: | Event | Fires when | | ----------------------- | --------------------------------------------------------------- | | `notification_received` | A new message arrives — refresh the feed or prepend the payload | | `unseen_count_changed` | The unseen badge count changes | | `unread_count_changed` | The unread count changes | > Inbox payloads may identify a message as either `_id` or [`messageId`](/api/models/schema-1kescd68ar#response-field-messageid) — accept both. --- URL: https://docs.travila.ai/api/notifications/preferences # Preferences and channel inheritance \{#overview} Global and workflow preferences combine to determine ordinary notification eligibility. Channel names depend on the operation, and critical workflow policy can bypass ordinary preference suppression. ## Preference inheritance and critical workflows \{#preference-policy} | Setting | Effect | | ------------------------------- | --------------------------------------------------------------------------------------------- | | Global channel preference | Applies across notification workflows. | | Per-workflow channel preference | Further restricts that workflow. Ordinary delivery requires both levels to allow the channel. | | `global.enabled: false` | Suppresses non-critical notifications under the preference policy. | | Workflow `critical: true` | Can bypass ordinary preference suppression. | | Explicit optional `false` | Preserves an opt-out where the field or map entry supports explicit presence. | | Missing channel | Can mean unsupported or inherited; do not interpret every omission as an explicit opt-out. | A critical workflow does not guarantee provider delivery or replace recipient authorization and business eligibility. Explain critical-notification policy in the preference UI. ## Preference update semantics \{#preference-updates} | Operation | Update behavior | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Update global preferences | Applies across workflows. Omitted channels retain their current values. | | Update workflow preferences | Requires [`workflowId`](/api/models/schema-p38aqgjs3a#request-field-workflowid); omitted channels retain their values. Use the global operation for global changes. | | Batch workflow preference update | Missing workflow IDs are skipped. Compare [`updatedCount`](/api/notifications/bulk-update-preferences#response-field-updatedcount) with the number of submitted entries. | Send only the settings the user changed; these operations patch preferences rather than replacing the entire set. ## Channel names across operations \{#channel-names} | API context | Channel vocabulary | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Preference toggle keys | [`inApp`](/api/models/schema-oj4cvo85fs#request-field-inapp), [`push`](/api/models/schema-oj4cvo85fs#request-field-push), [`email`](/api/models/schema-oj4cvo85fs#request-field-email), [`sms`](/api/models/schema-oj4cvo85fs#request-field-sms), [`chat`](/api/models/schema-oj4cvo85fs#request-field-chat) | | Registered channels | `CHANNEL_*` enum values | | Activity filters | Provider strings such as `in_app` and `push`; see [activity filter fields](/api/notifications/get-notification-activity#request). | Use the vocabulary defined by each operation. --- URL: https://docs.travila.ai/api/scheduled-jobs/callbacks # Signed callbacks and receiver acknowledgement \{#overview} A scheduler callback carries the configured body and a signed identity token. Receivers verify the claims, bind accepted work to the registered payload and deduplicate retries. ## Callback envelope \{#callback-envelope} The body is exactly the payload you configured — there is no envelope wrapping it. Identity does **not** travel in plaintext headers: there are no `X-Tenant-Id` or `X-Schedule-Id` headers to read. The scheduler's identity and firing claims are inside the signed token. The signature authenticates the token claims. It does not automatically bind the raw HTTP body; validate the payload against the schedule registered in your system before accepting work. ## Signing keys and claim verification \{#signing-keys} | Token or key property | Receiver behavior | | --------------------- | -------------------------------------------------------------------------------- | | Signing algorithm | Require `RS256`. | | `kid` header | Select the matching public key from the deployment's JWKS. | | Key rotation | Refresh the key set as needed; do not pin one key permanently. | | JWKS caching | Honor `Cache-Control: max-age=300` rather than fetching keys for every callback. | Verification uses public keys. The receiver needs no shared secret or private signing key. ## Signed claims \{#claims} Illustrative scheduled callback JWT claims. * `iss`: text https\://api.travila.ai. * `sub`: text \. * `aud`: text your-host.example.com/your/endpoint. * `iat`: number 1754500000. * `exp`: number 1754500300. * `jti`: text sched\:sched\_abc123:1754500000000. * `trigger`: text scheduled. * `schedule_id`: text sched\_abc123. * `tenant_id`: text your-tenant. * `project_id`: text default. | Claim | Check | | -------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `iss` | Must equal `https://api.travila.ai` | | `aud` | Must match the expected [normalized host + path](/api/scheduled-jobs/callbacks#audience) | | `exp` / `iat` | Require both; reject expired tokens, implausible future issuance and lifetimes outside your allowed window | | `jti` | Required non-empty firing identity; deduplicate within verified scope | | `trigger` | `scheduled` for a scheduler dispatch | | `schedule_id` | Required schedule identity; match your registered schedule | | `tenant_id`, `project_id`, `sub` | Required scope and owner; compare with the schedule you accept | An `act.sub` claim appears when the dispatch acts on behalf of another subject. Configure the issuer and JWKS endpoint for the deployment you use. Do not accept an old issuer or alternate hostname merely because it once served the platform. Treat issuer changes as a deliberate trust-configuration migration. ## Audience normalization \{#audience} `aud` is your target URL reduced to **host + path** — no scheme, no query string, and the scheme's default port dropped. A target of `https://api.example.com/hooks/daily-digest` produces: JWT audience illustration. * api.example.com/hooks/daily-digest Verify against the value you expect rather than accepting any audience. This is what stops a token minted for one of your endpoints being replayed against another. ## Retry identity and body binding \{#replay} Retries of one firing reuse `jti = sched::`. The `Idempotency-Key` header is a convenience copy; use the **verified** claim for authority and reject a mismatched header. Bind the acceptance record to the verified issuer, tenant, project, owner, schedule, audience and firing ID, and to a canonical payload digest. Retain it longer than the complete retry/replay window configured for your deployment. A signed token alone does not prove that someone holding it has left the request body unchanged. Compare the body with the schedule configuration saved in your application; the current token does not supply a signed body digest. ## Receiver acknowledgement \{#acknowledgement} | Receiver outcome | Scheduler behavior for that firing | | ------------------------------------------------ | ----------------------------------------------------------------------------------- | | HTTP status below 400 | Records successful delivery; this does not establish completion of downstream work. | | `408`, `425`, `429`, `5xx`, or a network failure | Records failure and retries within the configured attempt limit. | | Other `4xx` | Records failure and stops retrying that firing. | A later scheduled firing remains independent of the previous delivery outcome. Consecutive failures can [auto-pause](/api/scheduled-jobs/schedules#retry-policy) the schedule. Respond promptly after durable acceptance and process slow business work out of band. A delivery acknowledgement records receiver acceptance, not completion of the business action. ## Agent callback verification \{#agent-callback} Scheduled-agent callbacks use the same [signed claims](/api/scheduled-jobs/callbacks#claims), [audience normalization](/api/scheduled-jobs/callbacks#audience) and [firing identity](/api/scheduled-jobs/callbacks#replay) as other scheduled callbacks. | Verification step | Required result | | ---------------------- | -------------------------------------------------------------------------------------------------- | | Verify the token | Trusted deployment issuer, valid signature and acceptable issuance/expiry window. | | Match the registration | Expected audience, tenant, project, owner and schedule. | | Check the payload | Body agrees with the trusted schedule registration; the JWT does not contain a signed body digest. | | Accept once | Atomically store the scoped firing identity and payload digest with a pending work item. | Use [the complete receiver algorithm](/core-platform/scheduling/verifying) before starting the agent. ## Scheduled agent completion \{#agent-outcome} Interpret the generation result using the [canonical conversation outcome contract](/api/conversations/messages-and-runs#generation-interpret-the-outcome). Only a completed result permits consuming its completed output; unsuccessful and nonterminal responses can omit [`messages`](/api/conversations/send-message-sync#response-field-messages). A scheduler delivery acknowledgement does not establish agent completion. ## Result webhook subscription \{#result-webhook} > **Tip: One subscription per endpoint** > > The current platform permits one live subscription per endpoint; a second is rejected with `ALREADY_EXISTS`. Separate endpoints with overlapping filters can receive the same event, so deduplicate shared business effects across those receivers. See [Endpoints and subscriptions](/integrations/webhooks/endpoints) for changes and cutover guidance. --- URL: https://docs.travila.ai/api/scheduled-jobs/schedules # Schedule retries and auto-pause \{#overview} Retry limits govern attempts for one firing; consecutive-failure policy can pause later firings. Read [schedule counters](/api/models/schema-1ld0l8rmvg) and [execution diagnostics](/api/models/schema-1l7vrun3li) on their models. ## Retry policy and auto-pause \{#retry-policy} A retryable firing uses exponential backoff until it succeeds or exhausts its attempt limit. See [receiver acknowledgement](/api/scheduled-jobs/callbacks#acknowledgement) for which HTTP outcomes are retryable. The [retry policy reference](/api/models/schema-1l9ki2op1i) defines the attempt limit and initial and maximum backoff, including their defaults. Count the initial delivery as an attempt when choosing the limit. | [`autoPauseThreshold`](/api/scheduled-jobs/create-job#request-field-autopausethreshold) input | Effect | | --------------------------------------------------------------------------------------------- | ----------------------------------------------- | | Omitted or zero on creation | Selects the default of 10 consecutive failures. | | Zero on update | Leaves the existing threshold unchanged. | | Nonzero override | Must be from 3 through 100. | The current public requests do not expose a working disable setting. Reaching the threshold sets `SCHEDULE_STATUS_PAUSED` and records [`pausedReason`](/api/models/schema-1ld0l8rmvg#response-field-pausedreason). Resume the schedule after its target is healthy. --- URL: https://docs.travila.ai/api/secrets/credentials # Secret values and credential references \{#overview} Secret metadata, secret values and the integrations that reference them have different visibility and recovery requirements. ## Store and reference a credential \{#store-and-reference-a-credential} Use [Create or update a secret](/api/secrets/put-secret) for the accepted name, value and metadata fields. Keep the returned [version](/api/models/schema-1lhjc44i8n#response-field-version) when tracking credential changes. A connection references the secret by [name](/api/models/schema-p1cuh9jgfq#request-field-authsecretref); that reference does not authorize sending the credential to another destination. ## Inspect and list \{#inspect-and-list} Use [Get a secret's metadata](/api/secrets/get-secret-metadata#request) with [`name`](/api/secrets/get-secret-metadata#request-field-name), or [List secrets](/api/secrets/list-secrets#request) with zero-based [`page`](/api/secrets/list-secrets#request-field-page) and [`pageSize`](/api/secrets/list-secrets#request-field-pagesize). The current default page size is 50, with a maximum of 100. Continue through the result's pages to enumerate the project; a single page is not the complete inventory. These operations return metadata without values. ## Remove a credential \{#remove-a-credential} Call [Delete a secret](/api/secrets/delete-secret#request) with [`name`](/api/secrets/delete-secret#request-field-name). If a registered custom MCP server refers to it, the current API refuses ordinary deletion and reports the known references. Change those references first, or deliberately use `force: true` with management authority and accept the affected integrations failing on later resolution. Already-sent requests, external copies and provider revocation remain separate. A failed deletion can leave an incomplete result; do not infer that the old credential is intact. Deleting an already absent secret succeeds with a false [`deleted`](/api/secrets/delete-secret#response-field-deleted) result, which may be omitted from the JSON response. --- URL: https://docs.travila.ai/api/storage/uploads # Upload registration and URL expiry \{#overview} Uploading bytes and registering the resulting object are distinct operations. Quota checks, registration retries and temporary URL expiry have separate effects. ## Upload acceptance and registration retries \{#files-pre-signed-upload-large-files} The size check uses currently reported quota and does not reserve storage for this upload. If the request is rejected for quota, let the customer remove unneeded files before trying again; see [making room for another attachment](/core-platform/files-data/managing#quota). Several parallel uploads can consume the remaining space. Show upload progress in your application, then check that the transfer succeeded. The size-range header permits anything from zero bytes to the declared maximum; it does not confirm that the complete intended recording arrived. Keep the URL private: it can permit another upload until it expires. If registration's response is lost, retry registration for the same uploaded file. It returns the existing registration with an omitted/default [`registered`](/api/storage/register-uploaded-file#response-field-registered) flag when the file was already registered. Do not start another upload just because the registration response did not arrive. ## File references and expiry \{#files-file-references-and-expiry} Upload and single-file download URLs default to one hour when expiry is omitted; batch download URLs default to 24 hours. Choose an expiry suitable for the current interaction rather than storing those links in your support-request record. --- URL: https://docs.travila.ai/api/tools/selection # MCP server selection \{#overview} Discovery exposes available servers and tool schemas. The effective conversation, profile or per-send selection determines which servers a generation can use. ## Platform servers \{#platform-servers} The next turn uses the configured server selection when it is the effective list. An active [agent profile replaces conversation settings](/api/tools/selection#configuration-mcp-server-selection), so put the server on that profile when your application uses one. To expose only selected discovered tools, add [`allowlistToolPatterns`](/api/models/schema-1hik90rmo1#request-field-allowlisttoolpatterns) using their discovered names. A blocklist takes precedence over the allowlist. Keep one reference per server; duplicate references do not combine their filters. ## Per turn servers \{#per-turn-servers} The next normal turn inherits its configuration again. An empty override currently inherits too; it does not clear tools. Queued turns currently lose their overrides when later dequeued, so do not depend on this mechanism to restrict queued work. Tool selection does not establish a separate authorization ceiling; only trusted callers should choose it. ## MCP server selection \{#configuration-mcp-server-selection} [Updating conversation settings](/api/conversations/update-settings) replaces the whole settings object. Read its current value and preserve unrelated settings when changing server selection. [`mcpServers`](/api/models/schema-ph6avse89k#request-field-mcpservers) on conversation settings is the base set of MCP servers. Three tiers resolve in order, with each tier **replacing** the one below: 1. **Per-send override** ([`overrideMcpServers`](/api/conversations/send-message#request-field-overridemcpservers) on the send request) — applies only to that send. 2. **Active profile** ([`profile.mcpServers`](/api/models/schema-1hmbcecg1j#request-field-mcpservers)) — replaces conversation-level servers while the profile is active; an empty list means no servers. 3. **Conversation settings** ([`settings.mcpServers`](/api/models/schema-ph6avse89k#request-field-mcpservers)) — the baseline. No server is attached unless one of these tiers names it — including the platform's own catalog (`built-in:tavily`, `built-in:firecrawl`, …). See [Platform-provided servers](/api/tools/selection#platform-servers). Each server reference carries [`allowlistToolPatterns`](/api/models/schema-1hik90rmo1#request-field-allowlisttoolpatterns) and [`blocklistToolPatterns`](/api/models/schema-1hik90rmo1#request-field-blocklisttoolpatterns) — glob patterns enforced at call time to control which of that server's tools the model may use. --- # Glossary {#glossary} URL: https://docs.travila.ai/glossary ## Terms {#terms} ### Agent profile A reusable persona with model configuration, tools and metadata describing when it should be used. [Read the canonical explanation](/api/models/schema-1hmbcecg1j). ### Allocation A modeled share of compute, storage, idle capacity or shared services assigned to a project or customer; it answers a different question from provider-reported usage, an estimate or a customer charge. [Read the canonical explanation](/insights/usage-cost). ### Annotation queue A named work queue assigning score configurations to human annotation items. [Read the canonical explanation](/api/models/schema-1j9496mkdg). ### Callback The request a scheduled job’s firing sends to its receiver: the configured body plus a signed identity token whose signature does not bind that body, so the receiver validates the payload against the registered schedule and acknowledges only after durable acceptance. [Read the canonical explanation](/api/scheduled-jobs/callbacks). ### Client tool result The result the caller submits for a tool call executed on the client side. [Read the canonical explanation](/api/models/schema-1i4kndhs46). ### Compaction The recorded reduction of a conversation’s retained context, described by compaction metadata. [Read the canonical explanation](/api/models/schema-1fpqunnq41). ### Connected account An external user’s OAuth connection to an app. [Read the canonical explanation](/api/models/schema-1fd4ce3lnc). ### Conversation history The stored messages of a conversation, from which the context management strategy selects or summarizes what the model sees. [Read the canonical explanation](/api/models/schema-1hgrvsu34j). ### Conversation state The bounded read of a conversation used to retrieve a reply after an asynchronous send; it cannot correlate every queued or concurrent operation. [Read the canonical explanation](/managed-agents/conversations/generation#async-generation). ### Conversation thread The registry record for one conversation, kept so a user’s threads can be listed and managed together. [Read the canonical explanation](/api/models/schema-1i84dsgmg6). ### Dataset An evaluation dataset: its metadata, item counts, run history and input/output schemas. [Read the canonical explanation](/api/models/schema-1ja63aqvqo). ### Dataset item One evaluation input with its expected output and source trace references. [Read the canonical explanation](/api/models/schema-1jcdgbb5sm). ### Dataset run One execution of an evaluation dataset. [Read the canonical explanation](/api/models/schema-1jehhpchdc). ### Delivery attempt One try by the delivery backend to deliver a webhook event to an endpoint, recorded with its status and response on the event delivery. [Read the canonical explanation](/api/models/schema-1fiv947q56). ### Durable acceptance A callback receiver’s acknowledgement of a scheduler firing only after it has stored one durable work item; return 2xx only after durable acceptance. [Read the canonical explanation](/core-platform/scheduling/verifying). ### Durable work item The single stored record a callback receiver creates from a scheduler firing; repeated identical deliveries produce one, and a worker completes the business action from it. [Read the canonical explanation](/core-platform/scheduling/verifying). ### End user A tenant’s end user: captured identity claims and editable profile values, named on backend requests by the X-On-Behalf-Of header. [Read the canonical explanation](/api/models/schema-1l1et4gp2i). ### Event delivery The delivery-attempt state and response information for one webhook event. [Read the canonical explanation](/api/models/schema-1fiv947q56). ### Event provenance The event context in a signed webhook body: the event name, id and routing metadata that identify where an emitted event came from. [Read the canonical explanation](/integrations/webhooks/endpoints). ### Event type The named kind of webhook event; the event name inside the signed body is the authoritative one, not a routing header. [Read the canonical explanation](/integrations/webhooks/endpoints). ### Execution A single firing record for a scheduled job. [Read the canonical explanation](/api/models/schema-1l7vrun3li). ### Experiment context Dataset-run attribution attached when a scripted evaluation turn is sent. [Read the canonical explanation](/api/models/schema-1icbr3lltu). ### File A stored object described by its file metadata and organised in folders. [Read the canonical explanation](/api/models/schema-1lls6fo8p7). ### Generation config The canonical generation configuration applied to a request. [Read the canonical explanation](/api/models/schema-1h82h7ri5p). ### In flight Accepted work that has started and not completed; a dispatch already admitted or in flight can still complete, and pausing it is not remote-effect cancellation. [Read the canonical explanation](/api/scheduled-jobs/pause-job). ### Inbox acknowledgment A user’s acknowledgement of an inbox message; it neither performs nor rolls back the business operation. [Read the canonical explanation](/core-platform/notifications/inbox). ### Inbox message Notification content and interaction state displayed in a subscriber’s inbox. [Read the canonical explanation](/api/models/schema-1kescd68ar). ### MCP connection The connection a registered custom MCP server is invoked over; refer to the MCP server itself. [Read the canonical explanation](/integrations/tools-connections/custom-mcp-servers). Deprecated; use **MCP server**. ### MCP server A Model Context Protocol server an agent connects to for its available tools; a custom server is one the tenant registered and is invoked with the tenant’s credentials. [Read the canonical explanation](/api/models/schema-1ipatl4liq). ### Memory A stored statement associated with a user and, when recorded, an agent or conversation and a run or session. [Read the canonical explanation](/api/models/schema-1k63a85bkp). ### Memory extraction The pipeline that runs after a generation, derives new memory facts from the run’s messages and updates existing ones. [Read the canonical explanation](/api/memory/lifecycle). ### Memory relation A directed edge from a source entity to a destination entity, labelled by an open relationship string. [Read the canonical explanation](/api/models/schema-1k84aa8jbi). ### Memory retrieval The search that supplies stored memories to a generation from the query text submitted for it. [Read the canonical explanation](/api/models/schema-1igd5iut01). ### Message A chat message in a conversation thread, sent by the user or generated by the assistant. [Read the canonical explanation](/api/models/schema-1j3dcf7kvu). ### Message feedback One user’s feedback on an assistant-generated message. [Read the canonical explanation](/api/models/schema-1iroqctqt1). ### Model catalog The catalog metadata that filters candidate models, including price, through catalog-price filters, and the context window. [Read the canonical explanation](/managed-agents/model-controls/filtering). ### Model routing The selection of the model and provider that serve a request: explicit model ids must pass platform validation, metadata filters narrow the eligible candidates, and provider availability and run outcomes decide whether generation succeeds. [Read the canonical explanation](/api/model-controls/routing). ### Model routing filter Metadata-based criteria for filtering the model candidates eligible for a request. [Read the canonical explanation](/api/models/schema-1ga4tjqqg1). ### Notification channel One channel registered for notification delivery, with its registration state and credential count. [Read the canonical explanation](/api/models/schema-1kaqut27uf). ### Observation A timed evaluation span or generation record with model usage, inputs, outputs and scores. [Read the canonical explanation](/api/models/schema-1ju9tclufp). ### On-behalf-of user The end user a backend call made with a secret key acts for, identified by a request header; the key must carry the users:impersonate scope. [Read the canonical explanation](/core-platform/identity-access/scopes-permissions#the-usersimpersonate-scope-and-x-on-behalf-of). ### Profile version pin A nonzero profile version that keeps the selected profile content fixed; fragments still resolve from the latest fragment set even when the profile is pinned. [Read the canonical explanation](/api/agent-profiles/selection-and-versioning). ### Project The scope an application’s resources and keys belong to; the current public API uses the legacy default project. [Read the canonical explanation](/core-platform/workspaces-projects). ### Prompt cache The input-side cache of prompt tokens; tokens served from it are reported in the usage breakdown of prompt tokens. [Read the canonical explanation](/api/models/schema-1ivj82m55o). ### Prompt fragment Project-scoped reusable prompt-template text that profiles and other fragments include. [Read the canonical explanation](/api/models/schema-1j5dvgfmr9). ### Provider One of the model providers eligible for a request; provider preferences restrict and order them. [Read the canonical explanation](/api/models/schema-1gg690bhqh). ### Provider preferences Routing preferences that restrict and order the model providers eligible for a request. [Read the canonical explanation](/api/models/schema-1gg690bhqh). ### Publishable key A key configured for an accepted identity provider that lets a browser or mobile app call Travila directly with the signed-in user’s token, so the secret key never ships to the client. [Read the canonical explanation](/core-platform/identity-access/authentication#2-client-app-with-a-publishable-key). ### Queued send A send accepted behind an in-flight run; an accepted or queued response is not a completed reply, and the conversation can be idle without a correlated outcome for it. [Read the canonical explanation](/api/conversations/messages-and-runs). ### Recipient The person a notification is sent to; the requesting person must be permitted to notify that recipient, and an accepted token or supplied user id alone is not that permission. [Read the canonical explanation](/core-platform/notifications/sending). ### Replay A repeated delivery of the same scheduler firing; the receiver compares the firing identity and the payload binding before accepting it. [Read the canonical explanation](/api/scheduled-jobs/callbacks#replay). ### Response format The structured response control that constrains the shape of the model’s output. [Read the canonical explanation](/api/models/schema-1g69v4vltg). ### Response schema The JSON schema a response format sets; when set, server validation of the model’s output defaults to enabled, with one validation retry unless configured otherwise. [Read the canonical explanation](/api/models/schema-1g69v4vltg). ### Retention Configurable retention of stored data is planned and not yet available. [Read the canonical explanation](/core-platform/governance-privacy). ### Run One accepted generation of a reply to a sent message; retaining the accepted run lets a disconnected client recover the reply without sending the question again. [Read the canonical explanation](/managed-agents/conversations/generation). ### Sampled coverage The share of a fixed dataset’s eligible cases that were evaluated; not the proportion of every turn reviewed. [Read the canonical explanation](/api/evals/get-overview). ### Schedule The canonical representation of a scheduled job. [Read the canonical explanation](/api/models/schema-1ld0l8rmvg). ### Scope A label attached to an API key; where an operation enforces its scope, a missing grant returns 403 insufficient_scope. [Read the canonical explanation](/core-platform/identity-access/scopes-permissions). ### Score An evaluation score with its value, source, target identity and generation attribution. [Read the canonical explanation](/api/models/schema-1jm5lo00e7). ### Score config A score definition specifying its value type, bounds and allowed categories. [Read the canonical explanation](/api/models/schema-1k2h0fdd77). ### Secret A stored value scoped to one tenant and project, referenced by the resources that use it; read APIs return only its metadata. [Read the canonical explanation](/api/models/schema-1lhjc44i8n). ### Secret key A backend API key (sk_*) that identifies the tenant and stays on the server; with the users:impersonate scope it acts for the user named in X-On-Behalf-Of. [Read the canonical explanation](/core-platform/identity-access/scopes-permissions#the-usersimpersonate-scope-and-x-on-behalf-of). ### Self-hosted An installation of Travila your own team installs and operates, as opposed to a Travila-managed dedicated single-tenant deployment; not an Enterprise-only entitlement. [Read the canonical explanation](/enterprise/deployment-operations). ### Storage The file store behind the Storage APIs: Travila provides file storage, metadata and temporary upload and download URLs for objects your application owns. [Read the canonical explanation](/core-platform/files-data/files). ### Subscriber The recipient of notifications, described by the contact, locale and custom attributes delivery uses. [Read the canonical explanation](/api/models/schema-1kgdnn5p53). ### Tool A canonical tool or function definition, shared across all services, that the model can call. [Read the canonical explanation](/api/models/schema-1gomaj79cc). ### Tool approval The approval decision recorded for a specific tool call. [Read the canonical explanation](/api/models/schema-1j7jbpfsda). ### Tool call A single structured call to a tool emitted by the model during a run. [Read the canonical explanation](/api/models/schema-1it6mqsqoo). ### Tool execution policy Per-run policy for tool approvals, MCP execution concurrency and the admitted tool-call budget. [Read the canonical explanation](/api/models/schema-1h2ji21uc4). ### Trace The evaluation record of one conversation turn, including its recorded conversation and message. [Read the canonical explanation](/api/models/schema-1k4mjul65u). ### Turn One position within an agentic generation run, counted against the run’s configured maximum. [Read the canonical explanation](/api/models/schema-1ilcikuhu8). ### Usage Usage accounting for a generation: the tokens it consumed and the cost attributed to it. [Read the canonical explanation](/api/models/schema-1j1vov2uoh). ### Voice session A Daily/Pipecat voice session and its session metadata. [Read the canonical explanation](/api/models/schema-1ktuo6mcah). ### Webhook endpoint The provider record describing a webhook delivery destination and its delivery settings. [Read the canonical explanation](/api/models/schema-1ffl20kv2k). ### Webhook subscription The webhook event selection and retry settings associated with an endpoint. [Read the canonical explanation](/api/models/schema-1fn66l17fv). ### Workspace In the upcoming project model, not yet available, the container for your company, with a project per application; today the public API uses the legacy default project. [Read the canonical explanation](/core-platform/workspaces-projects). --- # Built-in tools URL: https://docs.travila.ai/integrations/builtin-tools * [Exa](/integrations/builtin-tools/erp-r7ui79mvkn) * [Firecrawl](/integrations/builtin-tools/erp-c5om7qc2en) * [Tavily](/integrations/builtin-tools/erp-c5ouf2icf8) --- # Exa URL: https://docs.travila.ai/integrations/builtin-tools/erp-r7ui79mvkn Search the web and retrieve page content using Exa through MCP. This catalog entry is **Proposed**; it does not establish that Exa is enabled in your deployment. Ask your deployment operator to confirm availability and configure the operational credential. When enabled, use [available-server discovery](/api/conversations/mcp-list-available-servers) to obtain the actual server reference, then select that reference in the conversation’s MCP server configuration and inspect its available tools. Do not derive a selectable server ID from this page’s title or vendor endpoint. [Documentation](https://exa.ai/docs/get-started/exa-mcp) ## Company Exa Labs, Inc. Exa provides web search and retrieval services for AI applications. [Website](https://exa.ai/) ## Product Exa Web search and content retrieval for AI applications, available through an API and a hosted MCP server. [Website](https://exa.ai/) ## Terms Exa Labs Terms of Service Exa’s service terms apply to its product and hosted MCP integration. Check the terms and plan that apply to your Exa account before connecting it. Terms published by Exa Labs, Inc. for its services. Document type: Terms of Service [Terms source](https://exa.ai/assets/Exa_Labs_Terms_of_Service.pdf) --- # Firecrawl URL: https://docs.travila.ai/integrations/builtin-tools/erp-c5om7qc2en Search the web and retrieve content from pages and sites through Firecrawl’s MCP tools. [Documentation](https://docs.firecrawl.dev/mcp-server) ## Company SideGuide Technologies, Inc. Operates Firecrawl, a web-data API for AI applications. [Website](https://www.firecrawl.dev/) ## Product Firecrawl Web-data API with search, scrape, crawl and browser-interaction capabilities for AI applications. [Website](https://www.firecrawl.dev/) ## Terms Firecrawl Terms of Use Firecrawl’s service agreement governs use of its web-data services and APIs. Refer to the agreement and the terms applicable to the account used for the service. Service terms published by SideGuide Technologies, Inc. d/b/a Firecrawl. Document type: Terms of Service Source version: Last revised 2026-10-07 [Terms source](https://www.firecrawl.dev/terms-of-service) --- # Tavily URL: https://docs.travila.ai/integrations/builtin-tools/erp-c5ouf2icf8 Search the web, extract page content, and explore sites through Tavily’s MCP tools. [Documentation](https://docs.tavily.com/documentation/mcp) ## Company AlphaAI Technologies Inc. dba Tavily Provides Tavily web-access APIs for AI applications. [Website](https://tavily.com/) ## Product Tavily Web-access API offering search, extraction, crawling, mapping and research endpoints for AI applications. [Website](https://tavily.com/) ## Terms Tavily Platform Terms of Service Tavily’s platform terms cover its services and APIs. A separate written agreement may govern an account’s use of the service. Platform service terms published by AlphaAI Technologies Inc. dba Tavily. Document type: Terms of Service Source version: Last updated 2026-05-04 [Terms source](https://www.tavily.com/terms) --- # Available models URL: https://docs.travila.ai/available-models Compare model capabilities and limits. Select a model for details about supported features and availability. | Model | Provider | Input | Output | Context | Tool calling | New selection | | ---------------------------------------------------------------------------------------- | --------- | ------------------------------- | ----------- | -------------- | ------------ | ------------- | | [Anthropic: Claude Opus 5.5](/available-models/jtk6r1n115) | anthropic | text, image, file | text | 1000000 tokens | Supported | Open | | [Anthropic: Claude Sonnet 4.6](/available-models/jts0kostgs) | anthropic | text, image, file | text | 1000000 tokens | Supported | Open | | [Anthropic: Claude Sonnet 5](/available-models/ju37hpafns) | anthropic | text, image, file | text | 1000000 tokens | Supported | Open | | [Anthropic: Claude Sonnet 5.5](/available-models/juakmtliue) | anthropic | text, image, file | text | 1000000 tokens | Supported | Open | | [DeepSeek: DeepSeek V3](/available-models/juhqecmnpn) | deepseek | text | text | 163840 tokens | Supported | Open | | [DeepSeek: DeepSeek V3 0324](/available-models/junp37gqdq) | deepseek | text | text | 163840 tokens | Supported | Open | | [DeepSeek: DeepSeek V3.1](/available-models/juub571p85) | deepseek | text | text | 163840 tokens | Supported | Open | | [DeepSeek: R1 0528](/available-models/jvcfsobspe) | deepseek | text | text | 163840 tokens | Supported | Open | | [DeepSeek: DeepSeek V3.1 Terminus](/available-models/jvqcod85uh) | deepseek | text | text | 163840 tokens | Supported | Open | | [DeepSeek: DeepSeek V3.2](/available-models/k00185s0u7) | deepseek | text | text | 163840 tokens | Supported | Open | | [DeepSeek: DeepSeek V3.2 Exp](/available-models/k07vhc0i0q) | deepseek | text | text | 163840 tokens | Supported | Open | | [DeepSeek: DeepSeek V4 Flash 0423](/available-models/k0fiit2mo0) | deepseek | text | text | 1048576 tokens | Supported | Open | | [DeepSeek: DeepSeek V4 Flash 0731](/available-models/k0mmkq2rj9) | deepseek | text | text | 1048576 tokens | Supported | Open | | [DeepSeek: DeepSeek V4 Flash Vision Exp](/available-models/k0td6kk2qo) | deepseek | text, image | text | 1048576 tokens | Supported | Open | | [DeepSeek: DeepSeek V4 Pro 0423](/available-models/k14rthieem) | deepseek | text | text | 1048576 tokens | Supported | Open | | [DeepSeek: DeepSeek V4 Pro 0813](/available-models/k1cssm4kga) | deepseek | text | text | 1048576 tokens | Supported | Open | | [DeepSeek: DeepSeek V4.1 Flash](/available-models/k1jou08lh8) | deepseek | text, image | text | 1048576 tokens | Supported | Open | | [DeepSeek: DeepSeek V4.1 Flash 1017](/available-models/k1q147n2dm) | deepseek | text, image | text | 1048576 tokens | Supported | Open | | [Google: Gemini 3 Flash Preview](/available-models/k211qsoh1n) | google | text, image, file, audio, video | text | 1048576 tokens | Supported | Open | | [Google: Nano Banana Pro (Gemini 3 Pro Image)](/available-models/k27b256g6q) | google | image, text | image, text | 131072 tokens | Supported | Open | | [Google: Nano Banana Pro (Gemini 3 Pro Image Preview)](/available-models/k2fu84p3jk) | google | image, text | image, text | 65536 tokens | Unknown | Open | | [Google: Nano Banana 2 (Gemini 3.1 Flash Image)](/available-models/k2mjvos8bj) | google | image, text | image, text | 131072 tokens | Unknown | Open | | [Google: Nano Banana 2 (Gemini 3.1 Flash Image Preview)](/available-models/k2tb76gheh) | google | image, text | image, text | 65536 tokens | Unknown | Open | | [Google: Gemini 3.1 Flash Lite](/available-models/k34atgh6gp) | google | text, image, video, file, audio | text | 1048576 tokens | Supported | Open | | [Google: Nano Banana 2 Lite (Gemini 3.1 Flash Lite Image)](/available-models/k3b2cl17g6) | google | image, text | image, text | 65536 tokens | Unknown | Open | | [Google: Gemini 3.1 Flash Lite Preview](/available-models/k3ibfctimp) | google | text, image, video, file, audio | text | 1048576 tokens | Supported | Open | | [Google: Gemini 3.1 Pro Preview](/available-models/k3phledrha) | google | audio, file, image, text, video | text | 1048576 tokens | Supported | Open | | [Google: Gemini 3.1 Pro Preview Custom Tools](/available-models/k408a90ikp) | google | text, audio, image, video, file | text | 1048576 tokens | Supported | Open | | [Google: Gemini 3.5 Flash](/available-models/k46uvf2jrp) | google | text, image, video, file, audio | text | 1048576 tokens | Supported | Open | | [Google: Gemini 3.5 Flash Lite](/available-models/k4d15vqqfv) | google | text, image, video, file, audio | text | 1048576 tokens | Supported | Open | | [Google: Gemini 3.6 Flash](/available-models/k4kcg4p1bt) | google | text, image, video, file, audio | text | 1048576 tokens | Supported | Open | | [Google: Gemini 3.7 Flash](/available-models/k4r52ukm02) | google | text, image, video, file, audio | text | 1048576 tokens | Supported | Open | | [Google: Gemini 3.8 Flash](/available-models/k52a5h4rgq) | google | text, image, video, file, audio | text | 1048576 tokens | Supported | Open | | [Google: Gemini 4 Argon](/available-models/k59qhvqbqr) | google | audio, file, image, text, video | text | 1048576 tokens | Supported | Open | | [Google: Nano Banana 2.1](/available-models/k5f6ekssie) | google | image, text | image, text | 65536 tokens | Supported | Open | | [OpenAI: GPT-6 Luna](/available-models/k5mp9bsvte) | openai | file, image, text | text | 1050000 tokens | Supported | Open | | [OpenAI: GPT-6 Luna Pro](/available-models/k5to19esns) | openai | file, image, text | text | 1050000 tokens | Supported | Open | | [OpenAI: GPT-6 Sol](/available-models/k640qt583j) | openai | file, image, text | text | 1050000 tokens | Supported | Open | | [OpenAI: GPT-6 Sol Pro](/available-models/k6b1mjms2f) | openai | file, image, text | text | 1050000 tokens | Supported | Open | | [Z.ai: GLM 4.5](/available-models/k6h6pa4i4h) | z-ai | text | text | 131072 tokens | Supported | Open | | [Z.ai: GLM 4.5 Air](/available-models/k6oajdmpr9) | z-ai | text | text | 131072 tokens | Supported | Open | | [Z.ai: GLM 4.5V](/available-models/k6vsaf7t2n) | z-ai | text, image | text | 65536 tokens | Supported | Open | | [Z.ai: GLM 4.6](/available-models/k768higa0q) | z-ai | text | text | 204800 tokens | Supported | Open | | [Z.ai: GLM 4.6V](/available-models/k7e8k0msbb) | z-ai | image, text, video | text | 131072 tokens | Supported | Open | | [Z.ai: GLM 4.7](/available-models/k7l3oqoh4l) | z-ai | text | text | 204800 tokens | Supported | Open | | [Z.ai: GLM 4.7 Flash](/available-models/k7sgao29k2) | z-ai | text | text | 200000 tokens | Supported | Open | | [Z.ai: GLM 5](/available-models/k83o5o1ish) | z-ai | text | text | 204800 tokens | Supported | Open | | [Z.ai: GLM 5 Turbo](/available-models/k8a294hp8p) | z-ai | text | text | 202752 tokens | Supported | Open | | [Z.ai: GLM 5.1](/available-models/k8hb5npdj9) | z-ai | text | text | 204800 tokens | Supported | Open | | [Z.ai: GLM 5.2](/available-models/k8o0gem1u3) | z-ai | text | text | 1048576 tokens | Supported | Open | | [Z.ai: GLM 5.3](/available-models/k8vbuq4jtr) | z-ai | text | text | 1048576 tokens | Supported | Open | | [Z.ai: GLM 5.3 Flash](/available-models/k95dacnqeg) | z-ai | text, image, video | text | 1048576 tokens | Supported | Open | | [Z.ai: GLM 5.3 FlashX](/available-models/k9cltmusva) | z-ai | text, image, video | text | 1048576 tokens | Supported | Open | | [Z.ai: GLM 5.3 Prime](/available-models/k9j634hu8o) | z-ai | text | text | 1000000 tokens | Supported | Open | | [Z.ai: GLM 5V Turbo](/available-models/k9qrqgk2i0) | z-ai | image, text, video | text | 202752 tokens | Supported | Open | | [OpenAI gpt-oss-20b](/available-models/otig24dkkq) | OpenAI | text | text | 131072 tokens | Supported | Open | --- # Anthropic: Claude Opus 5.5 \{#overview} URL: https://docs.travila.ai/available-models/jtk6r1n115 anthropic — anthropic/claude-opus-5.5 Input modalities: Reported — text, image, file Output modalities: Reported — text Context: 1000000 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Anthropic: Claude Sonnet 4.6 \{#overview} URL: https://docs.travila.ai/available-models/jts0kostgs anthropic — anthropic/claude-sonnet-4.6 Input modalities: Reported — text, image, file Output modalities: Reported — text Context: 1000000 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Anthropic: Claude Sonnet 5 \{#overview} URL: https://docs.travila.ai/available-models/ju37hpafns anthropic — anthropic/claude-sonnet-5 Input modalities: Reported — text, image, file Output modalities: Reported — text Context: 1000000 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Anthropic: Claude Sonnet 5.5 \{#overview} URL: https://docs.travila.ai/available-models/juakmtliue anthropic — anthropic/claude-sonnet-5.5 Input modalities: Reported — text, image, file Output modalities: Reported — text Context: 1000000 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # DeepSeek: DeepSeek V3 \{#overview} URL: https://docs.travila.ai/available-models/juhqecmnpn deepseek — deepseek/deepseek-chat Input modalities: Reported — text Output modalities: Reported — text Context: 163840 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Unknown Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # DeepSeek: DeepSeek V3 0324 \{#overview} URL: https://docs.travila.ai/available-models/junp37gqdq deepseek — deepseek/deepseek-chat-v3-0324 Input modalities: Reported — text Output modalities: Reported — text Context: 163840 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Unknown Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # DeepSeek: DeepSeek V3.1 \{#overview} URL: https://docs.travila.ai/available-models/juub571p85 deepseek — deepseek/deepseek-chat-v3.1 Input modalities: Reported — text Output modalities: Reported — text Context: 163840 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # DeepSeek: R1 0528 \{#overview} URL: https://docs.travila.ai/available-models/jvcfsobspe deepseek — deepseek/deepseek-r1-0528 Input modalities: Reported — text Output modalities: Reported — text Context: 163840 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # DeepSeek: DeepSeek V3.1 Terminus \{#overview} URL: https://docs.travila.ai/available-models/jvqcod85uh deepseek — deepseek/deepseek-v3.1-terminus Input modalities: Reported — text Output modalities: Reported — text Context: 163840 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # DeepSeek: DeepSeek V3.2 \{#overview} URL: https://docs.travila.ai/available-models/k00185s0u7 deepseek — deepseek/deepseek-v3.2 Input modalities: Reported — text Output modalities: Reported — text Context: 163840 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # DeepSeek: DeepSeek V3.2 Exp \{#overview} URL: https://docs.travila.ai/available-models/k07vhc0i0q deepseek — deepseek/deepseek-v3.2-exp Input modalities: Reported — text Output modalities: Reported — text Context: 163840 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # DeepSeek: DeepSeek V4 Flash 0423 \{#overview} URL: https://docs.travila.ai/available-models/k0fiit2mo0 deepseek — deepseek/deepseek-v4-flash Input modalities: Reported — text Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # DeepSeek: DeepSeek V4 Flash 0731 \{#overview} URL: https://docs.travila.ai/available-models/k0mmkq2rj9 deepseek — deepseek/deepseek-v4-flash-0731 Input modalities: Reported — text Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # DeepSeek: DeepSeek V4 Flash Vision Exp \{#overview} URL: https://docs.travila.ai/available-models/k0td6kk2qo deepseek — deepseek/deepseek-v4-flash-vision-exp Input modalities: Reported — text, image Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # DeepSeek: DeepSeek V4 Pro 0423 \{#overview} URL: https://docs.travila.ai/available-models/k14rthieem deepseek — deepseek/deepseek-v4-pro Input modalities: Reported — text Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # DeepSeek: DeepSeek V4 Pro 0813 \{#overview} URL: https://docs.travila.ai/available-models/k1cssm4kga deepseek — deepseek/deepseek-v4-pro-0813 Input modalities: Reported — text Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # DeepSeek: DeepSeek V4.1 Flash \{#overview} URL: https://docs.travila.ai/available-models/k1jou08lh8 deepseek — deepseek/deepseek-v4.1-flash Input modalities: Reported — text, image Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # DeepSeek: DeepSeek V4.1 Flash 1017 \{#overview} URL: https://docs.travila.ai/available-models/k1q147n2dm deepseek — deepseek/deepseek-v4.1-flash-1017 Input modalities: Reported — text, image Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Google: Gemini 3 Flash Preview \{#overview} URL: https://docs.travila.ai/available-models/k211qsoh1n google — google/gemini-3-flash-preview Input modalities: Reported — text, image, file, audio, video Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Google: Nano Banana Pro (Gemini 3 Pro Image) \{#overview} URL: https://docs.travila.ai/available-models/k27b256g6q google — google/gemini-3-pro-image Input modalities: Reported — image, text Output modalities: Reported — image, text Context: 131072 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Google: Nano Banana Pro (Gemini 3 Pro Image Preview) \{#overview} URL: https://docs.travila.ai/available-models/k2fu84p3jk google — google/gemini-3-pro-image-preview Input modalities: Reported — image, text Output modalities: Reported — image, text Context: 65536 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Unknown Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Google: Nano Banana 2 (Gemini 3.1 Flash Image) \{#overview} URL: https://docs.travila.ai/available-models/k2mjvos8bj google — google/gemini-3.1-flash-image Input modalities: Reported — image, text Output modalities: Reported — image, text Context: 131072 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Unknown Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Google: Nano Banana 2 (Gemini 3.1 Flash Image Preview) \{#overview} URL: https://docs.travila.ai/available-models/k2tb76gheh google — google/gemini-3.1-flash-image-preview Input modalities: Reported — image, text Output modalities: Reported — image, text Context: 65536 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Unknown Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Google: Gemini 3.1 Flash Lite \{#overview} URL: https://docs.travila.ai/available-models/k34atgh6gp google — google/gemini-3.1-flash-lite Input modalities: Reported — text, image, video, file, audio Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Google: Nano Banana 2 Lite (Gemini 3.1 Flash Lite Image) \{#overview} URL: https://docs.travila.ai/available-models/k3b2cl17g6 google — google/gemini-3.1-flash-lite-image Input modalities: Reported — image, text Output modalities: Reported — image, text Context: 65536 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Unknown Structured output: Unknown Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Google: Gemini 3.1 Flash Lite Preview \{#overview} URL: https://docs.travila.ai/available-models/k3ibfctimp google — google/gemini-3.1-flash-lite-preview Input modalities: Reported — text, image, video, file, audio Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Google: Gemini 3.1 Pro Preview \{#overview} URL: https://docs.travila.ai/available-models/k3phledrha google — google/gemini-3.1-pro-preview Input modalities: Reported — audio, file, image, text, video Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Google: Gemini 3.1 Pro Preview Custom Tools \{#overview} URL: https://docs.travila.ai/available-models/k408a90ikp google — google/gemini-3.1-pro-preview-customtools Input modalities: Reported — text, audio, image, video, file Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Google: Gemini 3.5 Flash \{#overview} URL: https://docs.travila.ai/available-models/k46uvf2jrp google — google/gemini-3.5-flash Input modalities: Reported — text, image, video, file, audio Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Google: Gemini 3.5 Flash Lite \{#overview} URL: https://docs.travila.ai/available-models/k4d15vqqfv google — google/gemini-3.5-flash-lite Input modalities: Reported — text, image, video, file, audio Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Google: Gemini 3.6 Flash \{#overview} URL: https://docs.travila.ai/available-models/k4kcg4p1bt google — google/gemini-3.6-flash Input modalities: Reported — text, image, video, file, audio Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Google: Gemini 3.7 Flash \{#overview} URL: https://docs.travila.ai/available-models/k4r52ukm02 google — google/gemini-3.7-flash Input modalities: Reported — text, image, video, file, audio Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Google: Gemini 3.8 Flash \{#overview} URL: https://docs.travila.ai/available-models/k52a5h4rgq google — google/gemini-3.8-flash Input modalities: Reported — text, image, video, file, audio Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Google: Gemini 4 Argon \{#overview} URL: https://docs.travila.ai/available-models/k59qhvqbqr google — google/gemini-4-argon Input modalities: Reported — audio, file, image, text, video Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Google: Nano Banana 2.1 \{#overview} URL: https://docs.travila.ai/available-models/k5f6ekssie google — google/gemini-nano-banana-2.1 Input modalities: Reported — image, text Output modalities: Reported — image, text Context: 65536 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # OpenAI: GPT-6 Luna \{#overview} URL: https://docs.travila.ai/available-models/k5mp9bsvte openai — openai/gpt-6-luna Input modalities: Reported — file, image, text Output modalities: Reported — text Context: 1050000 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # OpenAI: GPT-6 Luna Pro \{#overview} URL: https://docs.travila.ai/available-models/k5to19esns openai — openai/gpt-6-luna-pro Input modalities: Reported — file, image, text Output modalities: Reported — text Context: 1050000 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # OpenAI: GPT-6 Sol \{#overview} URL: https://docs.travila.ai/available-models/k640qt583j openai — openai/gpt-6-sol Input modalities: Reported — file, image, text Output modalities: Reported — text Context: 1050000 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # OpenAI: GPT-6 Sol Pro \{#overview} URL: https://docs.travila.ai/available-models/k6b1mjms2f openai — openai/gpt-6-sol-pro Input modalities: Reported — file, image, text Output modalities: Reported — text Context: 1050000 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Z.ai: GLM 4.5 \{#overview} URL: https://docs.travila.ai/available-models/k6h6pa4i4h z-ai — z-ai/glm-4.5 Input modalities: Reported — text Output modalities: Reported — text Context: 131072 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Unknown Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Z.ai: GLM 4.5 Air \{#overview} URL: https://docs.travila.ai/available-models/k6oajdmpr9 z-ai — z-ai/glm-4.5-air Input modalities: Reported — text Output modalities: Reported — text Context: 131072 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Unknown Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Z.ai: GLM 4.5V \{#overview} URL: https://docs.travila.ai/available-models/k6vsaf7t2n z-ai — z-ai/glm-4.5v Input modalities: Reported — text, image Output modalities: Reported — text Context: 65536 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Unknown Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Z.ai: GLM 4.6 \{#overview} URL: https://docs.travila.ai/available-models/k768higa0q z-ai — z-ai/glm-4.6 Input modalities: Reported — text Output modalities: Reported — text Context: 204800 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Z.ai: GLM 4.6V \{#overview} URL: https://docs.travila.ai/available-models/k7e8k0msbb z-ai — z-ai/glm-4.6v Input modalities: Reported — image, text, video Output modalities: Reported — text Context: 131072 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Unknown Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Z.ai: GLM 4.7 \{#overview} URL: https://docs.travila.ai/available-models/k7l3oqoh4l z-ai — z-ai/glm-4.7 Input modalities: Reported — text Output modalities: Reported — text Context: 204800 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Z.ai: GLM 4.7 Flash \{#overview} URL: https://docs.travila.ai/available-models/k7sgao29k2 z-ai — z-ai/glm-4.7-flash Input modalities: Reported — text Output modalities: Reported — text Context: 200000 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Z.ai: GLM 5 \{#overview} URL: https://docs.travila.ai/available-models/k83o5o1ish z-ai — z-ai/glm-5 Input modalities: Reported — text Output modalities: Reported — text Context: 204800 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Z.ai: GLM 5 Turbo \{#overview} URL: https://docs.travila.ai/available-models/k8a294hp8p z-ai — z-ai/glm-5-turbo Input modalities: Reported — text Output modalities: Reported — text Context: 202752 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Unknown Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Z.ai: GLM 5.1 \{#overview} URL: https://docs.travila.ai/available-models/k8hb5npdj9 z-ai — z-ai/glm-5.1 Input modalities: Reported — text Output modalities: Reported — text Context: 204800 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Z.ai: GLM 5.2 \{#overview} URL: https://docs.travila.ai/available-models/k8o0gem1u3 z-ai — z-ai/glm-5.2 Input modalities: Reported — text Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Z.ai: GLM 5.3 \{#overview} URL: https://docs.travila.ai/available-models/k8vbuq4jtr z-ai — z-ai/glm-5.3 Input modalities: Reported — text Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Z.ai: GLM 5.3 Flash \{#overview} URL: https://docs.travila.ai/available-models/k95dacnqeg z-ai — z-ai/glm-5.3-flash Input modalities: Reported — text, image, video Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Z.ai: GLM 5.3 FlashX \{#overview} URL: https://docs.travila.ai/available-models/k9cltmusva z-ai — z-ai/glm-5.3-flashx Input modalities: Reported — text, image, video Output modalities: Reported — text Context: 1048576 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Unknown Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Z.ai: GLM 5.3 Prime \{#overview} URL: https://docs.travila.ai/available-models/k9j634hu8o z-ai — z-ai/glm-5.3-prime Input modalities: Reported — text Output modalities: Reported — text Context: 1000000 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Unknown Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Z.ai: GLM 5V Turbo \{#overview} URL: https://docs.travila.ai/available-models/k9qrqgk2i0 z-ai — z-ai/glm-5v-turbo Input modalities: Reported — image, text, video Output modalities: Reported — text Context: 202752 tokens Input limit: Unknown Output limit: Unknown Input character limit: Unknown Tool calling: Supported Structured output: Unknown Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # OpenAI gpt-oss-20b \{#overview} URL: https://docs.travila.ai/available-models/otig24dkkq Open-weight model from OpenAI for text tasks, with reported support for tool calling, structured outputs and reasoning. OpenAI — openai/gpt-oss-20b Input modalities: Reported — text Output modalities: Reported — text Context: 131072 tokens Input limit: Unknown Output limit: 32768 tokens Input character limit: Unknown Tool calling: Supported Structured output: Supported Reasoning: Supported Streaming: Unknown Prompt caching: Unknown New selection: Open (effective 2026-10-22) Existing saved use: Undecided [All available models](/available-models) --- # Pricing URL: https://docs.travila.ai/pricing ## Plans | Plan | Base fee | Trial | Commitment | Included projects | Credits | |---|---|---|---|---|---| | Travila Platform — Monthly | 2499 USD per month, in advance | none | Month to month | 1 | prepaid credit expires after 12 months, rollover: full | | Travila Platform — Annual commitment | 1999 USD per month, in advance | 30 days, requires explicit purchase | Annual, 12 months | 1 | prepaid credit expires after 12 months, rollover: full | ## Usage prices | SKU | What is measured | Price | Plans | |---|---|---|---| | agents.rollouts.standard | Scheduled work, workflow steps and rollouts | 0 USD per 1 execution (work_kind agent-rollout) | Travila Platform — Monthly: list price; Travila Platform — Annual commitment: list price | | endusers.active.standard | Active end users | 0 USD per 1 end user up to 500; 0.001 USD per 1 end user | Travila Platform — Monthly: list price; Travila Platform — Annual commitment: list price | | evaluation.storage.standard | Retained evaluation items | 0.005 USD per 1 item | Travila Platform — Monthly: list price; Travila Platform — Annual commitment: list price | | exports.databricks.standard | Delivered export volume | 10 USD per 1,000,000,000 bytes (destination databricks) | Travila Platform — Monthly: list price; Travila Platform — Annual commitment: list price | | exports.snowflake.standard | Delivered export volume | 10 USD per 1,000,000,000 bytes (destination snowflake) | Travila Platform — Monthly: list price; Travila Platform — Annual commitment: list price | | memory.storage.standard | Retained memory capacity | 0.001 USD per 1 memory | Travila Platform — Monthly: list price; Travila Platform — Annual commitment: list price | | model.calls.standard | Model calls | 0 USD per 1 call up to 1,000; 0.0001 USD per 1 call | Travila Platform — Monthly: list price; Travila Platform — Annual commitment: list price | | notifications.handling.standard | Notifications | 0.00002 USD per 1 notification | Travila Platform — Monthly: list price; Travila Platform — Annual commitment: list price | | pipedream.calls.standard | Built-in tool and connector calls | 0.000225 USD per 1 call (funding platform, service pipedream); 0.000025 USD per 1 call (funding customer, service pipedream) | Travila Platform — Monthly: list price; Travila Platform — Annual commitment: list price | | pipedream.connected_users.standard | Active connected integration users | 2.25 USD per 1 connected user (funding platform, provider pipedream); 0 USD per 1 connected user (funding customer, provider pipedream) | Travila Platform — Monthly: list price; Travila Platform — Annual commitment: list price | | projects.additional.standard | Chargeable project capacity | 200 USD per 1 project (charge additional-project) | Travila Platform — Monthly: list price; Travila Platform — Annual commitment: list price | | projects.ai_assistant.standard | Chargeable project capacity | 100 USD per 1 project (charge ai-assistant) | Travila Platform — Monthly: list price; Travila Platform — Annual commitment: list price | | scheduler.fires.standard | Scheduled work, workflow steps and rollouts | 0.0001 USD per 1 execution (work_kind scheduler-fire) | Travila Platform — Monthly: list price; Travila Platform — Annual commitment: list price | | sessions.video_input.standard | Voice and video sessions | 0.0001 USD per 1 session (session_kind video-input) | Travila Platform — Monthly: list price; Travila Platform — Annual commitment: list price | | sessions.video_output.standard | Voice and video sessions | 0.0001 USD per 1 session (session_kind video-output) | Travila Platform — Monthly: list price; Travila Platform — Annual commitment: list price | | sessions.voice.standard | Voice and video sessions | 0.0001 USD per 1 session (session_kind voice) | Travila Platform — Monthly: list price; Travila Platform — Annual commitment: list price | | storage.capacity.standard | Stored data capacity | 0.03 USD per 1,000,000,000 bytes | Travila Platform — Monthly: list price; Travila Platform — Annual commitment: list price | | storage.reads.standard | Storage operations | 0.000005 USD per 1 operation (operation read) | Travila Platform — Monthly: list price; Travila Platform — Annual commitment: list price | | storage.uploads.standard | Storage operations | 0.000008 USD per 1 operation (operation upload) | Travila Platform — Monthly: list price; Travila Platform — Annual commitment: list price | | tools.food_weather.standard | Built-in tool and connector calls | 0.00001 USD per 1 call (service food); 0.00001 USD per 1 call (service weather) | Travila Platform — Monthly: list price; Travila Platform — Annual commitment: list price | | workflow.steps.standard | Scheduled work, workflow steps and rollouts | 0.0001 USD per 1 execution (work_kind workflow-step) | Travila Platform — Monthly: list price; Travila Platform — Annual commitment: list price | Model usage is priced per model on the [model rate card](/pricing/model-rate-card). ## Fees and credits | SKU | Kind | Price | Billing | |---|---|---|---| | travila.usage.credit.usd | Prepaid credit | drawn down as used | In advance | Prices change with 30 days' notice; third-party prices are set by us. Full terms: [Travila Master Services Agreement v2026.10.1](/pricing/agreements/travila.msa.standard) Addenda: [Travila Acceptable Use Policy v2026.10.1](/pricing/agreements/travila.aup.standard), [Travila Purchased and Promotional Credit Terms v2026.10.1](/pricing/agreements/travila.credits.standard) --- # Model rate card URL: https://docs.travila.ai/pricing/model-rate-card | Model | Publisher | Direction | Price per 1,000,000 tokens (USD) | Up to | Effective from | |---|---|---|---|---|---| | anthropic/claude-opus-5.5 | anthropic | input | 0 | 100,000 | 2026-10-22 | | anthropic/claude-opus-5.5 | anthropic | input | 4.6 | unlimited | 2026-10-22 | | anthropic/claude-opus-5.5 | anthropic | output | 0 | 100,000 | 2026-10-22 | | anthropic/claude-opus-5.5 | anthropic | output | 23 | unlimited | 2026-10-22 | | anthropic/claude-sonnet-4.6 | anthropic | input | 0 | 100,000 | 2026-10-22 | | anthropic/claude-sonnet-4.6 | anthropic | input | 3.45 | unlimited | 2026-10-22 | | anthropic/claude-sonnet-4.6 | anthropic | output | 0 | 100,000 | 2026-10-22 | | anthropic/claude-sonnet-4.6 | anthropic | output | 17.25 | unlimited | 2026-10-22 | | anthropic/claude-sonnet-5.5 | anthropic | input | 0 | 100,000 | 2026-10-22 | | anthropic/claude-sonnet-5.5 | anthropic | input | 2.3 | unlimited | 2026-10-22 | | anthropic/claude-sonnet-5.5 | anthropic | output | 0 | 100,000 | 2026-10-22 | | anthropic/claude-sonnet-5.5 | anthropic | output | 11.5 | unlimited | 2026-10-22 | | anthropic/claude-sonnet-5 | anthropic | input | 0 | 100,000 | 2026-10-22 | | anthropic/claude-sonnet-5 | anthropic | input | 2.3 | unlimited | 2026-10-22 | | anthropic/claude-sonnet-5 | anthropic | output | 0 | 100,000 | 2026-10-22 | | anthropic/claude-sonnet-5 | anthropic | output | 11.5 | unlimited | 2026-10-22 | | deepseek/deepseek-chat-v3-0324 | deepseek | input | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-chat-v3-0324 | deepseek | input | 0.3335 | unlimited | 2026-10-22 | | deepseek/deepseek-chat-v3-0324 | deepseek | output | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-chat-v3-0324 | deepseek | output | 1.311 | unlimited | 2026-10-22 | | deepseek/deepseek-chat-v3.1 | deepseek | input | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-chat-v3.1 | deepseek | input | 0.2875 | unlimited | 2026-10-22 | | deepseek/deepseek-chat-v3.1 | deepseek | output | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-chat-v3.1 | deepseek | output | 1.0925 | unlimited | 2026-10-22 | | deepseek/deepseek-chat | deepseek | input | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-chat | deepseek | input | 0.29601 | unlimited | 2026-10-22 | | deepseek/deepseek-chat | deepseek | output | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-chat | deepseek | output | 1.183005 | unlimited | 2026-10-22 | | deepseek/deepseek-r1-0528 | deepseek | input | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-r1-0528 | deepseek | input | 0.575 | unlimited | 2026-10-22 | | deepseek/deepseek-r1-0528 | deepseek | output | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-r1-0528 | deepseek | output | 2.4725 | unlimited | 2026-10-22 | | deepseek/deepseek-v3.1-terminus | deepseek | input | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-v3.1-terminus | deepseek | input | 0.3105 | unlimited | 2026-10-22 | | deepseek/deepseek-v3.1-terminus | deepseek | output | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-v3.1-terminus | deepseek | output | 1.15 | unlimited | 2026-10-22 | | deepseek/deepseek-v3.2-exp | deepseek | input | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-v3.2-exp | deepseek | input | 0.3105 | unlimited | 2026-10-22 | | deepseek/deepseek-v3.2-exp | deepseek | output | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-v3.2-exp | deepseek | output | 0.4715 | unlimited | 2026-10-22 | | deepseek/deepseek-v3.2 | deepseek | input | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-v3.2 | deepseek | input | 0.322 | unlimited | 2026-10-22 | | deepseek/deepseek-v3.2 | deepseek | output | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-v3.2 | deepseek | output | 0.483 | unlimited | 2026-10-22 | | deepseek/deepseek-v4-flash-0731 | deepseek | input | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-v4-flash-0731 | deepseek | input | 0.506 | unlimited | 2026-10-22 | | deepseek/deepseek-v4-flash-0731 | deepseek | output | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-v4-flash-0731 | deepseek | output | 1.518 | unlimited | 2026-10-22 | | deepseek/deepseek-v4-flash-vision-exp | deepseek | input | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-v4-flash-vision-exp | deepseek | input | 0.24794 | unlimited | 2026-10-22 | | deepseek/deepseek-v4-flash-vision-exp | deepseek | output | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-v4-flash-vision-exp | deepseek | output | 0.74382 | unlimited | 2026-10-22 | | deepseek/deepseek-v4-flash | deepseek | input | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-v4-flash | deepseek | input | 0.10465 | unlimited | 2026-10-22 | | deepseek/deepseek-v4-flash | deepseek | output | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-v4-flash | deepseek | output | 0.2093 | unlimited | 2026-10-22 | | deepseek/deepseek-v4-pro-0813 | deepseek | input | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-v4-pro-0813 | deepseek | input | 1.518 | unlimited | 2026-10-22 | | deepseek/deepseek-v4-pro-0813 | deepseek | output | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-v4-pro-0813 | deepseek | output | 4.554 | unlimited | 2026-10-22 | | deepseek/deepseek-v4-pro | deepseek | input | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-v4-pro | deepseek | input | 1.098549 | unlimited | 2026-10-22 | | deepseek/deepseek-v4-pro | deepseek | output | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-v4-pro | deepseek | output | 2.197098 | unlimited | 2026-10-22 | | deepseek/deepseek-v4.1-flash-1017 | deepseek | input | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-v4.1-flash-1017 | deepseek | input | 0.345 | unlimited | 2026-10-22 | | deepseek/deepseek-v4.1-flash-1017 | deepseek | output | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-v4.1-flash-1017 | deepseek | output | 1.38 | unlimited | 2026-10-22 | | deepseek/deepseek-v4.1-flash | deepseek | input | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-v4.1-flash | deepseek | input | 0.18975 | unlimited | 2026-10-22 | | deepseek/deepseek-v4.1-flash | deepseek | output | 0 | 100,000 | 2026-10-22 | | deepseek/deepseek-v4.1-flash | deepseek | output | 0.759 | unlimited | 2026-10-22 | | google/gemini-3-flash-preview | google | input | 0 | 100,000 | 2026-10-22 | | google/gemini-3-flash-preview | google | input | 0.575 | unlimited | 2026-10-22 | | google/gemini-3-flash-preview | google | output | 0 | 100,000 | 2026-10-22 | | google/gemini-3-flash-preview | google | output | 3.45 | unlimited | 2026-10-22 | | google/gemini-3-pro-image-preview | google | input | 0 | 100,000 | 2026-10-22 | | google/gemini-3-pro-image-preview | google | input | 2.3 | unlimited | 2026-10-22 | | google/gemini-3-pro-image-preview | google | output | 0 | 100,000 | 2026-10-22 | | google/gemini-3-pro-image-preview | google | output | 13.8 | unlimited | 2026-10-22 | | google/gemini-3-pro-image | google | input | 0 | 100,000 | 2026-10-22 | | google/gemini-3-pro-image | google | input | 2.3 | unlimited | 2026-10-22 | | google/gemini-3-pro-image | google | output | 0 | 100,000 | 2026-10-22 | | google/gemini-3-pro-image | google | output | 13.8 | unlimited | 2026-10-22 | | google/gemini-3.1-flash-image-preview | google | input | 0 | 100,000 | 2026-10-22 | | google/gemini-3.1-flash-image-preview | google | input | 0.575 | unlimited | 2026-10-22 | | google/gemini-3.1-flash-image-preview | google | output | 0 | 100,000 | 2026-10-22 | | google/gemini-3.1-flash-image-preview | google | output | 3.45 | unlimited | 2026-10-22 | | google/gemini-3.1-flash-image | google | input | 0 | 100,000 | 2026-10-22 | | google/gemini-3.1-flash-image | google | input | 0.575 | unlimited | 2026-10-22 | | google/gemini-3.1-flash-image | google | output | 0 | 100,000 | 2026-10-22 | | google/gemini-3.1-flash-image | google | output | 3.45 | unlimited | 2026-10-22 | | google/gemini-3.1-flash-lite-image | google | input | 0 | 100,000 | 2026-10-22 | | google/gemini-3.1-flash-lite-image | google | input | 0.2875 | unlimited | 2026-10-22 | | google/gemini-3.1-flash-lite-image | google | output | 0 | 100,000 | 2026-10-22 | | google/gemini-3.1-flash-lite-image | google | output | 1.725 | unlimited | 2026-10-22 | | google/gemini-3.1-flash-lite-preview | google | input | 0 | 100,000 | 2026-10-22 | | google/gemini-3.1-flash-lite-preview | google | input | 0.2875 | unlimited | 2026-10-22 | | google/gemini-3.1-flash-lite-preview | google | output | 0 | 100,000 | 2026-10-22 | | google/gemini-3.1-flash-lite-preview | google | output | 1.725 | unlimited | 2026-10-22 | | google/gemini-3.1-flash-lite | google | input | 0 | 100,000 | 2026-10-22 | | google/gemini-3.1-flash-lite | google | input | 0.2875 | unlimited | 2026-10-22 | | google/gemini-3.1-flash-lite | google | output | 0 | 100,000 | 2026-10-22 | | google/gemini-3.1-flash-lite | google | output | 1.725 | unlimited | 2026-10-22 | | google/gemini-3.1-pro-preview-customtools | google | input | 0 | 100,000 | 2026-10-22 | | google/gemini-3.1-pro-preview-customtools | google | input | 2.3 | unlimited | 2026-10-22 | | google/gemini-3.1-pro-preview-customtools | google | output | 0 | 100,000 | 2026-10-22 | | google/gemini-3.1-pro-preview-customtools | google | output | 13.8 | unlimited | 2026-10-22 | | google/gemini-3.1-pro-preview | google | input | 0 | 100,000 | 2026-10-22 | | google/gemini-3.1-pro-preview | google | input | 2.3 | unlimited | 2026-10-22 | | google/gemini-3.1-pro-preview | google | output | 0 | 100,000 | 2026-10-22 | | google/gemini-3.1-pro-preview | google | output | 13.8 | unlimited | 2026-10-22 | | google/gemini-3.5-flash-lite | google | input | 0 | 100,000 | 2026-10-22 | | google/gemini-3.5-flash-lite | google | input | 0.345 | unlimited | 2026-10-22 | | google/gemini-3.5-flash-lite | google | output | 0 | 100,000 | 2026-10-22 | | google/gemini-3.5-flash-lite | google | output | 2.875 | unlimited | 2026-10-22 | | google/gemini-3.5-flash | google | input | 0 | 100,000 | 2026-10-22 | | google/gemini-3.5-flash | google | input | 1.725 | unlimited | 2026-10-22 | | google/gemini-3.5-flash | google | output | 0 | 100,000 | 2026-10-22 | | google/gemini-3.5-flash | google | output | 10.35 | unlimited | 2026-10-22 | | google/gemini-3.6-flash | google | input | 0 | 100,000 | 2026-10-22 | | google/gemini-3.6-flash | google | input | 0.8625 | unlimited | 2026-10-22 | | google/gemini-3.6-flash | google | output | 0 | 100,000 | 2026-10-22 | | google/gemini-3.6-flash | google | output | 4.3125 | unlimited | 2026-10-22 | | google/gemini-3.7-flash | google | input | 0 | 100,000 | 2026-10-22 | | google/gemini-3.7-flash | google | input | 0.8625 | unlimited | 2026-10-22 | | google/gemini-3.7-flash | google | output | 0 | 100,000 | 2026-10-22 | | google/gemini-3.7-flash | google | output | 4.3125 | unlimited | 2026-10-22 | | google/gemini-3.8-flash | google | input | 0 | 100,000 | 2026-10-22 | | google/gemini-3.8-flash | google | input | 0.94875 | unlimited | 2026-10-22 | | google/gemini-3.8-flash | google | output | 0 | 100,000 | 2026-10-22 | | google/gemini-3.8-flash | google | output | 4.74375 | unlimited | 2026-10-22 | | google/gemini-4-argon | google | input | 0 | 100,000 | 2026-10-22 | | google/gemini-4-argon | google | input | 2.3 | unlimited | 2026-10-22 | | google/gemini-4-argon | google | output | 0 | 100,000 | 2026-10-22 | | google/gemini-4-argon | google | output | 11.5 | unlimited | 2026-10-22 | | google/gemini-nano-banana-2.1 | google | input | 0 | 100,000 | 2026-10-22 | | google/gemini-nano-banana-2.1 | google | input | 1.725 | unlimited | 2026-10-22 | | google/gemini-nano-banana-2.1 | google | output | 0 | 100,000 | 2026-10-22 | | google/gemini-nano-banana-2.1 | google | output | 8.625 | unlimited | 2026-10-22 | | openai/gpt-6-luna-pro | openai | input | 0 | 100,000 | 2026-10-22 | | openai/gpt-6-luna-pro | openai | input | 0.115 | unlimited | 2026-10-22 | | openai/gpt-6-luna-pro | openai | output | 0 | 100,000 | 2026-10-22 | | openai/gpt-6-luna-pro | openai | output | 0.575 | unlimited | 2026-10-22 | | openai/gpt-6-luna | openai | input | 0 | 100,000 | 2026-10-22 | | openai/gpt-6-luna | openai | input | 0.115 | unlimited | 2026-10-22 | | openai/gpt-6-luna | openai | output | 0 | 100,000 | 2026-10-22 | | openai/gpt-6-luna | openai | output | 0.575 | unlimited | 2026-10-22 | | openai/gpt-6-sol-pro | openai | input | 0 | 100,000 | 2026-10-22 | | openai/gpt-6-sol-pro | openai | input | 2.3 | unlimited | 2026-10-22 | | openai/gpt-6-sol-pro | openai | output | 0 | 100,000 | 2026-10-22 | | openai/gpt-6-sol-pro | openai | output | 11.5 | unlimited | 2026-10-22 | | openai/gpt-6-sol | openai | input | 0 | 100,000 | 2026-10-22 | | openai/gpt-6-sol | openai | input | 2.3 | unlimited | 2026-10-22 | | openai/gpt-6-sol | openai | output | 0 | 100,000 | 2026-10-22 | | openai/gpt-6-sol | openai | output | 11.5 | unlimited | 2026-10-22 | | openai/gpt-oss-20b | OpenAI | input | 0 | 100,000 | 2026-10-22 | | openai/gpt-oss-20b | OpenAI | input | 0.0207 | unlimited | 2026-10-22 | | openai/gpt-oss-20b | OpenAI | output | 0 | 100,000 | 2026-10-22 | | openai/gpt-oss-20b | OpenAI | output | 0.1035 | unlimited | 2026-10-22 | | z-ai/glm-4.5-air | z-ai | input | 0 | 100,000 | 2026-10-22 | | z-ai/glm-4.5-air | z-ai | input | 0.1495 | unlimited | 2026-10-22 | | z-ai/glm-4.5-air | z-ai | output | 0 | 100,000 | 2026-10-22 | | z-ai/glm-4.5-air | z-ai | output | 0.9775 | unlimited | 2026-10-22 | | z-ai/glm-4.5 | z-ai | input | 0 | 100,000 | 2026-10-22 | | z-ai/glm-4.5 | z-ai | input | 0.69 | unlimited | 2026-10-22 | | z-ai/glm-4.5 | z-ai | output | 0 | 100,000 | 2026-10-22 | | z-ai/glm-4.5 | z-ai | output | 2.53 | unlimited | 2026-10-22 | | z-ai/glm-4.5v | z-ai | input | 0 | 100,000 | 2026-10-22 | | z-ai/glm-4.5v | z-ai | input | 0.69 | unlimited | 2026-10-22 | | z-ai/glm-4.5v | z-ai | output | 0 | 100,000 | 2026-10-22 | | z-ai/glm-4.5v | z-ai | output | 2.07 | unlimited | 2026-10-22 | | z-ai/glm-4.6 | z-ai | input | 0 | 100,000 | 2026-10-22 | | z-ai/glm-4.6 | z-ai | input | 0.6325 | unlimited | 2026-10-22 | | z-ai/glm-4.6 | z-ai | output | 0 | 100,000 | 2026-10-22 | | z-ai/glm-4.6 | z-ai | output | 2.53 | unlimited | 2026-10-22 | | z-ai/glm-4.6v | z-ai | input | 0 | 100,000 | 2026-10-22 | | z-ai/glm-4.6v | z-ai | input | 0.345 | unlimited | 2026-10-22 | | z-ai/glm-4.6v | z-ai | output | 0 | 100,000 | 2026-10-22 | | z-ai/glm-4.6v | z-ai | output | 1.035 | unlimited | 2026-10-22 | | z-ai/glm-4.7-flash | z-ai | input | 0 | 100,000 | 2026-10-22 | | z-ai/glm-4.7-flash | z-ai | input | 0.069575 | unlimited | 2026-10-22 | | z-ai/glm-4.7-flash | z-ai | output | 0 | 100,000 | 2026-10-22 | | z-ai/glm-4.7-flash | z-ai | output | 0.46 | unlimited | 2026-10-22 | | z-ai/glm-4.7 | z-ai | input | 0 | 100,000 | 2026-10-22 | | z-ai/glm-4.7 | z-ai | input | 0.621 | unlimited | 2026-10-22 | | z-ai/glm-4.7 | z-ai | output | 0 | 100,000 | 2026-10-22 | | z-ai/glm-4.7 | z-ai | output | 2.277 | unlimited | 2026-10-22 | | z-ai/glm-5-turbo | z-ai | input | 0 | 100,000 | 2026-10-22 | | z-ai/glm-5-turbo | z-ai | input | 1.38 | unlimited | 2026-10-22 | | z-ai/glm-5-turbo | z-ai | output | 0 | 100,000 | 2026-10-22 | | z-ai/glm-5-turbo | z-ai | output | 4.6 | unlimited | 2026-10-22 | | z-ai/glm-5.1 | z-ai | input | 0 | 100,000 | 2026-10-22 | | z-ai/glm-5.1 | z-ai | input | 1.61 | unlimited | 2026-10-22 | | z-ai/glm-5.1 | z-ai | output | 0 | 100,000 | 2026-10-22 | | z-ai/glm-5.1 | z-ai | output | 5.06 | unlimited | 2026-10-22 | | z-ai/glm-5.2 | z-ai | input | 0 | 100,000 | 2026-10-22 | | z-ai/glm-5.2 | z-ai | input | 0.039215 | unlimited | 2026-10-22 | | z-ai/glm-5.2 | z-ai | output | 0 | 100,000 | 2026-10-22 | | z-ai/glm-5.2 | z-ai | output | 8.05 | unlimited | 2026-10-22 | | z-ai/glm-5.3-flash | z-ai | input | 0 | 100,000 | 2026-10-22 | | z-ai/glm-5.3-flash | z-ai | input | 0.00598 | unlimited | 2026-10-22 | | z-ai/glm-5.3-flash | z-ai | output | 0 | 100,000 | 2026-10-22 | | z-ai/glm-5.3-flash | z-ai | output | 0.228275 | unlimited | 2026-10-22 | | z-ai/glm-5.3-flashx | z-ai | input | 0 | 100,000 | 2026-10-22 | | z-ai/glm-5.3-flashx | z-ai | input | 0.4255 | unlimited | 2026-10-22 | | z-ai/glm-5.3-flashx | z-ai | output | 0 | 100,000 | 2026-10-22 | | z-ai/glm-5.3-flashx | z-ai | output | 1.4375 | unlimited | 2026-10-22 | | z-ai/glm-5.3-prime | z-ai | input | 0 | 100,000 | 2026-10-22 | | z-ai/glm-5.3-prime | z-ai | input | 3.22 | unlimited | 2026-10-22 | | z-ai/glm-5.3-prime | z-ai | output | 0 | 100,000 | 2026-10-22 | | z-ai/glm-5.3-prime | z-ai | output | 10.12 | unlimited | 2026-10-22 | | z-ai/glm-5.3 | z-ai | input | 0 | 100,000 | 2026-10-22 | | z-ai/glm-5.3 | z-ai | input | 0.09085 | unlimited | 2026-10-22 | | z-ai/glm-5.3 | z-ai | output | 0 | 100,000 | 2026-10-22 | | z-ai/glm-5.3 | z-ai | output | 1.61 | unlimited | 2026-10-22 | | z-ai/glm-5 | z-ai | input | 0 | 100,000 | 2026-10-22 | | z-ai/glm-5 | z-ai | input | 1.15 | unlimited | 2026-10-22 | | z-ai/glm-5 | z-ai | output | 0 | 100,000 | 2026-10-22 | | z-ai/glm-5 | z-ai | output | 3.68 | unlimited | 2026-10-22 | | z-ai/glm-5v-turbo | z-ai | input | 0 | 100,000 | 2026-10-22 | | z-ai/glm-5v-turbo | z-ai | input | 1.38 | unlimited | 2026-10-22 | | z-ai/glm-5v-turbo | z-ai | output | 0 | 100,000 | 2026-10-22 | | z-ai/glm-5v-turbo | z-ai | output | 4.6 | unlimited | 2026-10-22 | Prices change with 30 days' notice; third-party prices are set by us. Full terms: [Travila Master Services Agreement v2026.10.1](/pricing/agreements/travila.msa.standard) --- # Travila Acceptable Use Policy URL: https://docs.travila.ai/pricing/agreements/travila.aup.standard Version 2026.10.1 · Effective 2026-10-22 Attaches to: Master Services Agreement travila.msa.standard v2026.10.1 ## Defaults | Term | Value | |---|---| | Taxes | Fees exclusive of taxes | | Price change notice | 0 days | | Refunds | Non-refundable | | Dispute window | 0 days | | Late interest per month | 0.0% | | Cure period | 0 days | | Suspension | Read-only | | Renewal | Auto-renew | | Third-party prices | pass through at the provider's price | ## Scope and acceptance Effective 2026-10-22 for new orders accepted by the customer and the Travila contracting provider identified in the order. The order identifies the legal parties, service start, governing law and dispute forum, selected Plan, rate-card revision and any applicable addenda. Publishing these terms is an offer; it does not by itself establish customer acceptance, amend an existing agreement, start a subscription or authorize a charge. Existing customers remain governed by their accepted terms unless changed in accordance with them. ## Permitted use Use the service within the accepted scope and applicable law. Maintain rights to submitted content and authorization for connected accounts and tools. Protect credentials, apply least privilege, and review AI output before consequential use. ## Prohibited conduct Do not distribute malware, exploit systems without permission, evade access or spending controls, send unlawful spam, infringe third-party rights, or facilitate fraud, exploitation or illegal activity. Do not submit restricted or highly sensitive data unless the order and required safeguards expressly permit it. Authorized security testing requires an agreed scope. ## Enforcement Investigate credible reports and use proportionate restrictions. Give notice and a chance to cure where practical; urgent harm or legal obligations may require immediate restriction. Provide a route to challenge mistakes. The service must not imply a certified safety, healthcare or emergency-response capability that has not been qualified. --- # Travila Purchased and Promotional Credit Terms URL: https://docs.travila.ai/pricing/agreements/travila.credits.standard Version 2026.10.1 · Effective 2026-10-22 Attaches to: Master Services Agreement travila.msa.standard v2026.10.1 ## Defaults | Term | Value | |---|---| | Taxes | Fees exclusive of taxes | | Price change notice | 0 days | | Refunds | Refund window | | Refund window | 7 days | | Dispute window | 0 days | | Late interest per month | 0.0% | | Cure period | 0 days | | Suspension | Read-only | | Renewal | Auto-renew | | Third-party prices | pass through at the provider's price | ## Scope and acceptance Effective 2026-10-22 for new orders accepted by the customer and the Travila contracting provider identified in the order. The order identifies the legal parties, service start, governing law and dispute forum, selected Plan, rate-card revision and any applicable addenda. Publishing these terms is an offer; it does not by itself establish customer acceptance, amend an existing agreement, start a subscription or authorize a charge. Existing customers remain governed by their accepted terms unless changed in accordance with them. ## Purchased balance A purchased USD usage credit funds one USD of eligible selected usage charges. No additional credit-purchase fee applies; model and platform SKU prices remain separately visible. Paid credits carry across billing periods for twelve months from purchase, then expire only where lawful and after advance reminders. The customer sees each purchase, consumption and expiry lot. No cash-equivalent transfer or resale is allowed. ## Eligibility and consumption Purchased credits pay selected metered usage and explicitly selected supplier reimbursement, excluding recurring base fees, add-ons and taxes unless the order expressly opts those charges in. Apply soonest-expiring eligible credit first and keep purchased and promotional balances traceable. No double deduction or charge for a rejected duplicate event. Credit billing is offered only after allocation, expiry and balance controls have been qualified. ## Refund window Refund the unused purchased portion requested within seven calendar days of purchase through the original payment method. Consumed usage is not refunded unless charged in error. Mandatory rights and provider-breach remedies prevail. ## Auto-recharge and depleted balances Auto-recharge is off by default and requires explicit selection of threshold, amount, maximum exposure and payment authorization. Cancelling consent stops future recharges. No negative balance, overdraft or credit line is implied. A spending limit and a funded balance are independent controls; both must allow a new charge. A hard real-time spending cap applies only when the accepted order expressly provides one. ## Promotional and remedy credits Promotional credit is issued only by a specific grant naming eligible charges, amount and expiry; it has no cash refund and does not pay taxes. Startup platform-fee discounts are not usage-credit grants. SLA remedy credits apply only to their qualifying service. Publication of these terms does not issue a grant. --- # Travila Master Services Agreement URL: https://docs.travila.ai/pricing/agreements/travila.msa.standard Version 2026.10.1 · Effective 2026-10-22 ## Defaults | Term | Value | |---|---| | Taxes | Fees exclusive of taxes | | Price change notice | 30 days | | Refunds | Prorated | | Dispute window | 60 days | | Late interest per month | 1.5% | | Cure period | 15 days | | Suspension | Read-only | | Renewal | Auto-renew | | Third-party prices | set by us | | Payment method | Card | | Payment method | Invoice | ## Definitions **Allowance** — A stated quantity included without an additional charge for a specified SKU and period. Its scope and reset rule belong to the selected offer. **Commitment** — The duration or spending obligation accepted for an offer, separate from its invoice cadence and any trial before paid service. **Credit** — A stated monetary amount available to offset eligible charges. Funding, eligible charges, expiry and rollover require explicit terms. **Meter** — A defined quantity of platform activity or retained capacity, with its unit, measurement basis and dimensions. Defining a meter does not mean it is emitting usage. **Overage** — Usage above an applicable allowance, treated at the selected list price or plan price, or blocked by the plan. **Plan** — A versioned platform offer that groups the base fee, included SKUs, allowances, billing cadence and commitment under governing commercial terms. **SKU** — A separately priced unit of an offer, with its currency, pricing method and price bands. A usage SKU identifies the meter it prices. ## Scope and acceptance Effective 2026-10-22 for new orders accepted by the customer and the Travila contracting provider identified in the order. The order identifies the legal parties, service start, governing law and dispute forum, selected Plan, rate-card revision and any applicable addenda. Publishing these terms is an offer; it does not by itself establish customer acceptance, amend an existing agreement, start a subscription or authorize a charge. Existing customers remain governed by their accepted terms unless changed in accordance with them. ## Commercial definitions A Meter defines the activity or capacity counted. A SKU states its price. A Plan selects the offered SKUs and the base fee. An Allowance is the included quantity; Overage follows the selected price or blocking rule. Credit applies only under explicit eligible-charge and expiry terms. A Commitment is distinct from billing cadence and any trial. ## Orders and service scope An accepted order identifies the parties, selected Plan, exact SKU revisions, permitted uses, service period and applicable addenda. The order controls negotiated commercial specifics; a data-processing addendum controls personal-data processing; other conflicts follow this agreement. Draft records and marketing do not establish customer acceptance. ## Subscription and measured usage The monthly platform fee is USD 2,499. The twelve-month commitment is USD 1,999 per paid month, collected monthly in advance: USD 23,988 over twelve paid months, excluding usage and taxes. Each includes one project. Usage and optional services are additional only under selected SKUs. The annual offer has a cancellable thirty-day platform-fee trial requiring explicit paid purchase. Trial usage is not free unless an express Allowance says so. ## Usage calculation and invoice evidence Measure the actual served model and the declared Meter dimensions. Graduated bands charge only quantities inside each band; volume bands use the rate for total volume. Apply an Allowance once, at its stated scope and period. An Overage is charged only under its selected rule. Preserve usage identifiers and quantity/rate evidence; correct duplicates and confirmed billing errors. Missing usage or supplier-cost evidence is unresolved, not zero usage. Billing collection begins only after the applicable metering and duplicate-charge controls have been qualified. ## Payment and taxes Collection: recurring fees in advance, measured usage in arrears or deducted from an explicitly funded prepaid balance. Card collection requires authorization. Invoice eligibility is individually approved; approved invoices are due thirty days after issue, with no automatic spend threshold. Prices exclude legally applicable transaction taxes, itemized separately; provider income taxes remain the provider’s responsibility. No automatic overdraft or auto-recharge consent is implied. ## Price changes and third-party charges Give at least thirty days of advance notice of increases to existing prices; apply them prospectively after the notice period. Preserve fixed committed platform fees for the current term unless the order expressly allows otherwise. Supplier list-price changes do not automatically replace authored SKU rates. A separately selected pass-through charge needs attributable supplier evidence and an explicit margin; a customer-funded credential creates no platform reimbursement for the same supplier cost. Notification handling and attributable delivery costs remain separate. ## Billing disputes and overdue payment A customer may dispute a charge in good faith within sixty days of its billing date and must pay the undisputed balance on time. Investigate disputed quantities and rates; do not charge late interest or suspend solely for a reasonably disputed amount while the customer cooperates. For undisputed overdue balances, give written notice and fifteen days to cure. Thereafter simple interest is the lesser of 1.5 percent per month or the legal maximum, only where lawful. ## Renewal, cancellation and termination Monthly subscriptions renew monthly and may be cancelled before the next period. Annual commitments renew for twelve months only when the accepted order clearly discloses renewal and permits non-renewal notice at least thirty days before term end. A trial never creates a paid Commitment without explicit purchase. A party may terminate for material breach remaining uncured fifteen days after notice, or immediately for an incurable material breach. Earned usage and agreed committed fees remain payable subject to express remedies and law. ## Refunds and credit treatment Ordinary cancellation does not refund consumed service or the current paid subscription period. If the provider terminates for convenience or the customer terminates for an uncured provider breach, refund unused prepaid platform fees proportionally for the unserved period. Correct duplicate or erroneous charges and honor mandatory refunds. Purchased usage Credit has separate supplemental terms; promotional credits and service-remedy credits are distinct from purchased funds. ## Suspension and continuity For payment default after the stated cure period, the posture is read-only access where technically available, preserving a reasonable export route. Security threats, unlawful use or serious abuse may require immediate proportionate restriction, with notice when lawful and practical. Restore service after the cause is resolved. The order identifies available export methods and continuity arrangements; this agreement does not promise an unimplemented export mechanism. ## Customer content and AI services Customers retain their content and grant only rights needed to provide the selected service. Customers must have permission to submit data and use outputs. AI outputs may be inaccurate and require appropriate human review. The order identifies the selected AI providers and their applicable data-use terms. Use of customer content for training requires the customer’s express authorization under those terms; no uniform third-party retention or training guarantee is implied. No zero-retention, residency or regulated-use promise is inferred. ## Confidentiality, security and support Each party protects the other’s non-public information with reasonable care, limits access to authorized people and uses it only for the agreement. Lawful disclosures receive notice where permitted. Security measures, subprocessors, data locations and deletion periods belong in completed customer schedules. Support scope is stated in the order. Beta services carry no contractual uptime commitment; an SLA applies only when expressly adopted after operational qualification. ## Risk allocation Mutual general liability cap: fees paid or payable under the affected order during the preceding twelve months. Exclude indirect and consequential loss to the extent lawful. Fraud, deliberate misconduct, liabilities that law forbids limiting, and payment obligations are outside that cap. Confidentiality, data protection and intellectual-property indemnities require negotiated treatment in the completed order; this agreement does not assign them an unlimited or increased cap. ## Existing benefit and add-ons An eligible non-funded organization may receive three platform-fee months once under a separately accepted promotional order, excluding usage, additional projects and add-ons. It replaces rather than stacks with the annual trial. Eligibility, redemption and enforcement must exist before applying the benefit. The optional project AI Assistant is USD 100 per project-month when expressly ordered, with active-duration proration. Publication of these terms issues no grant and creates no customer entitlement. ## Rate card coverage and separately quoted services The published model rate card covers the 56 expressly listed models and separate input/output token quantities at fixed USD prices. These list prices are derived from a dated provider catalog plus a 15% service markup; the published amounts control and do not change automatically with supplier prices. There is no blanket price for an unlisted model or modality. Speech recognition, speech synthesis, video input processing, video generation, stock-data tools and currency-data tools require a separate written quote before use is chargeable. Session handling, where selected, is a separate listed service and does not include unquoted provider processing. Each selected model SKU includes a free graduated band of 100,000 input tokens and a separate 100,000 output tokens per project subscription per monthly billing period. Only excess usage is chargeable; free quantities reset each period, do not roll over and do not transfer between models or subscriptions. Other listed SKU allowances apply as stated. Additional promotional allowances or volume discounts require an express accepted order. --- # Synchronous client tool handoff URL: https://docs.travila.ai/diagrams/1qk1t3b6hm The application receives a pending client tool, runs it locally, submits the result with its cursor, and receives the completed response. ```mermaid sequenceDiagram accTitle: Synchronous client tool handoff accDescr: The application receives a pending client tool, runs it locally, submits the result with its cursor, and receives the completed response. participant C as Your app participant GW as Travila API participant M as Model C->>GW: POST /send-message-sync M->>GW: Calls navigate_to GW-->>C: AWAITING_CLIENT_TOOLS + pendingClientTools + clientToolCursor C->>C: Run the tool locally C->>GW: POST /submit-client-tool-results-sync (echo the cursor) M->>GW: Final answer GW-->>C: COMPLETED + messages ``` Use this in a guide: [Approve a tool action and finish the conversation](/managed-agents/delegation-approvals/using-tools) --- # Asynchronous client tool handoff URL: https://docs.travila.ai/diagrams/1qmo5rvpk0 An accepted run signals a pending tool; the worker reads the call and deadline, executes the tool, and submits the result for the run. ```mermaid sequenceDiagram accTitle: Asynchronous client tool handoff accDescr: An accepted run signals a pending tool; the worker reads the call and deadline, executes the tool, and submits the result for the run. participant C as Your service participant GW as Travila API participant M as Model C->>GW: POST /send-message GW-->>C: runId after acceptance M->>GW: Calls navigate_to GW-->>C: llm.tool_call_started webhook C->>GW: POST /list-pending-client-tools GW-->>C: the call + clientToolDeadlineAt C->>C: Run the tool C->>GW: POST /submit-client-tool-results GW-->>C: runId after acceptance ``` Use this in a guide: [Approve a tool action and finish the conversation](/managed-agents/delegation-approvals/using-tools) --- # Dataset replay and comparison loop URL: https://docs.travila.ai/diagrams/1qobmu47dp An application creates a dataset, curates inputs and expectations, runs its harness, records the experiment and reads stored run results. ```mermaid flowchart LR accTitle: Dataset replay and comparison loop accDescr: An application creates a dataset, curates inputs and expectations, runs its harness, records the experiment and reads stored run results. A["create-dataset"] --> B["add-dataset-item\n(harvest the turn)"] B --> C["update-dataset-item\n(author the expectation)"] C --> D["your harness runs"] D --> E["record and verify the experiment"] E --> F["list-dataset-runs"] F --> G["get-dataset-run"] ``` Use this in a guide: [Replay datasets and runs](/insights/evaluation/datasets-and-runs) --- # Memory retrieval and extraction lifecycle URL: https://docs.travila.ai/diagrams/1qq2a9383f The platform retrieves relevant memories before generation and starts asynchronous extraction from run messages after returning the reply. ```mermaid sequenceDiagram accTitle: Memory retrieval and extraction lifecycle accDescr: The platform retrieves relevant memories before generation and starts asynchronous extraction from run messages after returning the reply. participant C as Client participant P as Platform participant M as Memory store C->>P: send-message (user turn) P->>M: search memories (query = last user message) M-->>P: top-K memories above threshold Note over P: attach memory context to latest user message P->>P: generation with injected memories P-->>C: assistant reply P-)M: async extraction (new facts from run messages) ``` Use this in a guide: [Memory retrieval and extraction](/api/memory/lifecycle) --- # Generation configuration precedence URL: https://docs.travila.ai/diagrams/1qs69e3kcq Profile or thread defaults form the base; populated per-send fields override that base, and a platform default model fills an unset model. ```mermaid flowchart TD accTitle: Generation configuration precedence accDescr: Profile or thread defaults form the base; populated per-send fields override that base, and a platform default model fills an unset model. A["Profile config\n(if active — its rendered systemPrompt wins)"] --> M B["Thread defaultGenerationConfig\n(fallback when no profile)"] --> M M["Merge base"] --> C["Per-send overrideGenerationConfig\n(merges field-by-field — any populated field replaces)"] C --> D["Platform default model\n(fallback if nothing sets model)"] ``` Use this in a guide: [Configuration precedence and plugins](/api/model-controls/configuration) --- # Model candidate routing URL: https://docs.travila.ai/diagrams/1qu1c53eo4 Eligible candidates proceed to generation. Failed attempts try remaining candidates; exhaustion ends in an error. An empty eligible set also produces an error. ```mermaid flowchart LR accTitle: Model candidate routing accDescr: Eligible candidates proceed to generation. Failed attempts try remaining candidates; exhaustion ends in an error. An empty eligible set also produces an error. A["Request\n(models list + filter)"] --> B["Filter candidates\n(capabilities, cost)"] B --> C{"Any survivors?"} C -- "yes" --> D["Generation\n(selected candidate)"] D --> E{"Success?"} E -- "yes" --> F["Response"] E -- "no" --> I{"Candidate remaining?"} I -- "yes" --> G["Next candidate\n(fallback chain)"] G --> D I -- "no" --> J["Generation failed\nRead returned error"] C -- "no" --> H["No eligible model\nRead returned error"] ``` Use this in a guide: [Model routing and selection](/api/model-controls/routing) --- # Choose a model by the job you need it to do URL: https://docs.travila.ai/blog/choose-a-model-by-task-and-capability 2026-10-20 · Travila documentation A short checklist for matching a task to model capabilities, then testing a small shortlist. ## Start with a task, not a ranking Write down one concrete input and what a useful answer must contain. Reading a screenshot needs different inputs from drafting a short text reply. A model name alone does not tell you whether it fits either job. ## Make a capability checklist * **Inputs and outputs:** check the modalities the task needs, such as text or images, and the kind of output you expect. * **Context and response size:** compare your largest expected prompt with the documented context capacity, leave room for the response, and check any separate output limit. * **Required options:** if the workflow needs tool calls or a structured response, verify those specific capabilities instead of assuming every model supports them. * **Access and privacy:** check the account and data-handling restrictions that apply to your use case. ## Test a small shortlist Try the same representative cases with each candidate. Include an ambiguous input and a case where the expected output can be checked. Record missing information, format errors and factual mistakes. Choose acceptance criteria before comparing the answers; a fluent response is not enough if it fails the task. ## Use model cards as a starting point The [Available Models](/available-models) page helps you inspect documented properties. Provider references can report input and output modalities, context capacity and supported parameters. Treat an unknown capability as a question to verify, and confirm access in your intended environment separately. Recheck the source when you change the task or model. ## Further reading 1. [List all models and their properties](https://openrouter.ai/docs/api/api-reference/models/list-all-models-and-their-properties) — OpenRouter --- # Agent Profile APIs URL: https://docs.travila.ai/api/agent-profiles Version: `aju17f20mq` Use the reference below for request and response fields and operation-specific requirements. # Overview \{#overview} Manage agent profiles, their versions and reusable prompt fragments. Select profiles on the conversation API using `activeProfileId` at creation or `setActiveProfileId` when sending. ## Authentication \{#authentication} Use an authorized backend `sk_…` key in `X-API-Key`; these configuration operations do not need an end-user identity. A console JWT belongs to the separate console surface. See [Authentication](https://docs.travila.ai/core-platform/identity-access/authentication). ## Scoping \{#scoping} 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 profile version pins that profile record. Current fragment resolution can use the latest fragment set; a profile version alone is not a complete record of the prompt or configuration used by a turn. **Related guide:** [Create and version agent profiles](https://docs.travila.ai/managed-agents/profiles-prompts) ### JSON conventions \{#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](https://docs.travila.ai/api). ## Profiles \{#reference-group-1} Create, read, update, and delete agent profiles. * [Create an agent profile](/api/agent-profiles/create-agent-profile) * [Get an agent profile](/api/agent-profiles/get-agent-profile) * [List agent profiles](/api/agent-profiles/list-agent-profiles) * [Update an agent profile](/api/agent-profiles/update-agent-profile) * [Delete an agent profile](/api/agent-profiles/delete-agent-profile) * [Get the profile library](/api/agent-profiles/get-agent-profile-library) ## Versions \{#reference-group-2} Read a profile's immutable version history and the fragment set behind a version. * [List a profile's versions](/api/agent-profiles/list-agent-profile-versions) * [Get a fragment set by version](/api/agent-profiles/get-prompt-fragment-set) ## Prompt Fragments \{#reference-group-3} Reusable template blocks shared across profiles. * [Create a prompt fragment](/api/agent-profiles/create-prompt-fragment) * [Get a prompt fragment](/api/agent-profiles/get-prompt-fragment) * [List prompt fragments](/api/agent-profiles/list-prompt-fragments) * [Update a prompt fragment](/api/agent-profiles/update-prompt-fragment) * [Delete a prompt fragment](/api/agent-profiles/delete-prompt-fragment) ## Import \{#reference-group-4} Bulk-convert an existing prompt library into profiles and fragments. * [Import a prompt library](/api/agent-profiles/import-agent-profiles) ## Server 1 \{#reference-server-1} Travila API [https://api.travila.ai](https://api.travila.ai) ## X-API-Key \{#authentication-apiKeyAuth} Authorized tenant backend secret key (`sk_…`). No end-user identity is needed for these configuration operations. Keep the key out of client apps; authorization and provisioning still apply.

Authentication credentials

### apiKeyAuth Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-API-Key` ### onBehalfOf Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-On-Behalf-Of` ### bearerAuth Security scheme type: `http` HTTP authorization scheme: `bearer` ## Operations - [Create an agent profile](/api/agent-profiles/create-agent-profile) — `POST /api/v1/agent-profiles/create` - [Get an agent profile](/api/agent-profiles/get-agent-profile) — `POST /api/v1/agent-profiles/get` - [List agent profiles](/api/agent-profiles/list-agent-profiles) — `POST /api/v1/agent-profiles/list` - [Update an agent profile](/api/agent-profiles/update-agent-profile) — `POST /api/v1/agent-profiles/update` - [Delete an agent profile](/api/agent-profiles/delete-agent-profile) — `POST /api/v1/agent-profiles/delete` - [Get the profile library](/api/agent-profiles/get-agent-profile-library) — `POST /api/v1/agent-profiles/library` - [List a profile's versions](/api/agent-profiles/list-agent-profile-versions) — `POST /api/v1/agent-profiles/versions` - [Get a fragment set by version](/api/agent-profiles/get-prompt-fragment-set) — `POST /api/v1/prompt-fragments/get-set` - [Create a prompt fragment](/api/agent-profiles/create-prompt-fragment) — `POST /api/v1/prompt-fragments/create` - [Get a prompt fragment](/api/agent-profiles/get-prompt-fragment) — `POST /api/v1/prompt-fragments/get` - [List prompt fragments](/api/agent-profiles/list-prompt-fragments) — `POST /api/v1/prompt-fragments/list` - [Update a prompt fragment](/api/agent-profiles/update-prompt-fragment) — `POST /api/v1/prompt-fragments/update` - [Delete a prompt fragment](/api/agent-profiles/delete-prompt-fragment) — `POST /api/v1/prompt-fragments/delete` - [Import a prompt library](/api/agent-profiles/import-agent-profiles) — `POST /api/v1/agent-profiles/import` Document ID: `DOC-API-agent-profiles-overview`. [Section identities and revisions](/documentation-manifest.json). - Overview: `DOC-API-agent-profiles-overview#overview` - Authentication: `DOC-API-agent-profiles-overview#authentication` - Scoping: `DOC-API-agent-profiles-overview#scoping` - JSON conventions: `DOC-API-agent-profiles-overview#json-conventions` - Profiles: `DOC-API-agent-profiles-overview#reference-group-1` - Versions: `DOC-API-agent-profiles-overview#reference-group-2` - Prompt Fragments: `DOC-API-agent-profiles-overview#reference-group-3` - Import: `DOC-API-agent-profiles-overview#reference-group-4` - Server 1: `DOC-API-agent-profiles-overview#reference-server-1` - X-API-Key: `DOC-API-agent-profiles-overview#authentication-apiKeyAuth` --- # Create an agent profile URL: https://docs.travila.ai/api/agent-profiles/create-agent-profile **POST** `/api/v1/agent-profiles/create` Creates a profile in the caller's project library. A duplicate profile ID fails with `ALREADY_EXISTS`; use [update](/api/agent-profiles/update-agent-profile) to replace an existing profile. The store assigns the initial immutable version. The system prompt must be a valid template and every variable spec needs a unique name; otherwise create fails with `400`. Enabled profiles are immediately selectable. Disabled profiles are omitted from the selection library, and a direct send naming one fails with `ACTIVE_PROFILE_DISABLED`. Queued messages currently take a different fallback path; see [unusable profiles](/managed-agents/conversations/configuration#when-the-active-profile-cannot-be-used). Use this in a guide: [Build a reusable assistant profile](/managed-agents/profiles-prompts) · [Keep a model on the providers you choose](/managed-agents/model-controls/provider-pinning) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for creating a project-scoped agent profile with prompt and generation settings. **projectId** `string` Identifier of the project owning the agent-profile library. Use default for the default project. **profile** `any` **required** Agent profile definition to add to the project library. All of: Variant 1: A reusable persona with model configuration, tools and metadata describing when it should be selected. See the profile-selection and versioning guide for profile resolution and fragment versions. Model reference: [AgentProfile](/api/models/schema-1hmbcecg1j#request). **profileId** `string` Stable id, unique within the project library. **name** `string` Display name used when selecting an agent profile. e.g. "Nutrition Coach" **description** `string` Human-facing summary. **whenToUse** `string` Routing hint, Skill-style "use when…" **keywords** `array[string]` Keywords associated with discovery or selection of the agent profile. Type: `string` **enabled** `boolean` Whether the profile is enabled for selection. Omission during creation defaults to true; an explicitly false value creates a disabled profile. Disabled profiles are not selectable. **generationConfig** `any` Model, sampling, and tool configuration used for generation. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#request). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#request). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#request). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#request). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#request). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#request). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinitionInput]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#request). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinitionInput]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRuleInput]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#request). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#request). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#request). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRuleInput]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#request). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#request). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfigInput]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#request). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#request). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#request). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#request). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) Minimum length: 2 Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$ **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#request). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" Maximum length: 50 **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" Enum: ``, `friendly`, `iso8601`, `date_only` Maximum length: 50 **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#request). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` **required** Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" Enum: `minimal`, `standard`, `verbose` **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#request). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#request). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **mcpServers** `array[llm_v1_common_v1_MCPServerReferenceInput]` MCP servers used for tool discovery when this profile is active. This list replaces the conversation-wide MCP server list for those turns. MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#request). **serverId** `string` **required** ID of pre-configured MCP server (e.g., "github", "filesystem"). Minimum length: 1 **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **variableSpecs** `array[llm_v1_common_v1_PromptVariableSpecInput]` Variables consumed by the profile’s system-prompt template, rendered from the conversation’s prompt\_variables. Declares a variable used by a profile’s system-prompt template. Values are supplied through the conversation’s prompt\_variables. When creating a conversation with an explicitly selected profile, a variable\_specs entry with required set to true and no nonempty default\_value causes MISSING\_REQUIRED\_PROMPT\_VARIABLES if the variable is missing. Supply its value at creation; this validation is not repeated for each send or queued turn. Set intended values explicitly even when the specification declares a default. A nonempty default\_value suppresses the creation-time missing-required error but is not automatically inserted into the rendered prompt. Model reference: [PromptVariableSpec](/api/models/schema-1hkadmq6cl#request). **name** `string` Variable name referenced by the profile’s system-prompt template. e.g. "user\_name" → substituted for \{\{.user\_name}} **description** `string` Console hint + caller documentation. **required** `boolean` Whether a value is required for a profile explicitly selected at conversation creation. This validation does not run for every send or queued turn. **defaultValue** `string` A nonempty default value suppresses the creation-time missing-required error. It is not automatically inserted into the rendered prompt; supply intended values explicitly. **type** `any` Optional runtime type for this variable in the template engine. Type used to coerce a prompt variable before placing it in the template context. It determines creation-time validation, the authoring control, and how comparisons and joining values behave.
| Value | No. | Form | Meaning | |---|---|---|---| | `VAR_TYPE_STRING` | 0 | Canonical | Treat the variable as text in the template context. | | `VAR_TYPE_NUMBER` | 1 | Canonical | See meaning below. | | `VAR_TYPE_BOOL` | 2 | Canonical | See meaning below. | | `VAR_TYPE_LIST` | 3 | Canonical | See meaning below. | **`VAR_TYPE_NUMBER`** Coerce the variable to a numeric value for arithmetic or numeric comparisons. float64 in the template context (gt/lt/ge…) **`VAR_TYPE_BOOL`** Coerce the variable to a boolean for template conditions. truthiness in \{\{if …}} **`VAR_TYPE_LIST`** Provide a list that templates can iterate or join. \[]interface\{} — joinable, rangeable
Exactly one of: Variant 1: Type: `string` Enum: `VAR_TYPE_STRING`, `VAR_TYPE_NUMBER`, `VAR_TYPE_BOOL`, `VAR_TYPE_LIST` Variant 2: Type: `integer(int32)` **version** `string(int64)` Output-only immutable revision of the profile. Versions start at one and increase on successful mutations; values supplied on writes are ignored. Pattern: ^-?\d+$ #### agent-profiles-createAgentProfile-request Create a reusable support profile; choose a new profileId in your project. ```json { "profile": { "profileId": "support-assistant", "name": "Support assistant", "whenToUse": "Help users answer product questions.", "generationConfig": { "systemPrompt": "Answer clearly using the supplied product information." } } } ``` #### cookbook-managed-agents-profiles-prompts-index-01-request Guide request for Step 1: Save the assistant instructions. Replace example resource identifiers with your own authorized values. ```json { "profile": { "profileId": "nutrition_coach", "name": "Nutrition Coach", "description": "Food, meals and macros.", "whenToUse": "Use when the user asks about food, meals, or macros.", "keywords": [ "nutrition", "food", "macros" ], "enabled": true, "generationConfig": { "model": "YOUR_MODEL_ID", "systemPrompt": "You are a nutrition coach. Be concise and practical.", "temperature": 0.4 } } } ``` ## Responses ### 200 — Profile created; the stored record is echoed back Content type: `application/json` Result payload for creating a project-scoped agent profile with prompt and generation settings. **profile** `any` Echoes the stored profile. All of: Variant 1: A reusable persona with model configuration, tools and metadata describing when it should be selected. See the profile-selection and versioning guide for profile resolution and fragment versions. Model reference: [AgentProfile](/api/models/schema-1hmbcecg1j#response). **profileId** `string` Stable id, unique within the project library. **name** `string` Display name used when selecting an agent profile. e.g. "Nutrition Coach" **description** `string` Human-facing summary. **whenToUse** `string` Routing hint, Skill-style "use when…" **keywords** `array[string]` Keywords associated with discovery or selection of the agent profile. Type: `string` **enabled** `boolean` Whether the profile is enabled for selection. Omission during creation defaults to true; an explicitly false value creates a disabled profile. Disabled profiles are not selectable. **generationConfig** `any` Model, sampling, and tool configuration used for generation. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#response). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#response). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#response). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#response). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#response). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#response). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#response). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinition]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#response). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfig]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#response). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#response). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#response). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#response). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#response). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#response). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#response). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#response). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **mcpServers** `array[llm_v1_common_v1_MCPServerReference]` MCP servers used for tool discovery when this profile is active. This list replaces the conversation-wide MCP server list for those turns. MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#response). **serverId** `string` ID of pre-configured MCP server (e.g., "github", "filesystem"). **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **variableSpecs** `array[llm_v1_common_v1_PromptVariableSpec]` Variables consumed by the profile’s system-prompt template, rendered from the conversation’s prompt\_variables. Declares a variable used by a profile’s system-prompt template. Values are supplied through the conversation’s prompt\_variables. When creating a conversation with an explicitly selected profile, a variable\_specs entry with required set to true and no nonempty default\_value causes MISSING\_REQUIRED\_PROMPT\_VARIABLES if the variable is missing. Supply its value at creation; this validation is not repeated for each send or queued turn. Set intended values explicitly even when the specification declares a default. A nonempty default\_value suppresses the creation-time missing-required error but is not automatically inserted into the rendered prompt. Model reference: [PromptVariableSpec](/api/models/schema-1hkadmq6cl#response). **name** `string` Variable name referenced by the profile’s system-prompt template. e.g. "user\_name" → substituted for \{\{.user\_name}} **description** `string` Console hint + caller documentation. **required** `boolean` Whether a value is required for a profile explicitly selected at conversation creation. This validation does not run for every send or queued turn. **defaultValue** `string` A nonempty default value suppresses the creation-time missing-required error. It is not automatically inserted into the rendered prompt; supply intended values explicitly. **type** `any` Optional runtime type for this variable in the template engine. Type used to coerce a prompt variable before placing it in the template context. It determines creation-time validation, the authoring control, and how comparisons and joining values behave.
| Value | No. | Form | Meaning | |---|---|---|---| | `VAR_TYPE_STRING` | 0 | Canonical | Treat the variable as text in the template context. | | `VAR_TYPE_NUMBER` | 1 | Canonical | See meaning below. | | `VAR_TYPE_BOOL` | 2 | Canonical | See meaning below. | | `VAR_TYPE_LIST` | 3 | Canonical | See meaning below. | **`VAR_TYPE_NUMBER`** Coerce the variable to a numeric value for arithmetic or numeric comparisons. float64 in the template context (gt/lt/ge…) **`VAR_TYPE_BOOL`** Coerce the variable to a boolean for template conditions. truthiness in \{\{if …}} **`VAR_TYPE_LIST`** Provide a list that templates can iterate or join. \[]interface\{} — joinable, rangeable
Exactly one of: Variant 1: Type: `string` Enum: `VAR_TYPE_STRING`, `VAR_TYPE_NUMBER`, `VAR_TYPE_BOOL`, `VAR_TYPE_LIST` Variant 2: Type: `integer(int32)` **version** `string(int64)` Output-only immutable revision of the profile. Versions start at one and increase on successful mutations; values supplied on writes are ignored. Pattern: ^-?\d+$ #### agent-profiles-createAgentProfile-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "profile": { "profileId": "example_123", "name": "example", "description": "example", "whenToUse": "example", "keywords": [ "example_123" ], "enabled": true, "generationConfig": { "model": "example", "models": [ "example" ], "systemPrompt": "Example text", "transforms": [ "example" ], "temperature": 1, "topP": 1, "maxOutputTokens": 1, "frequencyPenalty": 1, "presencePenalty": 1, "stopSequences": [ "example" ], "seed": "1", "allowParallelToolCalls": true, "topK": 1, "repetitionPenalty": 1, "topLogprobs": 1, "minP": 1, "topA": 1, "user": "example", "modalities": [ "MODALITY_TEXT" ], "languagePreference": "en-US", "requestTimeoutSeconds": 1, "clearTools": true }, "mcpServers": [ { "serverId": "example_123", "enabled": true, "priority": 1, "allowlistToolPatterns": [ "example" ], "blocklistToolPatterns": [ "example" ] } ], "variableSpecs": [ { "name": "example", "description": "example", "required": true, "defaultValue": "example", "type": "VAR_TYPE_STRING" } ], "version": 1 } } ``` #### cookbook-managed-agents-profiles-prompts-index-json-01-response Illustrative response for Step 1: Save the assistant instructions. Replace example resource identifiers with your own authorized values. ```json { "profile": { "profileId": "nutrition_coach", "name": "Nutrition Coach", "description": "Food, meals and macros.", "whenToUse": "Use when the user asks about food, meals, or macros.", "keywords": [ "nutrition", "food", "macros" ], "enabled": true, "generationConfig": { "model": "YOUR_MODEL_ID", "systemPrompt": "You are a nutrition coach. Be concise and practical.", "temperature": 0.4 }, "version": 1 } } ``` Document ID: `DOC-MA-profiles-prompts-api-createAgentProfile`. [Section identities and revisions](/documentation-manifest.json). - Create an agent profile: `DOC-MA-profiles-prompts-api-createAgentProfile#overview` - Request: `DOC-MA-profiles-prompts-api-createAgentProfile#request` - Responses: `DOC-MA-profiles-prompts-api-createAgentProfile#responses` --- # Create a prompt fragment URL: https://docs.travila.ai/api/agent-profiles/create-prompt-fragment **POST** `/api/v1/prompt-fragments/create` Creates a reusable template block in the caller's project. The fragment ID must be unique within that project. Profiles that include the fragment share the stored text, so a later edit affects every referencing profile. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Reuse and update shared assistant instructions](/managed-agents/profiles-prompts/prompt-fragments) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for creating a reusable block of prompt-template text in the project library. **projectId** `string` Project whose prompt library receives the fragment. If omitted, the operation uses `default`. **fragment** `any` **required** Reusable prompt fragment definition to add to the project library. All of: Variant 1: Project-scoped reusable prompt-template text. Profiles and other fragments include it with `{{template "fragment_id" .}}`; variables come from the conversation’s prompt\_variables. Model reference: [PromptFragment](/api/models/schema-1j5dvgfmr9#request). **fragmentId** `string` Stable template name, unique within the project library and used by include actions. **name** `string` Display name used as a console hint for the reusable prompt fragment. **content** `string` Raw template text, supporting `{{.variable}}` placeholders and nested `{{template "id" .}}` includes. #### agent-profiles-createPromptFragment-request Create a reusable prompt fragment with a new fragmentId. ```json { "fragment": { "fragmentId": "answer-style", "name": "Answer style", "content": "Use short paragraphs and explain any assumptions." } } ``` #### cookbook-managed-agents-profiles-prompts-prompt-fragments-01-request Guide request for Step 1: Create the block and include it in the profile. Replace example resource identifiers with your own authorized values. ```json { "fragment": { "fragmentId": "safety", "name": "Safety rules", "content": "Never give medical advice. Refer the user to a clinician when asked." } } ``` ## Responses ### 200 — Fragment created; the stored record is echoed back Content type: `application/json` Result payload for creating a reusable block of prompt-template text in the project library. **fragment** `any` Echoes the stored fragment. All of: Variant 1: Project-scoped reusable prompt-template text. Profiles and other fragments include it with `{{template "fragment_id" .}}`; variables come from the conversation’s prompt\_variables. Model reference: [PromptFragment](/api/models/schema-1j5dvgfmr9#response). **fragmentId** `string` Stable template name, unique within the project library and used by include actions. **name** `string` Display name used as a console hint for the reusable prompt fragment. **content** `string` Raw template text, supporting `{{.variable}}` placeholders and nested `{{template "id" .}}` includes. #### agent-profiles-createPromptFragment-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "fragment": { "fragmentId": "example_123", "name": "example", "content": "Example text" } } ``` #### cookbook-managed-agents-profiles-prompts-prompt-fragments-json-01-response Illustrative response for Step 1: Create the block and include it in the profile. Replace example resource identifiers with your own authorized values. ```json { "fragment": { "fragmentId": "safety", "name": "Safety rules", "content": "Never give medical advice. Refer the user to a clinician when asked." } } ``` Document ID: `DOC-MA-profiles-prompts-api-createPromptFragment`. [Section identities and revisions](/documentation-manifest.json). - Create a prompt fragment: `DOC-MA-profiles-prompts-api-createPromptFragment#overview` - Request: `DOC-MA-profiles-prompts-api-createPromptFragment#request` - Responses: `DOC-MA-profiles-prompts-api-createPromptFragment#responses` --- # Delete an agent profile URL: https://docs.travila.ai/api/agent-profiles/delete-agent-profile **POST** `/api/v1/agent-profiles/delete` Deletes the profile from the current library without checking whether conversations still reference it. Resolve dependent conversations before deletion. * Direct sends on conversations still naming it in [`activeProfileId`](/api/conversations/create-thread#request-field-activeprofileid) fail with `ACTIVE_PROFILE_NOT_FOUND`. Select an enabled replacement or restore the profile. A disabled replacement fails with `ACTIVE_PROFILE_DISABLED`. Queued messages can fall back to defaults and log the problem; see [unusable profiles](/managed-agents/conversations/configuration#when-the-active-profile-cannot-be-used). * Historical version records remain. Their retention does not prove that every dependent turn remains reproducible. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build a reusable assistant profile](/managed-agents/profiles-prompts) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for removing an agent profile from the project library. **projectId** `string` Identifier of the project associated with the operation. **profileId** `string` **required** Identifier of the agent profile associated with the operation or generation. Minimum length: 1 #### agent-profiles-deleteAgentProfile-request Use the profileId of an existing profile in your project. ```json { "profileId": "support-assistant" } ``` #### cookbook-managed-agents-profiles-prompts-index-07-request Guide request for Retire an assistant without stranding its conversations. Replace example resource identifiers with your own authorized values. ```json { "profileId": "nutrition_coach" } ``` ## Responses ### 200 — Profile deleted Content type: `application/json` Response schema for removing an agent profile from the project library; no response fields are declared. #### agent-profiles-deleteAgentProfile-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json {} ``` Document ID: `DOC-MA-profiles-prompts-api-deleteAgentProfile`. [Section identities and revisions](/documentation-manifest.json). - Delete an agent profile: `DOC-MA-profiles-prompts-api-deleteAgentProfile#overview` - Request: `DOC-MA-profiles-prompts-api-deleteAgentProfile#request` - Responses: `DOC-MA-profiles-prompts-api-deleteAgentProfile#responses` --- # Delete a prompt fragment URL: https://docs.travila.ai/api/agent-profiles/delete-prompt-fragment **POST** `/api/v1/prompt-fragments/delete` Deletes a fragment from the current set. The renderer reports missing fragments and other reachable-template errors; its caller can then return the original prompt. **Deleting does not rewrite the profiles that include it** A missing fragment can leave the system prompt unrendered, so literal `{{template "safety" .}}` text reaches the model. Generation may continue with that raw template; this is not a validated or safe fallback, and a successful response does not prove that the intended instructions were rendered. Other failures can still stop the turn. Check dependencies before removal: page through all profiles and inspect their [`generationConfig.systemPrompt`](/api/models/schema-1h82h7ri5p#request-field-systemprompt) values, then check nested fragment includes too. Checking one page or only direct includes can miss a dependent profile. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Reuse and update shared assistant instructions](/managed-agents/profiles-prompts/prompt-fragments) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for removing a reusable prompt fragment from the project library. **projectId** `string` Identifier of the project associated with the operation. **fragmentId** `string` **required** Identifier of the reusable prompt fragment. Minimum length: 1 #### agent-profiles-deletePromptFragment-request Use the fragmentId of an existing prompt fragment in your project. ```json { "fragmentId": "answer-style" } ``` #### cookbook-managed-agents-profiles-prompts-prompt-fragments-06-request Guide request for Retire a shared block without leaving broken includes. Replace example resource identifiers with your own authorized values. ```json { "fragmentId": "safety" } ``` ## Responses ### 200 — Fragment deleted Content type: `application/json` Response schema for removing a reusable prompt fragment from the project library; no response fields are declared. #### agent-profiles-deletePromptFragment-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json {} ``` Document ID: `DOC-MA-profiles-prompts-api-deletePromptFragment`. [Section identities and revisions](/documentation-manifest.json). - Delete a prompt fragment: `DOC-MA-profiles-prompts-api-deletePromptFragment#overview` - Request: `DOC-MA-profiles-prompts-api-deletePromptFragment#request` - Responses: `DOC-MA-profiles-prompts-api-deletePromptFragment#responses` --- # Get the profile library URL: https://docs.travila.ai/api/agent-profiles/get-agent-profile-library **POST** `/api/v1/agent-profiles/library` Returns the project's profile-selection library for building a picker. Its selection metadata omits runtime configuration; use [get](/api/agent-profiles/get-agent-profile) to inspect or edit a full profile. This discovery projection neither proves that an autonomous router is active nor guarantees a measured cost or latency improvement. For a native conversation, pass the chosen profile ID through `activeProfileId` on thread creation or `setActiveProfileId` when sending a message; Travila loads its configuration. The returned `defaultProfileId` is not applied automatically when `activeProfileId` is empty. Your client must explicitly select its intended profile. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build a reusable assistant profile](/managed-agents/profiles-prompts) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for reading profile metadata available for discovery in the project library. **projectId** `string` Identifier of the project associated with the operation. `default` identifies the default project. #### agent-profiles-getAgentProfileLibrary-request Read the enabled profile library in the authenticated project; no additional body fields are needed. ```json {} ``` ## Responses ### 200 — Selection metadata for the project Content type: `application/json` Result payload for reading profile metadata available for discovery in the project library. **library** `any` Profile identity and selection metadata for the project. All of: Variant 1: Selection metadata for the project’s agent profiles. Retrieve an individual profile to read its complete model and tool configuration. Model reference: [AgentProfileLibrary](/api/models/schema-ou55jqfkih#response). **profiles** `array[llm_v1_common_v1_AgentProfileMetadata]` Profile identity and selection metadata. Full configurations are retrieved individually with GetAgentProfile. Profile identity and selection hints for a picker or router. This projection excludes the system prompt, generation settings, tools and MCP configuration; retrieve AgentProfile to inspect the runtime configuration. These hints do not establish that routing is active. Model reference: [AgentProfileMetadata](/api/models/schema-ohmse4h323#response). **profileId** `string` Identifier of the agent profile associated with the operation or generation. **name** `string` Display name used when presenting an agent profile in the library. **description** `string` Human-readable description of the resource. **whenToUse** `string` Instructions describing when this agent profile should be selected. **keywords** `array[string]` Keywords associated with discovery or selection of the agent profile. Type: `string` **enabled** `boolean` Whether this configuration is enabled. **defaultProfileId** `string` Project's nominated default profile. Native conversations do not automatically apply it when active\_profile\_id is empty; the client must explicitly select its intended profile. #### agent-profiles-getAgentProfileLibrary-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "library": { "profiles": [ { "profileId": "example_123", "name": "example", "description": "example", "whenToUse": "example", "keywords": [ "example_123" ], "enabled": true } ], "defaultProfileId": "example_123" } } ``` #### cookbook-managed-agents-profiles-prompts-index-json-04-response Illustrative response for Variant: let the user choose an assistant. Replace example resource identifiers with your own authorized values. ```json { "library": { "profiles": [ { "profileId": "nutrition_coach", "name": "Nutrition Coach", "description": "Food, meals and macros.", "whenToUse": "Use when the user asks about food, meals, or macros.", "keywords": [ "nutrition", "food", "macros" ], "enabled": true } ], "defaultProfileId": "generalist" } } ``` Document ID: `DOC-MA-profiles-prompts-api-getAgentProfileLibrary`. [Section identities and revisions](/documentation-manifest.json). - Get the profile library: `DOC-MA-profiles-prompts-api-getAgentProfileLibrary#overview` - Request: `DOC-MA-profiles-prompts-api-getAgentProfileLibrary#request` - Responses: `DOC-MA-profiles-prompts-api-getAgentProfileLibrary#responses` --- # Get an agent profile URL: https://docs.travila.ai/api/agent-profiles/get-agent-profile **POST** `/api/v1/agent-profiles/get` Returns a full profile record at the selected immutable version. A profile or version that never existed returns `NOT_FOUND`. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build a reusable assistant profile](/managed-agents/profiles-prompts) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for retrieving a selected agent profile and its configuration. **projectId** `string` Identifier of the project associated with the operation. **profileId** `string` **required** Identifier of the agent profile associated with the operation or generation. Minimum length: 1 **version** `string(int64)` Immutable profile version to retrieve. Zero or omission selects the latest version. A requested version that does not exist returns NOT\_FOUND. Pattern: ^-?\d+$ #### agent-profiles-getAgentProfile-request Use the profileId of an existing profile in your project. ```json { "profileId": "support-assistant" } ``` #### cookbook-managed-agents-profiles-prompts-index-02-request Guide request for Step 2: Confirm what you saved. Replace example resource identifiers with your own authorized values. ```json { "profileId": "nutrition_coach" } ``` #### cookbook-managed-agents-profiles-prompts-index-json-02-request Guide request for Step 2: Confirm what you saved. Replace example resource identifiers with your own authorized values. ```json { "profileId": "nutrition_coach", "version": 3 } ``` ## Responses ### 200 — Profile returned Content type: `application/json` Result payload for retrieving a selected agent profile and its configuration. **profile** `any` Agent profile returned by the operation. All of: Variant 1: A reusable persona with model configuration, tools and metadata describing when it should be selected. See the profile-selection and versioning guide for profile resolution and fragment versions. Model reference: [AgentProfile](/api/models/schema-1hmbcecg1j#response). **profileId** `string` Stable id, unique within the project library. **name** `string` Display name used when selecting an agent profile. e.g. "Nutrition Coach" **description** `string` Human-facing summary. **whenToUse** `string` Routing hint, Skill-style "use when…" **keywords** `array[string]` Keywords associated with discovery or selection of the agent profile. Type: `string` **enabled** `boolean` Whether the profile is enabled for selection. Omission during creation defaults to true; an explicitly false value creates a disabled profile. Disabled profiles are not selectable. **generationConfig** `any` Model, sampling, and tool configuration used for generation. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#response). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#response). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#response). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#response). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#response). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#response). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#response). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinition]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#response). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfig]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#response). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#response). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#response). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#response). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#response). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#response). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#response). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#response). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **mcpServers** `array[llm_v1_common_v1_MCPServerReference]` MCP servers used for tool discovery when this profile is active. This list replaces the conversation-wide MCP server list for those turns. MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#response). **serverId** `string` ID of pre-configured MCP server (e.g., "github", "filesystem"). **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **variableSpecs** `array[llm_v1_common_v1_PromptVariableSpec]` Variables consumed by the profile’s system-prompt template, rendered from the conversation’s prompt\_variables. Declares a variable used by a profile’s system-prompt template. Values are supplied through the conversation’s prompt\_variables. When creating a conversation with an explicitly selected profile, a variable\_specs entry with required set to true and no nonempty default\_value causes MISSING\_REQUIRED\_PROMPT\_VARIABLES if the variable is missing. Supply its value at creation; this validation is not repeated for each send or queued turn. Set intended values explicitly even when the specification declares a default. A nonempty default\_value suppresses the creation-time missing-required error but is not automatically inserted into the rendered prompt. Model reference: [PromptVariableSpec](/api/models/schema-1hkadmq6cl#response). **name** `string` Variable name referenced by the profile’s system-prompt template. e.g. "user\_name" → substituted for \{\{.user\_name}} **description** `string` Console hint + caller documentation. **required** `boolean` Whether a value is required for a profile explicitly selected at conversation creation. This validation does not run for every send or queued turn. **defaultValue** `string` A nonempty default value suppresses the creation-time missing-required error. It is not automatically inserted into the rendered prompt; supply intended values explicitly. **type** `any` Optional runtime type for this variable in the template engine. Type used to coerce a prompt variable before placing it in the template context. It determines creation-time validation, the authoring control, and how comparisons and joining values behave.
| Value | No. | Form | Meaning | |---|---|---|---| | `VAR_TYPE_STRING` | 0 | Canonical | Treat the variable as text in the template context. | | `VAR_TYPE_NUMBER` | 1 | Canonical | See meaning below. | | `VAR_TYPE_BOOL` | 2 | Canonical | See meaning below. | | `VAR_TYPE_LIST` | 3 | Canonical | See meaning below. | **`VAR_TYPE_NUMBER`** Coerce the variable to a numeric value for arithmetic or numeric comparisons. float64 in the template context (gt/lt/ge…) **`VAR_TYPE_BOOL`** Coerce the variable to a boolean for template conditions. truthiness in \{\{if …}} **`VAR_TYPE_LIST`** Provide a list that templates can iterate or join. \[]interface\{} — joinable, rangeable
Exactly one of: Variant 1: Type: `string` Enum: `VAR_TYPE_STRING`, `VAR_TYPE_NUMBER`, `VAR_TYPE_BOOL`, `VAR_TYPE_LIST` Variant 2: Type: `integer(int32)` **version** `string(int64)` Output-only immutable revision of the profile. Versions start at one and increase on successful mutations; values supplied on writes are ignored. Pattern: ^-?\d+$ #### agent-profiles-getAgentProfile-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "profile": { "profileId": "example_123", "name": "example", "description": "example", "whenToUse": "example", "keywords": [ "example_123" ], "enabled": true, "generationConfig": { "model": "example", "models": [ "example" ], "systemPrompt": "Example text", "transforms": [ "example" ], "temperature": 1, "topP": 1, "maxOutputTokens": 1, "frequencyPenalty": 1, "presencePenalty": 1, "stopSequences": [ "example" ], "seed": "1", "allowParallelToolCalls": true, "topK": 1, "repetitionPenalty": 1, "topLogprobs": 1, "minP": 1, "topA": 1, "user": "example", "modalities": [ "MODALITY_TEXT" ], "languagePreference": "en-US", "requestTimeoutSeconds": 1, "clearTools": true }, "mcpServers": [ { "serverId": "example_123", "enabled": true, "priority": 1, "allowlistToolPatterns": [ "example" ], "blocklistToolPatterns": [ "example" ] } ], "variableSpecs": [ { "name": "example", "description": "example", "required": true, "defaultValue": "example", "type": "VAR_TYPE_STRING" } ], "version": 1 } } ``` Document ID: `DOC-MA-profiles-prompts-api-getAgentProfile`. [Section identities and revisions](/documentation-manifest.json). - Get an agent profile: `DOC-MA-profiles-prompts-api-getAgentProfile#overview` - Request: `DOC-MA-profiles-prompts-api-getAgentProfile#request` - Responses: `DOC-MA-profiles-prompts-api-getAgentProfile#responses` --- # Get a fragment set by version URL: https://docs.travila.ai/api/agent-profiles/get-prompt-fragment-set **POST** `/api/v1/prompt-fragments/get-set` Returns the fragments in a specified project-wide fragment-set version, ordered by fragment ID. Fragment writes advance the set version. A set version reconstructs that stored set, not a complete rendered turn. Current profile and fragment reads are independent and rendering can use the latest set; capture the set actually used alongside variables and effective configuration. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Reuse and update shared assistant instructions](/managed-agents/profiles-prompts/prompt-fragments) · [Profile selection and prompt versions](/api/agent-profiles/selection-and-versioning) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for reading an immutable version of the project’s prompt-fragment set. **projectId** `string` Identifier of the project associated with the operation. **setVersion** `string(int64)` **required** Version identifying the immutable prompt-fragment set. Pattern: ^-?\d+$ #### agent-profiles-getPromptFragmentSet-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "setVersion": 1 } ``` #### cookbook-managed-agents-profiles-prompts-prompt-fragments-05-request Guide request for Recover the text used before a change. Replace example resource identifiers with your own authorized values. ```json { "setVersion": 7 } ``` ## Responses ### 200 — Fragments at that set version Content type: `application/json` Result payload for reading an immutable version of the project’s prompt-fragment set. **setVersion** `string(int64)` Version identifying the immutable prompt-fragment set. Pattern: ^-?\d+$ **fragments** `array[llm_v1_common_v1_PromptFragment]` Ordered by fragment\_id. Project-scoped reusable prompt-template text. Profiles and other fragments include it with `{{template "fragment_id" .}}`; variables come from the conversation’s prompt\_variables. Model reference: [PromptFragment](/api/models/schema-1j5dvgfmr9#response). **fragmentId** `string` Stable template name, unique within the project library and used by include actions. **name** `string` Display name used as a console hint for the reusable prompt fragment. **content** `string` Raw template text, supporting `{{.variable}}` placeholders and nested `{{template "id" .}}` includes. #### agent-profiles-getPromptFragmentSet-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "setVersion": 1, "fragments": [ { "fragmentId": "example_123", "name": "example", "content": "Example text" } ] } ``` #### cookbook-managed-agents-profiles-prompts-prompt-fragments-json-04-response Illustrative response for Recover the text used before a change. Replace example resource identifiers with your own authorized values. ```json { "setVersion": 7, "fragments": [ { "fragmentId": "safety", "name": "Safety rules", "content": "Never give medical advice. Refer the user to a clinician when asked." } ] } ``` Document ID: `DOC-MA-profiles-prompts-api-getPromptFragmentSet`. [Section identities and revisions](/documentation-manifest.json). - Get a fragment set by version: `DOC-MA-profiles-prompts-api-getPromptFragmentSet#overview` - Request: `DOC-MA-profiles-prompts-api-getPromptFragmentSet#request` - Responses: `DOC-MA-profiles-prompts-api-getPromptFragmentSet#responses` --- # Get a prompt fragment URL: https://docs.travila.ai/api/agent-profiles/get-prompt-fragment **POST** `/api/v1/prompt-fragments/get` Returns one fragment by id. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Reuse and update shared assistant instructions](/managed-agents/profiles-prompts/prompt-fragments) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for retrieving a reusable prompt fragment by its identifier. **projectId** `string` Identifier of the project associated with the operation. **fragmentId** `string` **required** Identifier of the reusable prompt fragment. Minimum length: 1 #### agent-profiles-getPromptFragment-request Use the fragmentId of an existing prompt fragment in your project. ```json { "fragmentId": "answer-style" } ``` #### cookbook-managed-agents-profiles-prompts-prompt-fragments-02-request Guide request for Step 2: Check the sources and record their set version. Replace example resource identifiers with your own authorized values. ```json { "fragmentId": "safety" } ``` ## Responses ### 200 — Fragment returned Content type: `application/json` Result payload for retrieving a reusable prompt fragment by its identifier. **fragment** `any` Reusable prompt fragment returned by the operation. All of: Variant 1: Project-scoped reusable prompt-template text. Profiles and other fragments include it with `{{template "fragment_id" .}}`; variables come from the conversation’s prompt\_variables. Model reference: [PromptFragment](/api/models/schema-1j5dvgfmr9#response). **fragmentId** `string` Stable template name, unique within the project library and used by include actions. **name** `string` Display name used as a console hint for the reusable prompt fragment. **content** `string` Raw template text, supporting `{{.variable}}` placeholders and nested `{{template "id" .}}` includes. #### agent-profiles-getPromptFragment-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "fragment": { "fragmentId": "example_123", "name": "example", "content": "Example text" } } ``` Document ID: `DOC-MA-profiles-prompts-api-getPromptFragment`. [Section identities and revisions](/documentation-manifest.json). - Get a prompt fragment: `DOC-MA-profiles-prompts-api-getPromptFragment#overview` - Request: `DOC-MA-profiles-prompts-api-getPromptFragment#request` - Responses: `DOC-MA-profiles-prompts-api-getPromptFragment#responses` --- # Import a prompt library URL: https://docs.travila.ai/api/agent-profiles/import-agent-profiles **POST** `/api/v1/agent-profiles/import` Bulk-converts a source prompt library into profiles and reusable fragments. Conversion happens at import time: prompts are rewritten to the platform template syntax and variable specifications are derived from usage. The platform never interprets the source DSL when serving a turn. Existing rows cause the import to stop at the first conflict with `ALREADY_EXISTS`, unless overwrite is enabled. In overwrite mode, existing profiles and fragments are replaced. Writes apply fragments before profiles and are not atomic across rows: a later failure can leave earlier writes in place. Re-read the library and reconcile it before retrying. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build a reusable assistant profile](/managed-agents/profiles-prompts) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for converting a source prompt library into project profiles. Every shared block referenced by an include must be supplied in fragments so the importer can resolve the library. **projectId** `string` Identifier of the project associated with the operation. **templates** `array[llm_v1_common_v1_SourcePromptTemplate]` Source persona templates to convert into conversational agent profiles. Source persona template to convert into an agent profile during import. Its source\_dsl contains the original template syntax from which the importer derives the profile template and variable specifications. Model reference: [SourcePromptTemplate](/api/models/schema-pjk9r8rn5b#request). **profileId** `string` Identifier of the agent profile associated with the operation or generation. **name** `string` Display name for the imported agent profile. **whenToUse** `string` Instructions describing when the imported agent profile should be selected. **keywords** `array[string]` Keywords associated with selection of the imported agent profile. Type: `string` **sourceDsl** `string` Raw source-DSL system prompt. **generationConfig** `any` Generation settings other than the prompt, such as temperature. Must not set model or models: import refuses a template that does, and the model is set afterwards with UpdateAgentProfile. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#request). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#request). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#request). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#request). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#request). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#request). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinitionInput]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#request). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinitionInput]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRuleInput]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#request). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#request). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#request). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRuleInput]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#request). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#request). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfigInput]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#request). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#request). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#request). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#request). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) Minimum length: 2 Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$ **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#request). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" Maximum length: 50 **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" Enum: ``, `friendly`, `iso8601`, `date_only` Maximum length: 50 **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#request). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` **required** Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" Enum: `minimal`, `standard`, `verbose` **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#request). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#request). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **fragments** `array[llm_v1_common_v1_SourcePromptFragment]` Shared @include blocks. Shared template block supplied for import. Its path resolves source include directives; fragment\_id supplies the stable output identity when shared fragments are emitted, or is derived from the path when omitted. Model reference: [SourcePromptFragment](/api/models/schema-ohqh497pal#request). **fragmentId** `string` Identifier of the reusable prompt fragment. **name** `string` Display name for the imported reusable prompt fragment. **sourceDsl** `string` Raw source text (may itself contain @include / metadata comments). **path** `string` Include path, e.g. "\_shared/safety-module.txt" **variableTypes** `map[string, any]` Optional variable type hints that override types inferred from template usage. Map values: Type used to coerce a prompt variable before placing it in the template context. It determines creation-time validation, the authoring control, and how comparisons and joining values behave. Type used to coerce a prompt variable before placing it in the template context. It determines creation-time validation, the authoring control, and how comparisons and joining values behave.
| Value | No. | Form | Meaning | |---|---|---|---| | `VAR_TYPE_STRING` | 0 | Canonical | Treat the variable as text in the template context. | | `VAR_TYPE_NUMBER` | 1 | Canonical | See meaning below. | | `VAR_TYPE_BOOL` | 2 | Canonical | See meaning below. | | `VAR_TYPE_LIST` | 3 | Canonical | See meaning below. | **`VAR_TYPE_NUMBER`** Coerce the variable to a numeric value for arithmetic or numeric comparisons. float64 in the template context (gt/lt/ge…) **`VAR_TYPE_BOOL`** Coerce the variable to a boolean for template conditions. truthiness in \{\{if …}} **`VAR_TYPE_LIST`** Provide a list that templates can iterate or join. \[]interface\{} — joinable, rangeable
Exactly one of: Variant 1: Type: `string` Enum: `VAR_TYPE_STRING`, `VAR_TYPE_NUMBER`, `VAR_TYPE_BOOL`, `VAR_TYPE_LIST` Variant 2: Type: `integer(int32)` **overwrite** `boolean` Update existing profiles and fragments instead of failing ALREADY\_EXISTS. An existing profile takes the imported prompt, variable specs, name, when\_to\_use, keywords and the generation settings the template sets; its model, MCP servers, description and enabled state are kept. **emitFragments** `boolean` When false, the default, resolve source includes inline into each profile’s system prompt without writing shared fragment rows. When true, emit supplied shared blocks as prompt fragments and reference them through template actions; every referenced shared block must be supplied. #### agent-profiles-importAgentProfiles-request Import one source template as a new profile; use overwrite only when replacement is intended. ```json { "templates": [ { "profileId": "support-assistant", "name": "Support assistant", "whenToUse": "Help users answer product questions.", "sourceDsl": "Answer clearly using the supplied product information." } ] } ``` #### cookbook-managed-agents-profiles-prompts-index-08-request Guide request for Variant: migrate an existing prompt library. Replace example resource identifiers with your own authorized values. ```json { "templates": [ { "profileId": "nutrition_coach", "name": "Nutrition Coach", "whenToUse": "Use when the user asks about food, meals, or macros.", "keywords": [ "nutrition" ], "sourceDsl": "@include _shared/safety.txt\n\nYou are a nutrition coach for {{user_name}}.", "generationConfig": { "model": "YOUR_MODEL_ID" } } ], "fragments": [ { "fragmentId": "safety", "name": "Safety rules", "path": "_shared/safety.txt", "sourceDsl": "Never give medical advice." } ], "emitFragments": true } ``` ## Responses ### 200 — Converted profiles and fragments, as stored Content type: `application/json` Result payload for converting and importing source prompt templates into project agent profiles. **profiles** `array[llm_v1_common_v1_AgentProfile]` Converted + stored (echo). A reusable persona with model configuration, tools and metadata describing when it should be selected. See the profile-selection and versioning guide for profile resolution and fragment versions. Model reference: [AgentProfile](/api/models/schema-1hmbcecg1j#response). **profileId** `string` Stable id, unique within the project library. **name** `string` Display name used when selecting an agent profile. e.g. "Nutrition Coach" **description** `string` Human-facing summary. **whenToUse** `string` Routing hint, Skill-style "use when…" **keywords** `array[string]` Keywords associated with discovery or selection of the agent profile. Type: `string` **enabled** `boolean` Whether the profile is enabled for selection. Omission during creation defaults to true; an explicitly false value creates a disabled profile. Disabled profiles are not selectable. **generationConfig** `any` Model, sampling, and tool configuration used for generation. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#response). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#response). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#response). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#response). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#response). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#response). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#response). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinition]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#response). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfig]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#response). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#response). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#response). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#response). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#response). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#response). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#response). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#response). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **mcpServers** `array[llm_v1_common_v1_MCPServerReference]` MCP servers used for tool discovery when this profile is active. This list replaces the conversation-wide MCP server list for those turns. MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#response). **serverId** `string` ID of pre-configured MCP server (e.g., "github", "filesystem"). **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **variableSpecs** `array[llm_v1_common_v1_PromptVariableSpec]` Variables consumed by the profile’s system-prompt template, rendered from the conversation’s prompt\_variables. Declares a variable used by a profile’s system-prompt template. Values are supplied through the conversation’s prompt\_variables. When creating a conversation with an explicitly selected profile, a variable\_specs entry with required set to true and no nonempty default\_value causes MISSING\_REQUIRED\_PROMPT\_VARIABLES if the variable is missing. Supply its value at creation; this validation is not repeated for each send or queued turn. Set intended values explicitly even when the specification declares a default. A nonempty default\_value suppresses the creation-time missing-required error but is not automatically inserted into the rendered prompt. Model reference: [PromptVariableSpec](/api/models/schema-1hkadmq6cl#response). **name** `string` Variable name referenced by the profile’s system-prompt template. e.g. "user\_name" → substituted for \{\{.user\_name}} **description** `string` Console hint + caller documentation. **required** `boolean` Whether a value is required for a profile explicitly selected at conversation creation. This validation does not run for every send or queued turn. **defaultValue** `string` A nonempty default value suppresses the creation-time missing-required error. It is not automatically inserted into the rendered prompt; supply intended values explicitly. **type** `any` Optional runtime type for this variable in the template engine. Type used to coerce a prompt variable before placing it in the template context. It determines creation-time validation, the authoring control, and how comparisons and joining values behave.
| Value | No. | Form | Meaning | |---|---|---|---| | `VAR_TYPE_STRING` | 0 | Canonical | Treat the variable as text in the template context. | | `VAR_TYPE_NUMBER` | 1 | Canonical | See meaning below. | | `VAR_TYPE_BOOL` | 2 | Canonical | See meaning below. | | `VAR_TYPE_LIST` | 3 | Canonical | See meaning below. | **`VAR_TYPE_NUMBER`** Coerce the variable to a numeric value for arithmetic or numeric comparisons. float64 in the template context (gt/lt/ge…) **`VAR_TYPE_BOOL`** Coerce the variable to a boolean for template conditions. truthiness in \{\{if …}} **`VAR_TYPE_LIST`** Provide a list that templates can iterate or join. \[]interface\{} — joinable, rangeable
Exactly one of: Variant 1: Type: `string` Enum: `VAR_TYPE_STRING`, `VAR_TYPE_NUMBER`, `VAR_TYPE_BOOL`, `VAR_TYPE_LIST` Variant 2: Type: `integer(int32)` **version** `string(int64)` Output-only immutable revision of the profile. Versions start at one and increase on successful mutations; values supplied on writes are ignored. Pattern: ^-?\d+$ **fragments** `array[llm_v1_common_v1_PromptFragment]` Reusable prompt fragments returned by the operation. Project-scoped reusable prompt-template text. Profiles and other fragments include it with `{{template "fragment_id" .}}`; variables come from the conversation’s prompt\_variables. Model reference: [PromptFragment](/api/models/schema-1j5dvgfmr9#response). **fragmentId** `string` Stable template name, unique within the project library and used by include actions. **name** `string` Display name used as a console hint for the reusable prompt fragment. **content** `string` Raw template text, supporting `{{.variable}}` placeholders and nested `{{template "id" .}}` includes. #### agent-profiles-importAgentProfiles-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "profiles": [ { "profileId": "example_123", "name": "example", "description": "example", "whenToUse": "example", "keywords": [ "example_123" ], "enabled": true, "generationConfig": { "model": "example", "models": [ "example" ], "systemPrompt": "Example text", "transforms": [ "example" ], "temperature": 1, "topP": 1, "maxOutputTokens": 1, "frequencyPenalty": 1, "presencePenalty": 1, "stopSequences": [ "example" ], "seed": "1", "allowParallelToolCalls": true, "topK": 1, "repetitionPenalty": 1, "topLogprobs": 1, "minP": 1, "topA": 1, "user": "example", "modalities": [ "MODALITY_TEXT" ], "languagePreference": "en-US", "requestTimeoutSeconds": 1, "clearTools": true }, "mcpServers": [ { "serverId": "example_123", "enabled": true, "priority": 1, "allowlistToolPatterns": [ "example" ], "blocklistToolPatterns": [ "example" ] } ], "variableSpecs": [ { "name": "example", "description": "example", "required": true, "defaultValue": "example", "type": "VAR_TYPE_STRING" } ], "version": 1 } ], "fragments": [ { "fragmentId": "example_123", "name": "example", "content": "Example text" } ] } ``` #### cookbook-managed-agents-profiles-prompts-index-json-07-response Illustrative response for Variant: migrate an existing prompt library. Replace example resource identifiers with your own authorized values. ```json { "profiles": [ { "profileId": "nutrition_coach", "version": 1 } ], "fragments": [ { "fragmentId": "safety", "name": "Safety rules" } ] } ``` Document ID: `DOC-MA-profiles-prompts-api-importAgentProfiles`. [Section identities and revisions](/documentation-manifest.json). - Import a prompt library: `DOC-MA-profiles-prompts-api-importAgentProfiles#overview` - Request: `DOC-MA-profiles-prompts-api-importAgentProfiles#request` - Responses: `DOC-MA-profiles-prompts-api-importAgentProfiles#responses` --- # List a profile's versions URL: https://docs.travila.ai/api/agent-profiles/list-agent-profile-versions **POST** `/api/v1/agent-profiles/versions` Returns stored profile versions newest first. Use a version with get to inspect that profile record. It does not establish what a past turn ran: actual fragment versions, resolved variables, renderer and effective generation settings must also be captured. A profile that never existed returns an empty list. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build a reusable assistant profile](/managed-agents/profiles-prompts) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for listing immutable revisions of an agent profile. **projectId** `string` Identifier of the project associated with the operation. **profileId** `string` **required** Identifier of the agent profile associated with the operation or generation. Minimum length: 1 #### agent-profiles-listAgentProfileVersions-request Use the profileId of an existing profile in your project. ```json { "profileId": "support-assistant" } ``` #### cookbook-managed-agents-profiles-prompts-index-04-request Guide request for Recipe: investigate a change and restore earlier content. Replace example resource identifiers with your own authorized values. ```json { "profileId": "nutrition_coach" } ``` ## Responses ### 200 — Version history, descending Content type: `application/json` Result payload for listing immutable revisions of an agent profile. **versions** `array[llm_v1_services_agent_profile_v1_AgentProfileVersionInfo]` Descending (newest first). Empty when the profile has never existed. Version identifier and creation time for an immutable agent-profile revision. Model reference: [AgentProfileVersionInfo](/api/models/schema-ohrdb6rrpn#response). **version** `string(int64)` Version of the resource represented by this message. Pattern: ^-?\d+$ **createdAt** `string(date-time)` Time when this record was created. #### agent-profiles-listAgentProfileVersions-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "versions": [ { "version": 1, "createdAt": "2026-09-16T12:00:00Z" } ] } ``` #### cookbook-managed-agents-profiles-prompts-index-json-03-response Illustrative response for Recipe: investigate a change and restore earlier content. Replace example resource identifiers with your own authorized values. ```json { "versions": [ { "version": 3, "createdAt": "2026-08-14T10:22:41Z" }, { "version": 2, "createdAt": "2026-07-02T16:04:09Z" }, { "version": 1, "createdAt": "2026-06-19T09:11:55Z" } ] } ``` Document ID: `DOC-MA-profiles-prompts-api-listAgentProfileVersions`. [Section identities and revisions](/documentation-manifest.json). - List a profile's versions: `DOC-MA-profiles-prompts-api-listAgentProfileVersions#overview` - Request: `DOC-MA-profiles-prompts-api-listAgentProfileVersions#request` - Responses: `DOC-MA-profiles-prompts-api-listAgentProfileVersions#responses` --- # List agent profiles URL: https://docs.travila.ai/api/agent-profiles/list-agent-profiles **POST** `/api/v1/agent-profiles/list` Returns a paginated collection of full profile records for inspection or editing. For a lightweight selection view, use [library](/api/agent-profiles/get-agent-profile-library), which omits runtime configuration. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build a reusable assistant profile](/managed-agents/profiles-prompts) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for paging through agent profiles available in the project library. **projectId** `string` Identifier of the project associated with the operation. **page** `string(int64)` Page number used by this listing operation. Pattern: ^-?\d+$ **pageSize** `string(int64)` Number of entries requested per page. Zero or omission lets the server choose its default. Pattern: ^-?\d+$ **includeDisabled** `boolean` Include disabled profiles in addition to the enabled selection; otherwise only enabled profiles are returned. #### agent-profiles-listAgentProfiles-request Read a bounded first page from the project library. ```json { "page": 1, "pageSize": 20 } ``` #### cookbook-managed-agents-profiles-prompts-index-06-request Guide request for Variant: inventory profiles before a shared change. Replace example resource identifiers with your own authorized values. ```json { "page": 1, "pageSize": 25 } ``` ## Responses ### 200 — Page of profiles Content type: `application/json` Result payload for paging through agent profiles available in the project library. **profiles** `array[llm_v1_common_v1_AgentProfile]` Agent profiles returned by the listing or import. A reusable persona with model configuration, tools and metadata describing when it should be selected. See the profile-selection and versioning guide for profile resolution and fragment versions. Model reference: [AgentProfile](/api/models/schema-1hmbcecg1j#response). **profileId** `string` Stable id, unique within the project library. **name** `string` Display name used when selecting an agent profile. e.g. "Nutrition Coach" **description** `string` Human-facing summary. **whenToUse** `string` Routing hint, Skill-style "use when…" **keywords** `array[string]` Keywords associated with discovery or selection of the agent profile. Type: `string` **enabled** `boolean` Whether the profile is enabled for selection. Omission during creation defaults to true; an explicitly false value creates a disabled profile. Disabled profiles are not selectable. **generationConfig** `any` Model, sampling, and tool configuration used for generation. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#response). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#response). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#response). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#response). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#response). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#response). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#response). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinition]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#response). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfig]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#response). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#response). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#response). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#response). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#response). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#response). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#response). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#response). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **mcpServers** `array[llm_v1_common_v1_MCPServerReference]` MCP servers used for tool discovery when this profile is active. This list replaces the conversation-wide MCP server list for those turns. MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#response). **serverId** `string` ID of pre-configured MCP server (e.g., "github", "filesystem"). **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **variableSpecs** `array[llm_v1_common_v1_PromptVariableSpec]` Variables consumed by the profile’s system-prompt template, rendered from the conversation’s prompt\_variables. Declares a variable used by a profile’s system-prompt template. Values are supplied through the conversation’s prompt\_variables. When creating a conversation with an explicitly selected profile, a variable\_specs entry with required set to true and no nonempty default\_value causes MISSING\_REQUIRED\_PROMPT\_VARIABLES if the variable is missing. Supply its value at creation; this validation is not repeated for each send or queued turn. Set intended values explicitly even when the specification declares a default. A nonempty default\_value suppresses the creation-time missing-required error but is not automatically inserted into the rendered prompt. Model reference: [PromptVariableSpec](/api/models/schema-1hkadmq6cl#response). **name** `string` Variable name referenced by the profile’s system-prompt template. e.g. "user\_name" → substituted for \{\{.user\_name}} **description** `string` Console hint + caller documentation. **required** `boolean` Whether a value is required for a profile explicitly selected at conversation creation. This validation does not run for every send or queued turn. **defaultValue** `string` A nonempty default value suppresses the creation-time missing-required error. It is not automatically inserted into the rendered prompt; supply intended values explicitly. **type** `any` Optional runtime type for this variable in the template engine. Type used to coerce a prompt variable before placing it in the template context. It determines creation-time validation, the authoring control, and how comparisons and joining values behave.
| Value | No. | Form | Meaning | |---|---|---|---| | `VAR_TYPE_STRING` | 0 | Canonical | Treat the variable as text in the template context. | | `VAR_TYPE_NUMBER` | 1 | Canonical | See meaning below. | | `VAR_TYPE_BOOL` | 2 | Canonical | See meaning below. | | `VAR_TYPE_LIST` | 3 | Canonical | See meaning below. | **`VAR_TYPE_NUMBER`** Coerce the variable to a numeric value for arithmetic or numeric comparisons. float64 in the template context (gt/lt/ge…) **`VAR_TYPE_BOOL`** Coerce the variable to a boolean for template conditions. truthiness in \{\{if …}} **`VAR_TYPE_LIST`** Provide a list that templates can iterate or join. \[]interface\{} — joinable, rangeable
Exactly one of: Variant 1: Type: `string` Enum: `VAR_TYPE_STRING`, `VAR_TYPE_NUMBER`, `VAR_TYPE_BOOL`, `VAR_TYPE_LIST` Variant 2: Type: `integer(int32)` **version** `string(int64)` Output-only immutable revision of the profile. Versions start at one and increase on successful mutations; values supplied on writes are ignored. Pattern: ^-?\d+$ **totalCount** `string(int64)` Total number of matching entries reported by the operation. Pattern: ^-?\d+$ **hasMore** `boolean` Whether the listing reports additional entries beyond this page. #### agent-profiles-listAgentProfiles-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "profiles": [ { "profileId": "example_123", "name": "example", "description": "example", "whenToUse": "example", "keywords": [ "example_123" ], "enabled": true, "generationConfig": { "model": "example", "models": [ "example" ], "systemPrompt": "Example text", "transforms": [ "example" ], "temperature": 1, "topP": 1, "maxOutputTokens": 1, "frequencyPenalty": 1, "presencePenalty": 1, "stopSequences": [ "example" ], "seed": "1", "allowParallelToolCalls": true, "topK": 1, "repetitionPenalty": 1, "topLogprobs": 1, "minP": 1, "topA": 1, "user": "example", "modalities": [ "MODALITY_TEXT" ], "languagePreference": "en-US", "requestTimeoutSeconds": 1, "clearTools": true }, "mcpServers": [ { "serverId": "example_123", "enabled": true, "priority": 1, "allowlistToolPatterns": [ "example" ], "blocklistToolPatterns": [ "example" ] } ], "variableSpecs": [ { "name": "example", "description": "example", "required": true, "defaultValue": "example", "type": "VAR_TYPE_STRING" } ], "version": 1 } ], "totalCount": 1, "hasMore": true } ``` #### cookbook-managed-agents-profiles-prompts-index-json-05-response Illustrative response for Variant: inventory profiles before a shared change. Replace example resource identifiers with your own authorized values. ```json { "profiles": [ { "profileId": "nutrition_coach", "name": "Nutrition Coach", "version": 3 } ], "totalCount": 1, "hasMore": false } ``` Document ID: `DOC-MA-profiles-prompts-api-listAgentProfiles`. [Section identities and revisions](/documentation-manifest.json). - List agent profiles: `DOC-MA-profiles-prompts-api-listAgentProfiles#overview` - Request: `DOC-MA-profiles-prompts-api-listAgentProfiles#request` - Responses: `DOC-MA-profiles-prompts-api-listAgentProfiles#responses` --- # List prompt fragments URL: https://docs.travila.ai/api/agent-profiles/list-prompt-fragments **POST** `/api/v1/prompt-fragments/list` Returns the project's fragments, paginated, together with the current project-wide fragment-set version. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Reuse and update shared assistant instructions](/managed-agents/profiles-prompts/prompt-fragments) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for paging through reusable prompt fragments in the project library. **projectId** `string` Identifier of the project associated with the operation. **page** `string(int64)` Page number used by this listing operation. Pattern: ^-?\d+$ **pageSize** `string(int64)` Number of entries requested per page. Zero or omission lets the server choose its default. Pattern: ^-?\d+$ #### agent-profiles-listPromptFragments-request Read a bounded first page from the project library. ```json { "page": 1, "pageSize": 20 } ``` #### cookbook-managed-agents-profiles-prompts-prompt-fragments-03-request Guide request for Step 2: Check the sources and record their set version. Replace example resource identifiers with your own authorized values. ```json { "page": 1, "pageSize": 25 } ``` ## Responses ### 200 — Page of fragments Content type: `application/json` Result payload for paging through reusable prompt fragments in the project library. **fragments** `array[llm_v1_common_v1_PromptFragment]` Reusable prompt fragments returned by the operation. Project-scoped reusable prompt-template text. Profiles and other fragments include it with `{{template "fragment_id" .}}`; variables come from the conversation’s prompt\_variables. Model reference: [PromptFragment](/api/models/schema-1j5dvgfmr9#response). **fragmentId** `string` Stable template name, unique within the project library and used by include actions. **name** `string` Display name used as a console hint for the reusable prompt fragment. **content** `string` Raw template text, supporting `{{.variable}}` placeholders and nested `{{template "id" .}}` includes. **totalCount** `string(int64)` Total number of matching entries reported by the operation. Pattern: ^-?\d+$ **hasMore** `boolean` Whether the listing reports additional entries beyond this page. **setVersion** `string(int64)` Current version of the project’s prompt-fragment set. Zero means no fragments have been written. Pattern: ^-?\d+$ #### agent-profiles-listPromptFragments-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "fragments": [ { "fragmentId": "example_123", "name": "example", "content": "Example text" } ], "totalCount": 1, "hasMore": true, "setVersion": 1 } ``` #### cookbook-managed-agents-profiles-prompts-prompt-fragments-json-03-response Illustrative response for Step 2: Check the sources and record their set version. Replace example resource identifiers with your own authorized values. ```json { "fragments": [ { "fragmentId": "safety", "name": "Safety rules", "content": "Never give medical advice. Refer the user to a clinician when asked." } ], "totalCount": 1, "hasMore": false, "setVersion": 7 } ``` Document ID: `DOC-MA-profiles-prompts-api-listPromptFragments`. [Section identities and revisions](/documentation-manifest.json). - List prompt fragments: `DOC-MA-profiles-prompts-api-listPromptFragments#overview` - Request: `DOC-MA-profiles-prompts-api-listPromptFragments#request` - Responses: `DOC-MA-profiles-prompts-api-listPromptFragments#responses` --- # Update an agent profile URL: https://docs.travila.ai/api/agent-profiles/update-agent-profile **POST** `/api/v1/agent-profiles/update` Updates an agent profile. Each successful update appends a new immutable version; the profile ID remains fixed and the store assigns the version. **Which fields change** Without an [`updateMask`](/api/agent-profiles/update-agent-profile#request-field-updatemask), only the fields the supplied [`profile`](/api/agent-profiles/update-agent-profile#request-field-profile) sets change, and inside `generationConfig` only the sub-fields it sets. Nothing left out is cleared, so clearing a field needs a mask. A mask naming fields changes exactly those, clearing a named field the profile leaves unset; to replace the whole profile, name every field. An update that would leave `name` or `whenToUse` empty is refused with `400`, as is one writing a system prompt that is not a valid template or variable specs without unique names. Use this in a guide: [Build a reusable assistant profile](/managed-agents/profiles-prompts) · [Keep a model on the providers you choose](/managed-agents/model-controls/provider-pinning) · [Reuse and update shared assistant instructions](/managed-agents/profiles-prompts/prompt-fragments) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for changing selected agent-profile fields and producing an updated revision. **projectId** `string` Identifier of the project associated with the operation. **profileId** `string` **required** Identifier of the agent profile associated with the operation or generation. Minimum length: 1 **profile** `any` Carries the new field values. All of: Variant 1: A reusable persona with model configuration, tools and metadata describing when it should be selected. See the profile-selection and versioning guide for profile resolution and fragment versions. Model reference: [AgentProfile](/api/models/schema-1hmbcecg1j#request). **profileId** `string` Stable id, unique within the project library. **name** `string` Display name used when selecting an agent profile. e.g. "Nutrition Coach" **description** `string` Human-facing summary. **whenToUse** `string` Routing hint, Skill-style "use when…" **keywords** `array[string]` Keywords associated with discovery or selection of the agent profile. Type: `string` **enabled** `boolean` Whether the profile is enabled for selection. Omission during creation defaults to true; an explicitly false value creates a disabled profile. Disabled profiles are not selectable. **generationConfig** `any` Model, sampling, and tool configuration used for generation. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#request). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#request). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#request). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#request). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#request). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#request). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinitionInput]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#request). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinitionInput]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRuleInput]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#request). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#request). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#request). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRuleInput]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#request). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#request). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfigInput]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#request). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#request). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#request). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#request). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) Minimum length: 2 Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$ **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#request). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" Maximum length: 50 **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" Enum: ``, `friendly`, `iso8601`, `date_only` Maximum length: 50 **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#request). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` **required** Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" Enum: `minimal`, `standard`, `verbose` **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#request). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#request). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **mcpServers** `array[llm_v1_common_v1_MCPServerReferenceInput]` MCP servers used for tool discovery when this profile is active. This list replaces the conversation-wide MCP server list for those turns. MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#request). **serverId** `string` **required** ID of pre-configured MCP server (e.g., "github", "filesystem"). Minimum length: 1 **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **variableSpecs** `array[llm_v1_common_v1_PromptVariableSpecInput]` Variables consumed by the profile’s system-prompt template, rendered from the conversation’s prompt\_variables. Declares a variable used by a profile’s system-prompt template. Values are supplied through the conversation’s prompt\_variables. When creating a conversation with an explicitly selected profile, a variable\_specs entry with required set to true and no nonempty default\_value causes MISSING\_REQUIRED\_PROMPT\_VARIABLES if the variable is missing. Supply its value at creation; this validation is not repeated for each send or queued turn. Set intended values explicitly even when the specification declares a default. A nonempty default\_value suppresses the creation-time missing-required error but is not automatically inserted into the rendered prompt. Model reference: [PromptVariableSpec](/api/models/schema-1hkadmq6cl#request). **name** `string` Variable name referenced by the profile’s system-prompt template. e.g. "user\_name" → substituted for \{\{.user\_name}} **description** `string` Console hint + caller documentation. **required** `boolean` Whether a value is required for a profile explicitly selected at conversation creation. This validation does not run for every send or queued turn. **defaultValue** `string` A nonempty default value suppresses the creation-time missing-required error. It is not automatically inserted into the rendered prompt; supply intended values explicitly. **type** `any` Optional runtime type for this variable in the template engine. Type used to coerce a prompt variable before placing it in the template context. It determines creation-time validation, the authoring control, and how comparisons and joining values behave.
| Value | No. | Form | Meaning | |---|---|---|---| | `VAR_TYPE_STRING` | 0 | Canonical | Treat the variable as text in the template context. | | `VAR_TYPE_NUMBER` | 1 | Canonical | See meaning below. | | `VAR_TYPE_BOOL` | 2 | Canonical | See meaning below. | | `VAR_TYPE_LIST` | 3 | Canonical | See meaning below. | **`VAR_TYPE_NUMBER`** Coerce the variable to a numeric value for arithmetic or numeric comparisons. float64 in the template context (gt/lt/ge…) **`VAR_TYPE_BOOL`** Coerce the variable to a boolean for template conditions. truthiness in \{\{if …}} **`VAR_TYPE_LIST`** Provide a list that templates can iterate or join. \[]interface\{} — joinable, rangeable
Exactly one of: Variant 1: Type: `string` Enum: `VAR_TYPE_STRING`, `VAR_TYPE_NUMBER`, `VAR_TYPE_BOOL`, `VAR_TYPE_LIST` Variant 2: Type: `integer(int32)` **version** `string(int64)` Output-only immutable revision of the profile. Versions start at one and increase on successful mutations; values supplied on writes are ignored. Pattern: ^-?\d+$ **updateMask** `string` Field paths selecting which values to modify. Omitted or empty: only the fields the profile sets change, at every depth. #### agent-profiles-updateAgentProfile-request Rename an existing profile without replacing its generation configuration. ```json { "profileId": "support-assistant", "profile": { "name": "Customer support assistant" }, "updateMask": "name" } ``` #### cookbook-managed-agents-profiles-prompts-index-03-request Guide request for Recipe: change the response style without replacing the profile. Replace example resource identifiers with your own authorized values. ```json { "profileId": "nutrition_coach", "profile": { "generationConfig": { "temperature": 0.2 } }, "updateMask": "generationConfig.temperature" } ``` #### cookbook-managed-agents-profiles-prompts-index-json-06-request Guide request for Retire an assistant without stranding its conversations. Replace example resource identifiers with your own authorized values. ```json { "profileId": "nutrition_coach", "profile": { "enabled": false }, "updateMask": "enabled" } ``` #### cookbook-managed-agents-profiles-prompts-prompt-fragments-json-02-request Guide request for Step 1: Create the block and include it in the profile. Replace example resource identifiers with your own authorized values. ```json { "profileId": "nutrition_coach", "profile": { "generationConfig": { "systemPrompt": "{{template \"safety\" .}}\n\nYou are a nutrition coach for {{.userName}}." } }, "updateMask": "generationConfig.systemPrompt" } ``` ## Responses ### 200 — Profile updated; the new stored record is echoed back Content type: `application/json` Result payload for changing selected agent-profile fields and producing an updated revision. **profile** `any` Agent profile returned by the operation. All of: Variant 1: A reusable persona with model configuration, tools and metadata describing when it should be selected. See the profile-selection and versioning guide for profile resolution and fragment versions. Model reference: [AgentProfile](/api/models/schema-1hmbcecg1j#response). **profileId** `string` Stable id, unique within the project library. **name** `string` Display name used when selecting an agent profile. e.g. "Nutrition Coach" **description** `string` Human-facing summary. **whenToUse** `string` Routing hint, Skill-style "use when…" **keywords** `array[string]` Keywords associated with discovery or selection of the agent profile. Type: `string` **enabled** `boolean` Whether the profile is enabled for selection. Omission during creation defaults to true; an explicitly false value creates a disabled profile. Disabled profiles are not selectable. **generationConfig** `any` Model, sampling, and tool configuration used for generation. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#response). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#response). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#response). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#response). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#response). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#response). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#response). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinition]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#response). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfig]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#response). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#response). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#response). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#response). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#response). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#response). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#response). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#response). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **mcpServers** `array[llm_v1_common_v1_MCPServerReference]` MCP servers used for tool discovery when this profile is active. This list replaces the conversation-wide MCP server list for those turns. MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#response). **serverId** `string` ID of pre-configured MCP server (e.g., "github", "filesystem"). **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **variableSpecs** `array[llm_v1_common_v1_PromptVariableSpec]` Variables consumed by the profile’s system-prompt template, rendered from the conversation’s prompt\_variables. Declares a variable used by a profile’s system-prompt template. Values are supplied through the conversation’s prompt\_variables. When creating a conversation with an explicitly selected profile, a variable\_specs entry with required set to true and no nonempty default\_value causes MISSING\_REQUIRED\_PROMPT\_VARIABLES if the variable is missing. Supply its value at creation; this validation is not repeated for each send or queued turn. Set intended values explicitly even when the specification declares a default. A nonempty default\_value suppresses the creation-time missing-required error but is not automatically inserted into the rendered prompt. Model reference: [PromptVariableSpec](/api/models/schema-1hkadmq6cl#response). **name** `string` Variable name referenced by the profile’s system-prompt template. e.g. "user\_name" → substituted for \{\{.user\_name}} **description** `string` Console hint + caller documentation. **required** `boolean` Whether a value is required for a profile explicitly selected at conversation creation. This validation does not run for every send or queued turn. **defaultValue** `string` A nonempty default value suppresses the creation-time missing-required error. It is not automatically inserted into the rendered prompt; supply intended values explicitly. **type** `any` Optional runtime type for this variable in the template engine. Type used to coerce a prompt variable before placing it in the template context. It determines creation-time validation, the authoring control, and how comparisons and joining values behave.
| Value | No. | Form | Meaning | |---|---|---|---| | `VAR_TYPE_STRING` | 0 | Canonical | Treat the variable as text in the template context. | | `VAR_TYPE_NUMBER` | 1 | Canonical | See meaning below. | | `VAR_TYPE_BOOL` | 2 | Canonical | See meaning below. | | `VAR_TYPE_LIST` | 3 | Canonical | See meaning below. | **`VAR_TYPE_NUMBER`** Coerce the variable to a numeric value for arithmetic or numeric comparisons. float64 in the template context (gt/lt/ge…) **`VAR_TYPE_BOOL`** Coerce the variable to a boolean for template conditions. truthiness in \{\{if …}} **`VAR_TYPE_LIST`** Provide a list that templates can iterate or join. \[]interface\{} — joinable, rangeable
Exactly one of: Variant 1: Type: `string` Enum: `VAR_TYPE_STRING`, `VAR_TYPE_NUMBER`, `VAR_TYPE_BOOL`, `VAR_TYPE_LIST` Variant 2: Type: `integer(int32)` **version** `string(int64)` Output-only immutable revision of the profile. Versions start at one and increase on successful mutations; values supplied on writes are ignored. Pattern: ^-?\d+$ #### agent-profiles-updateAgentProfile-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "profile": { "profileId": "example_123", "name": "example", "description": "example", "whenToUse": "example", "keywords": [ "example_123" ], "enabled": true, "generationConfig": { "model": "example", "models": [ "example" ], "systemPrompt": "Example text", "transforms": [ "example" ], "temperature": 1, "topP": 1, "maxOutputTokens": 1, "frequencyPenalty": 1, "presencePenalty": 1, "stopSequences": [ "example" ], "seed": "1", "allowParallelToolCalls": true, "topK": 1, "repetitionPenalty": 1, "topLogprobs": 1, "minP": 1, "topA": 1, "user": "example", "modalities": [ "MODALITY_TEXT" ], "languagePreference": "en-US", "requestTimeoutSeconds": 1, "clearTools": true }, "mcpServers": [ { "serverId": "example_123", "enabled": true, "priority": 1, "allowlistToolPatterns": [ "example" ], "blocklistToolPatterns": [ "example" ] } ], "variableSpecs": [ { "name": "example", "description": "example", "required": true, "defaultValue": "example", "type": "VAR_TYPE_STRING" } ], "version": 1 } } ``` Document ID: `DOC-MA-profiles-prompts-api-updateAgentProfile`. [Section identities and revisions](/documentation-manifest.json). - Update an agent profile: `DOC-MA-profiles-prompts-api-updateAgentProfile#overview` - Request: `DOC-MA-profiles-prompts-api-updateAgentProfile#request` - Responses: `DOC-MA-profiles-prompts-api-updateAgentProfile#responses` --- # Update a prompt fragment URL: https://docs.travila.ai/api/agent-profiles/update-prompt-fragment **POST** `/api/v1/prompt-fragments/update` Partially updates a fragment via [`updateMask`](/api/agent-profiles/update-prompt-fragment#request-field-updatemask), using the mask semantics of [profile update](/managed-agents/profiles-prompts#update-a-profile). The change reaches every profile that includes this fragment on its next turn and increments the project-wide fragment-set version. There is no per-profile rollout. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Reuse and update shared assistant instructions](/managed-agents/profiles-prompts/prompt-fragments) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for changing selected fields of a reusable prompt fragment. **projectId** `string` Identifier of the project associated with the operation. **fragmentId** `string` **required** Identifier of the reusable prompt fragment. Minimum length: 1 **fragment** `any` Carries the new field values. All of: Variant 1: Project-scoped reusable prompt-template text. Profiles and other fragments include it with `{{template "fragment_id" .}}`; variables come from the conversation’s prompt\_variables. Model reference: [PromptFragment](/api/models/schema-1j5dvgfmr9#request). **fragmentId** `string` Stable template name, unique within the project library and used by include actions. **name** `string` Display name used as a console hint for the reusable prompt fragment. **content** `string` Raw template text, supporting `{{.variable}}` placeholders and nested `{{template "id" .}}` includes. **updateMask** `string` Field paths selecting which values to modify. #### agent-profiles-updatePromptFragment-request Replace the content of an existing fragment, preserving its other fields. ```json { "fragmentId": "answer-style", "fragment": { "content": "Use short paragraphs and include the next action." }, "updateMask": "content" } ``` #### cookbook-managed-agents-profiles-prompts-prompt-fragments-04-request Guide request for Recipe: change shared wording across the assistants. Replace example resource identifiers with your own authorized values. ```json { "fragmentId": "safety", "fragment": { "content": "Never give medical or dosage advice. Refer the user to a clinician." }, "updateMask": "content" } ``` ## Responses ### 200 — Fragment updated; the new stored record is echoed back Content type: `application/json` Result payload for changing selected fields of a reusable prompt fragment. **fragment** `any` Reusable prompt fragment returned by the operation. All of: Variant 1: Project-scoped reusable prompt-template text. Profiles and other fragments include it with `{{template "fragment_id" .}}`; variables come from the conversation’s prompt\_variables. Model reference: [PromptFragment](/api/models/schema-1j5dvgfmr9#response). **fragmentId** `string` Stable template name, unique within the project library and used by include actions. **name** `string` Display name used as a console hint for the reusable prompt fragment. **content** `string` Raw template text, supporting `{{.variable}}` placeholders and nested `{{template "id" .}}` includes. #### agent-profiles-updatePromptFragment-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "fragment": { "fragmentId": "example_123", "name": "example", "content": "Example text" } } ``` Document ID: `DOC-MA-profiles-prompts-api-updatePromptFragment`. [Section identities and revisions](/documentation-manifest.json). - Update a prompt fragment: `DOC-MA-profiles-prompts-api-updatePromptFragment#overview` - Request: `DOC-MA-profiles-prompts-api-updatePromptFragment#request` - Responses: `DOC-MA-profiles-prompts-api-updatePromptFragment#responses` --- # Third-Party Integrations APIs URL: https://docs.travila.ai/api/connected-apps Version: `aju17f20mq` Use the reference below for request and response fields and operation-specific requirements. # Overview \{#overview} Connect end-user accounts through the optional hosted Pipedream integration. This API requires Pipedream Connect to be enabled for your account. ## Everything Is Scoped To The Calling User \{#everything-is-scoped-to-the-calling-user} ## Authentication \{#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](https://docs.travila.ai/core-platform/identity-access/authentication). Tenant context comes from the authenticated request. Client-supplied `X-Tenant-Id`, `X-User-Id` or `X-Project-Id` are not an authorization mechanism. 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 completed redirect is not proof of a connected, authorized account. Reconcile the current connection attempt and returned account state. Multiple accounts can exist for one app. A healthy connection does not replace the user’s consent for an action. **Related guide:** [Connected accounts](https://docs.travila.ai/integrations/tools-connections/connected-apps) ## Pagination \{#pagination} ### JSON conventions \{#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](https://docs.travila.ai/api). ## Pipedream \{#reference-group-1} Connect a user's own third-party accounts through [Pipedream Connect](https://pipedream.com/docs/connect/), and manage what they have connected. The arc is: browse the catalog (public data, readable before anyone has connected anything), mint a short-lived hosted link the user opens to authorize one app, then read and remove the accounts that came out of it — including whole-user offboarding. * [List connectable apps](/api/connected-apps/pipedream-list-apps) * [Retrieve one app by slug](/api/connected-apps/pipedream-retrieve-app) * [List app categories](/api/connected-apps/pipedream-list-app-categories) * [Start connecting an app](/api/connected-apps/pipedream-create-connect-token) * [List the caller's connected accounts](/api/connected-apps/pipedream-list-accounts-for-current-user) * [Disconnect one account](/api/connected-apps/pipedream-delete-account-for-current-user) * [Delete the caller's integration data entirely](/api/connected-apps/pipedream-delete-external-user-for-current-user) * [Call a connected app's API as the user](/api/connected-apps/pipedream-proxy-for-current-user) ## Server 1 \{#reference-server-1} Travila API [https://api.travila.ai](https://api.travila.ai) ## X-API-Key \{#authentication-apiKeyAuth} 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 \{#authentication-onBehalfOf} 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 \{#authentication-bearerAuth} 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

### apiKeyAuth Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-API-Key` ### onBehalfOf Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-On-Behalf-Of` ### bearerAuth Security scheme type: `http` HTTP authorization scheme: `bearer` ## Operations - [Start connecting an app](/api/connected-apps/pipedream-create-connect-token) — `POST /api/v1/integrations/pipedream/create-connect-token` - [List connectable apps](/api/connected-apps/pipedream-list-apps) — `POST /api/v1/integrations/pipedream/list-apps` - [Retrieve one app by slug](/api/connected-apps/pipedream-retrieve-app) — `POST /api/v1/integrations/pipedream/retrieve-app` - [List app categories](/api/connected-apps/pipedream-list-app-categories) — `POST /api/v1/integrations/pipedream/list-app-categories` - [List the caller's connected accounts](/api/connected-apps/pipedream-list-accounts-for-current-user) — `POST /api/v1/integrations/pipedream/list-accounts` - [Disconnect one account](/api/connected-apps/pipedream-delete-account-for-current-user) — `POST /api/v1/integrations/pipedream/delete-account` - [Delete the caller's integration data entirely](/api/connected-apps/pipedream-delete-external-user-for-current-user) — `POST /api/v1/integrations/pipedream/delete-external-user` - [Call a connected app's API as the user](/api/connected-apps/pipedream-proxy-for-current-user) — `POST /api/v1/integrations/pipedream/proxy` Document ID: `DOC-API-connected-apps-overview`. [Section identities and revisions](/documentation-manifest.json). - Overview: `DOC-API-connected-apps-overview#overview` - Everything Is Scoped To The Calling User: `DOC-API-connected-apps-overview#everything-is-scoped-to-the-calling-user` - Authentication: `DOC-API-connected-apps-overview#authentication` - Pagination: `DOC-API-connected-apps-overview#pagination` - JSON conventions: `DOC-API-connected-apps-overview#json-conventions` - Pipedream: `DOC-API-connected-apps-overview#reference-group-1` - Server 1: `DOC-API-connected-apps-overview#reference-server-1` - X-API-Key: `DOC-API-connected-apps-overview#authentication-apiKeyAuth` - X-On-Behalf-Of: `DOC-API-connected-apps-overview#authentication-onBehalfOf` - Authorization: Bearer: `DOC-API-connected-apps-overview#authentication-bearerAuth` --- # Start connecting an app URL: https://docs.travila.ai/api/connected-apps/pipedream-create-connect-token **POST** `/api/v1/integrations/pipedream/create-connect-token` Creates a hosted connection attempt targeted by `appSlug` and returns its complete connect URL. Validate the parsed URL against the expected provider origin and path for the current attempt, then use it without reconstructing its token query. Treat the URL as a short-lived credential; read `expiresAt`, avoid caching/sharing it, and create a fresh attempt when appropriate. Do not assume a specific lifetime or single-use property unless qualified for the deployed provider. For embedding, configure exact `allowedOrigins`. Correlate the returned state with the attempt initiated by this user; returned state is not authority. A redirect does not establish success: reconcile `list-accounts` and provider errors. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for issuing a token and hosted link for connecting an end-user account. **state** `string` Optional opaque state to round-trip in redirect **redirectUri** `string` Optional universal redirect (success) URI override **allowedOrigins** `array[string]` CORS allowed origins for hosted Connect (iframe) Type: `string` **successRedirectUrl** `string` Optional explicit success/error redirects **errorRedirectUrl** `string` URL to which the account-connection flow redirects on error. **webhookUrl** `string` Optional webhook for Connect notifications **appSlug** `string` App slug the end user should connect (e.g. "github", "strava"). Pipedream's hosted Connect page rejects the link its API returns unless an `app` query parameter is present. Forwarded to PipedreamService.CreateConnectToken, which builds a link that works as-is. #### connected-apps-pipedreamCreateConnectToken-request Create a connection token for the authenticated end user using the configured provider defaults. ```json {} ``` #### cookbook-integrations-tools-connections-connected-apps-02-request Guide request for Create the authorization link when the customer clicks Connect. Replace example resource identifiers with your own authorized values. ```json { "appSlug": "google_calendar", "successRedirectUrl": "https://app.example.com/integrations?ok=1", "errorRedirectUrl": "https://app.example.com/integrations?ok=0", "state": "picker-session-8f3a" } ``` ## Responses ### 200 — Connect token and hosted link Content type: `application/json` Result payload for issuing a token and hosted link for connecting an end-user account. **token** `string` Short-lived Pipedream Connect token returned by the provider. **connectLinkUrl** `string` Pipedream Connect URL used to authorize an account connection. **expiresAt** `string(date-time)` Time when the credential or resource expires. #### connected-apps-pipedreamCreateConnectToken-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "token": "example", "connectLinkUrl": "https://example.com/resource", "expiresAt": "2026-09-16T12:00:00Z" } ``` #### cookbook-integrations-tools-connections-connected-apps-json-02-response Illustrative response for Create the authorization link when the customer clicks Connect. Replace example resource identifiers with your own authorized values. ```json { "token": "ctok_5xyz...", "connectLinkUrl": "https://pipedream.com/_static/connect.html?token=ctok_5xyz...&connectLink=true&app=google_calendar", "expiresAt": "2026-08-10T10:04:11Z" } ``` Document ID: `DOC-IN-tools-connections-apps-api-pipedreamCreateConnectToken`. [Section identities and revisions](/documentation-manifest.json). - Start connecting an app: `DOC-IN-tools-connections-apps-api-pipedreamCreateConnectToken#overview` - Request: `DOC-IN-tools-connections-apps-api-pipedreamCreateConnectToken#request` - Responses: `DOC-IN-tools-connections-apps-api-pipedreamCreateConnectToken#responses` --- # Disconnect one account URL: https://docs.travila.ai/api/connected-apps/pipedream-delete-account-for-current-user **POST** `/api/v1/integrations/pipedream/delete-account` Disconnects the specified account belonging to the authenticated beneficiary. An account outside that scope is returned as not found. Reconcile uncertain responses before recreating it. Disconnection does not undo already dispatched actions or establish that all provider sessions and copies have been erased immediately. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for removing a Pipedream account connection for the calling user. **accountId** `string` **required** Which connected account to disconnect. Ownership is enforced downstream against the caller's own accounts — an id belonging to anyone else reads back as not found. Minimum length: 1 #### connected-apps-pipedreamDeleteAccountForCurrentUser-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "accountId": "example_123" } ``` #### cookbook-integrations-tools-connections-connected-apps-05-request Guide request for Disconnect the selected calendar. Replace example resource identifiers with your own authorized values. ```json { "accountId": "apn_kAHeAr9" } ``` ## Responses ### 200 — Account disconnected Content type: `application/json` Result payload for removing a Pipedream account connection for the calling user. **deleted** `boolean` Whether the deletion operation reports the resource removed. #### connected-apps-pipedreamDeleteAccountForCurrentUser-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "deleted": true } ``` Document ID: `DOC-IN-tools-connections-apps-api-pipedreamDeleteAccountForCurrentUser`. [Section identities and revisions](/documentation-manifest.json). - Disconnect one account: `DOC-IN-tools-connections-apps-api-pipedreamDeleteAccountForCurrentUser#overview` - Request: `DOC-IN-tools-connections-apps-api-pipedreamDeleteAccountForCurrentUser#request` - Responses: `DOC-IN-tools-connections-apps-api-pipedreamDeleteAccountForCurrentUser#responses` --- # Delete the caller's integration data entirely URL: https://docs.travila.ai/api/connected-apps/pipedream-delete-external-user-for-current-user **POST** `/api/v1/integrations/pipedream/delete-external-user` Requests irreversible deletion of the authenticated beneficiary's Pipedream external user and associated connections. Use it as one step of offboarding, not as proof of erasure across every provider and backup. Reconnection creates new connection state and requires fresh user authorization. [`accountsDeleted`](/api/connected-apps/pipedream-delete-external-user-for-current-user#response-field-accountsdeleted) is counted immediately before deletion and can differ under concurrent changes; it is not a per-account deletion receipt. Preserve your application's record of cleanup and unresolved external actions. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for removing the calling user’s Pipedream identity and connected accounts. #### connected-apps-pipedreamDeleteExternalUserForCurrentUser-request Delete the external connected-app user selected by authentication; no user identifier is accepted in this body. ```json {} ``` ## Responses ### 200 — User and all their connected accounts deleted Content type: `application/json` Result payload for removing the calling user’s Pipedream identity and connected accounts. **deleted** `boolean` Whether the deletion operation reports the resource removed. **accountsDeleted** `string(int64)` How many connected accounts went with the user. Counted from a read taken just before the delete, since Pipedream answers 204 with no body — a connection added between the two calls is still deleted, just not counted. Pattern: ^-?\d+$ #### connected-apps-pipedreamDeleteExternalUserForCurrentUser-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "deleted": true, "accountsDeleted": 1 } ``` #### cookbook-integrations-tools-connections-connected-apps-json-04-response Illustrative response for Remove integration data when the customer leaves. Replace example resource identifiers with your own authorized values. ```json { "deleted": true, "accountsDeleted": 3 } ``` Document ID: `DOC-IN-tools-connections-apps-api-pipedreamDeleteExternalUserForCurrentUser`. [Section identities and revisions](/documentation-manifest.json). - Delete the caller's integration data entirely: `DOC-IN-tools-connections-apps-api-pipedreamDeleteExternalUserForCurrentUser#overview` - Request: `DOC-IN-tools-connections-apps-api-pipedreamDeleteExternalUserForCurrentUser#request` - Responses: `DOC-IN-tools-connections-apps-api-pipedreamDeleteExternalUserForCurrentUser#responses` --- # List the caller's connected accounts URL: https://docs.travila.ai/api/connected-apps/pipedream-list-accounts-for-current-user **POST** `/api/v1/integrations/pipedream/list-accounts` Lists connected accounts for the authenticated beneficiary. An app can have multiple accounts; select the intended account ID explicitly. `healthy === true` reflects the returned provider connection state, not current action consent or authorization. An unhealthy account can need reconnection. The response does not directly return the stored third-party credential. Continue using provider pagination rather than treating an empty data page alone as exhaustion. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for listing Pipedream account connections belonging to the calling user. **after** `string` Cursor selecting entries after the specified position in the provider listing. **before** `string` Cursor selecting entries before the specified position in the provider listing. **limit** `string(int64)` Maximum number of entries requested from the listing. Pattern: ^-?\d+$ **oauthAppId** `string` OAuth application identifier used to select connected accounts. **app** `string` Pipedream app slug used to restrict the operation to one connected app. **includeCredentials** `boolean` Whether the provider should include account credentials in its response. #### connected-apps-pipedreamListAccountsForCurrentUser-request List accounts belonging to the authenticated end user. ```json {} ``` #### cookbook-integrations-tools-connections-connected-apps-03-request Guide request for Confirm the account before showing Connected. Replace example resource identifiers with your own authorized values. ```json { "app": "google_calendar" } ``` ## Responses ### 200 — A page of the caller's connected accounts Content type: `application/json` Result payload for listing Pipedream account connections belonging to the calling user. **data** `array[integrations_v1_services_pipedream_v1_Account]` Pipedream connected accounts returned for this page. Connected account (external user's OAuth connection to an app) Model reference: [Account](/api/models/schema-1fd4ce3lnc#response). **id** `string` Unique account ID. **name** `string` Display name (e.g., user's email or handle). **externalUserId** `string` Your application's user ID. **healthy** `boolean` Whether the account credentials are valid. **app** `string` Pipedream application selected by the request or returned by the provider. App name\_slug **oauthAppId** `string` OAuth app identifier (if applicable). **createdAt** `string(date-time)` Time when this record was created. **updatedAt** `string(date-time)` Time when this record was last updated. **credentialsLastRefreshedAt** `string(date-time)` Time when the connected account credentials were last refreshed. **credentialsExpiresAt** `string(date-time)` Expiration time reported for the connected account credentials. **error** `string` Error message if unhealthy. **lastRefreshedAt** `string(date-time)` ISO 8601 when credentials were last refreshed. **nextRefreshAt** `string(date-time)` ISO 8601 when credentials will next be refreshed. **pageInfo** `any` Cursor and count information returned with the provider listing. All of: Variant 1: Pagination information returned in list responses Model reference: [PipedreamPageInfo](/api/models/schema-ohepdcsvjo#response). **count** `string(int64)` Items in current page. Pattern: ^-?\d+$ **totalCount** `string(int64)` Total items matching query. Pattern: ^-?\d+$ **startCursor** `string` Cursor for start of page. **endCursor** `string` Cursor for end of page. #### connected-apps-pipedreamListAccountsForCurrentUser-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "data": [ { "id": "example_123", "name": "example", "externalUserId": "example_123", "healthy": true, "app": "example", "oauthAppId": "example_123", "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z", "credentialsLastRefreshedAt": "2026-09-16T12:00:00Z", "credentialsExpiresAt": "2026-09-16T12:00:00Z", "error": "example", "lastRefreshedAt": "2026-09-16T12:00:00Z", "nextRefreshAt": "2026-09-16T12:00:00Z" } ], "pageInfo": { "count": 1, "totalCount": 1, "startCursor": "example", "endCursor": "example" } } ``` #### cookbook-integrations-tools-connections-connected-apps-json-03-response Illustrative response for Confirm the account before showing Connected. Replace example resource identifiers with your own authorized values. ```json { "data": [ { "id": "apn_kAHeAr9", "name": "user@example.com", "app": "google_calendar", "healthy": true, "createdAt": "2026-08-10T09:14:52Z" } ], "pageInfo": { "count": 1, "totalCount": 1 } } ``` Document ID: `DOC-IN-tools-connections-apps-api-pipedreamListAccountsForCurrentUser`. [Section identities and revisions](/documentation-manifest.json). - List the caller's connected accounts: `DOC-IN-tools-connections-apps-api-pipedreamListAccountsForCurrentUser#overview` - Request: `DOC-IN-tools-connections-apps-api-pipedreamListAccountsForCurrentUser#request` - Responses: `DOC-IN-tools-connections-apps-api-pipedreamListAccountsForCurrentUser#responses` --- # List app categories URL: https://docs.travila.ai/api/connected-apps/pipedream-list-app-categories **POST** `/api/v1/integrations/pipedream/list-app-categories` Lists the categories apps are grouped under ("Developer Tools", "Communication"). Feed the returned `id` values into `categoryIds` on [`list-apps`](/api/connected-apps/pipedream-list-apps) to filter a picker by category. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized shared platform action. Use this in a guide: [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for discovering the categories used by the Pipedream app catalog. **after** `string` Cursor selecting entries after the specified position in the provider listing. **before** `string` Cursor selecting entries before the specified position in the provider listing. **limit** `string(int64)` Maximum number of entries requested from the listing. Pattern: ^-?\d+$ #### connected-apps-pipedreamListAppCategories-request List connected-app categories; this request has no selection fields. ```json {} ``` ## Responses ### 200 — A page of categories Content type: `application/json` Result payload for discovering the categories used by the Pipedream app catalog. **data** `array[integrations_v1_services_pipedream_v1_AppCategory]` Pipedream app categories returned for this page. App category Model reference: [AppCategory](/api/models/schema-ohbp8u7c1i#response). **id** `string` Identifier of the app category record. **nameSlug** `string` Category slug identifying the entry in the Pipedream catalog. **name** `string` Display label of the app category in the Pipedream catalog. **pageInfo** `any` Cursor and count information returned with the provider listing. All of: Variant 1: Pagination information returned in list responses Model reference: [PipedreamPageInfo](/api/models/schema-ohepdcsvjo#response). **count** `string(int64)` Items in current page. Pattern: ^-?\d+$ **totalCount** `string(int64)` Total items matching query. Pattern: ^-?\d+$ **startCursor** `string` Cursor for start of page. **endCursor** `string` Cursor for end of page. #### connected-apps-pipedreamListAppCategories-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "data": [ { "id": "example_123", "nameSlug": "example", "name": "example" } ], "pageInfo": { "count": 1, "totalCount": 1, "startCursor": "example", "endCursor": "example" } } ``` Document ID: `DOC-IN-tools-connections-apps-api-pipedreamListAppCategories`. [Section identities and revisions](/documentation-manifest.json). - List app categories: `DOC-IN-tools-connections-apps-api-pipedreamListAppCategories#overview` - Request: `DOC-IN-tools-connections-apps-api-pipedreamListAppCategories#request` - Responses: `DOC-IN-tools-connections-apps-api-pipedreamListAppCategories#responses` --- # List connectable apps URL: https://docs.travila.ai/api/connected-apps/pipedream-list-apps **POST** `/api/v1/integrations/pipedream/list-apps` Lists the apps a user can connect, newest catalog first unless you sort. Use this to build an app picker. This is public catalog data. It does not tell you what the caller has already connected; use [`list-accounts`](/api/connected-apps/pipedream-list-accounts-for-current-user) for that. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized shared platform action. Use this in a guide: [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for searching the Pipedream app catalog with pagination and sorting. **after** `string` Cursor selecting entries after the specified position in the provider listing. **before** `string` Cursor selecting entries before the specified position in the provider listing. **limit** `string(int64)` Maximum number of entries requested from the listing. Pattern: ^-?\d+$ **q** `string` Free-text search over app names in the integration catalog. **categoryIds** `array[string]` Integration app category identifiers used to restrict the listing. Type: `string` **sortKey** `any` Provider field used to order catalog results. Integration-app catalog property used to order list results.
| Value | No. | Form | Meaning | |---|---|---|---| | `APP_SORT_KEY_NAME` | 0 | Canonical | See meaning below. | | `APP_SORT_KEY_NAME_SLUG` | 1 | Canonical | See meaning below. | | `APP_SORT_KEY_FEATURED_WEIGHT` | 2 | Canonical | See meaning below. | **`APP_SORT_KEY_NAME`** Sort by the app's display name. "name" **`APP_SORT_KEY_NAME_SLUG`** Sort by the app's stable name slug. "name\_slug" **`APP_SORT_KEY_FEATURED_WEIGHT`** Sort by the catalog's featured-app ranking weight. "featured\_weight"
Exactly one of: Variant 1: Type: `string` Enum: `APP_SORT_KEY_NAME`, `APP_SORT_KEY_NAME_SLUG`, `APP_SORT_KEY_FEATURED_WEIGHT` Variant 2: Type: `integer(int32)` **sortDirection** `any` Direction in which the provider should order catalog results. Direction applied to the selected integration-app sort key.
| Value | No. | Form | Meaning | |---|---|---|---| | `SORT_DIRECTION_ASC` | 0 | Canonical | See meaning below. | | `SORT_DIRECTION_DESC` | 1 | Canonical | See meaning below. | **`SORT_DIRECTION_ASC`** Order results from lower to higher values of the selected sort key. "asc" **`SORT_DIRECTION_DESC`** Order results from higher to lower values of the selected sort key. "desc"
Exactly one of: Variant 1: Type: `string` Enum: `SORT_DIRECTION_ASC`, `SORT_DIRECTION_DESC` Variant 2: Type: `integer(int32)` #### connected-apps-pipedreamListApps-request List available connected-app integrations with default paging. ```json {} ``` #### cookbook-integrations-tools-connections-connected-apps-01-request Guide request for Find Google Calendar in the catalog. Replace example resource identifiers with your own authorized values. ```json { "q": "cal", "sortKey": "APP_SORT_KEY_FEATURED_WEIGHT", "sortDirection": "SORT_DIRECTION_DESC", "limit": 20 } ``` ## Responses ### 200 — A page of apps Content type: `application/json` Result payload for searching the Pipedream app catalog with pagination and sorting. **data** `array[integrations_v1_services_pipedream_v1_App]` Pipedream app catalog entries returned for this page. App metadata Model reference: [App](/api/models/schema-oti80oaqc4#response). **id** `string` Identifier of the app record. **nameSlug** `string` Unique slug identifier (e.g., "slack", "github"). **name** `string` Display name of the integration app in the Pipedream catalog. **authType** `any` Authentication mechanism reported for the integration app. Credential mechanism an integration app uses when connecting an account.
| Value | No. | Form | Meaning | |---|---|---|---| | `AUTH_TYPE_KEYS` | 0 | Canonical | See meaning below. | | `AUTH_TYPE_OAUTH` | 1 | Canonical | See meaning below. | | `AUTH_TYPE_NONE` | 2 | Canonical | See meaning below. | **`AUTH_TYPE_KEYS`** The app uses API-key credentials. API keys **`AUTH_TYPE_OAUTH`** The app uses an OAuth authorization flow. OAuth 2.0 **`AUTH_TYPE_NONE`** The app does not require authentication credentials. No auth required
Exactly one of: Variant 1: Type: `string` Enum: `AUTH_TYPE_KEYS`, `AUTH_TYPE_OAUTH`, `AUTH_TYPE_NONE` Variant 2: Type: `integer(int32)` **description** `string` Human-readable description of the resource. **imgSrc** `string` Logo image URL supplied for the integration app. **customFieldsJson** `string` JSON string for custom fields. **categories** `array[string]` Categories assigned to the integration app. Type: `string` **featuredWeight** `string(int64)` Provider weight used to order featured apps. Pattern: ^-?\d+$ **pageInfo** `any` Cursor and count information returned with the provider listing. All of: Variant 1: Pagination information returned in list responses Model reference: [PipedreamPageInfo](/api/models/schema-ohepdcsvjo#response). **count** `string(int64)` Items in current page. Pattern: ^-?\d+$ **totalCount** `string(int64)` Total items matching query. Pattern: ^-?\d+$ **startCursor** `string` Cursor for start of page. **endCursor** `string` Cursor for end of page. #### connected-apps-pipedreamListApps-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "data": [ { "id": "example_123", "nameSlug": "example", "name": "example", "authType": "AUTH_TYPE_KEYS", "description": "example", "imgSrc": "example", "customFieldsJson": "{}", "categories": [ "example" ], "featuredWeight": 1 } ], "pageInfo": { "count": 1, "totalCount": 1, "startCursor": "example", "endCursor": "example" } } ``` #### cookbook-integrations-tools-connections-connected-apps-json-01-response Illustrative response for Find Google Calendar in the catalog. Replace example resource identifiers with your own authorized values. ```json { "data": [ { "id": "app_1Q5hjR", "nameSlug": "google_calendar", "name": "Google Calendar", "imgSrc": "https://assets.pipedream.net/s.v0/app_1Q5hjR/logo/orig", "authType": "AUTH_TYPE_OAUTH", "categories": [ "Productivity" ], "featuredWeight": 12 } ], "pageInfo": { "count": 1, "totalCount": 34, "endCursor": "Y3Vyc29yOjE=" } } ``` Document ID: `DOC-IN-tools-connections-apps-api-pipedreamListApps`. [Section identities and revisions](/documentation-manifest.json). - List connectable apps: `DOC-IN-tools-connections-apps-api-pipedreamListApps#overview` - Request: `DOC-IN-tools-connections-apps-api-pipedreamListApps#request` - Responses: `DOC-IN-tools-connections-apps-api-pipedreamListApps#responses` --- # Call a connected app's API as the user URL: https://docs.travila.ai/api/connected-apps/pipedream-proxy-for-current-user **POST** `/api/v1/integrations/pipedream/proxy` Makes an HTTP request through the selected connected account. The account must belong to the effective user and the destination is subject to the provider's allowed-domain rules. Those checks do not replace permission for the requested action. Each upstream app defines its own payload. ### Upstream response handling Read the returned upstream [`status`](/api/connected-apps/pipedream-proxy-for-current-user#response-field-status) before treating the operation as successful: Travila can return HTTP 200 while the app's response contains a 404. Upstream headers and the [`body`](/api/connected-apps/pipedream-proxy-for-current-user#response-field-body) are returned as data, including on non-success status codes. Decode the body according to its content type; headers and bodies can contain third-party sensitive data. Redirects are returned, not followed. Treat `Location` as untrusted: it need not be a signed or credential-free download URL. Validate the destination before opening it and never forward platform or account credentials to it. The provider request timeout is 30 seconds. Page large results or use an appropriate provider download flow to stay within the response-body limit. A timeout can leave the external action's outcome unknown; check that action before retrying. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for making an authenticated app API request through the calling user’s connected account. ### Input constraints ### method The method must be exactly GET, HEAD, POST, PUT, PATCH, or DELETE. These literal choices are case-sensitive; no other method value satisfies this condition. **accountId** `string` **required** One of the caller's own connected accounts (id from list-accounts). Any other id reads back as not found. Minimum length: 1 **method** `string` **required** HTTP method used for the proxied or signed request. Enum: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` **url** `string` **required** Destination URL for the proxied app API request. Minimum length: 1 Maximum length: 4096 **headers** `map[string, string]` Forwarded upstream (sent as x-pd-proxy-\). **body** `string(byte)` Raw request body (base64 on the wire). Empty for GET/HEAD. #### connected-apps-pipedreamProxyForCurrentUser-request Replace accountId with the authenticated user’s connected GitHub account; request that provider’s profile endpoint. ```json { "accountId": "apn_example", "method": "GET", "url": "https://api.github.com/user" } ``` ## Responses ### 200 — The upstream response, whatever its status Content type: `application/json` Result payload for making an authenticated app API request through the calling user’s connected account. **status** `string(int64)` HTTP status code returned by the connected app’s API. Pattern: ^-?\d+$ **headers** `map[string, string]` HTTP response headers returned by the connected app’s API. **body** `string(byte)` Raw upstream body (base64 on the wire), capped at 4 MiB. Larger bodies are rejected rather than truncated, with OUT\_OF\_RANGE and reason RESPONSE\_TOO\_LARGE. #### connected-apps-pipedreamProxyForCurrentUser-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "status": 1, "headers": {}, "body": "ZXhhbXBsZQ==" } ``` Document ID: `DOC-IN-tools-connections-apps-api-pipedreamProxyForCurrentUser`. [Section identities and revisions](/documentation-manifest.json). - Call a connected app's API as the user: `DOC-IN-tools-connections-apps-api-pipedreamProxyForCurrentUser#overview` - Request: `DOC-IN-tools-connections-apps-api-pipedreamProxyForCurrentUser#request` - Responses: `DOC-IN-tools-connections-apps-api-pipedreamProxyForCurrentUser#responses` --- # Retrieve one app by slug URL: https://docs.travila.ai/api/connected-apps/pipedream-retrieve-app **POST** `/api/v1/integrations/pipedream/retrieve-app` Returns a single app by its `nameSlug` — the stable identifier used everywhere else in this API (`github`, `slack`, `google_calendar`). Use it to render an app detail page without paging the whole catalog. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized shared platform action. Use this in a guide: [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for retrieving app catalog metadata by its Pipedream slug. **nameSlug** `string` **required** Pipedream app slug identifying the catalog entry. Minimum length: 1 #### connected-apps-pipedreamRetrieveApp-request Look up the GitHub app before starting a connection. ```json { "nameSlug": "github" } ``` ## Responses ### 200 — The app Content type: `application/json` Result payload for retrieving app catalog metadata by its Pipedream slug. **app** `any` Catalog metadata returned for the selected Pipedream app. All of: Variant 1: App metadata Model reference: [App](/api/models/schema-oti80oaqc4#response). **id** `string` Identifier of the app record. **nameSlug** `string` Unique slug identifier (e.g., "slack", "github"). **name** `string` Display name of the integration app in the Pipedream catalog. **authType** `any` Authentication mechanism reported for the integration app. Credential mechanism an integration app uses when connecting an account.
| Value | No. | Form | Meaning | |---|---|---|---| | `AUTH_TYPE_KEYS` | 0 | Canonical | See meaning below. | | `AUTH_TYPE_OAUTH` | 1 | Canonical | See meaning below. | | `AUTH_TYPE_NONE` | 2 | Canonical | See meaning below. | **`AUTH_TYPE_KEYS`** The app uses API-key credentials. API keys **`AUTH_TYPE_OAUTH`** The app uses an OAuth authorization flow. OAuth 2.0 **`AUTH_TYPE_NONE`** The app does not require authentication credentials. No auth required
Exactly one of: Variant 1: Type: `string` Enum: `AUTH_TYPE_KEYS`, `AUTH_TYPE_OAUTH`, `AUTH_TYPE_NONE` Variant 2: Type: `integer(int32)` **description** `string` Human-readable description of the resource. **imgSrc** `string` Logo image URL supplied for the integration app. **customFieldsJson** `string` JSON string for custom fields. **categories** `array[string]` Categories assigned to the integration app. Type: `string` **featuredWeight** `string(int64)` Provider weight used to order featured apps. Pattern: ^-?\d+$ #### connected-apps-pipedreamRetrieveApp-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "app": { "id": "example_123", "nameSlug": "example", "name": "example", "authType": "AUTH_TYPE_KEYS", "description": "example", "imgSrc": "example", "customFieldsJson": "{}", "categories": [ "example" ], "featuredWeight": 1 } } ``` Document ID: `DOC-IN-tools-connections-apps-api-pipedreamRetrieveApp`. [Section identities and revisions](/documentation-manifest.json). - Retrieve one app by slug: `DOC-IN-tools-connections-apps-api-pipedreamRetrieveApp#overview` - Request: `DOC-IN-tools-connections-apps-api-pipedreamRetrieveApp#request` - Responses: `DOC-IN-tools-connections-apps-api-pipedreamRetrieveApp#responses` --- # Append a message without generating URL: https://docs.travila.ai/api/conversations/append-message **POST** `/api/v1/llm/append-message` Appends a context message to the thread's history without starting generation for this call. Use it to record a system note, an external event or other context that later generations should see without triggering a reply. Read `conversation-state` to confirm the event: append assigns the next monotonic sequence immediately and publishes a message event. `ROLE_USER` opens a new user turn; other roles join the most recent user turn. Choose the role for how the event should appear in history, without changing the fact it records. Append bypasses the interrupt policy and pending queue. It can run while another turn is active, but that turn may already have assembled its provider request. This call does not stop already running work or guarantee zero account-level cost: storage and future model input can still cost money. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Get a customer’s reply and recover an interrupted send](/managed-agents/conversations/generation) · [Context and compaction](/api/conversations/context-and-compaction) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for adding a message to conversation history without starting generation. **conversationKey** `string` **required** Identifier of the conversation thread. Minimum length: 1 **message** `any` **required** Required, for the same reason as SendMessageRequest.user\_message and via the same hole: this field's name is "message", the sends call theirs "user\_message", and the lenient codec discards whichever one the caller did not pick. Appending nothing costs no tokens, but applyAppendMessage returns nil for a nil message and the endpoint answers 200 regardless — so a CONTEXT UPDATE feed writes nothing and the TRIGGER that later reads the thread is missing the context it was told had landed. All of: Variant 1: Chat message At least one of content or tool\_calls must contain an entry; both lists may be nonempty. role must select a listed message role. Requiredness and allowed values are declared separately. Model reference: [Message](/api/models/schema-1j3dcf7kvu#request). **role** `any` **required** Role of the participant that produced the chat message. Participant role attached to a conversation message and forwarded in model context.
| Value | No. | Form | Meaning | |---|---|---|---| | `ROLE_SYSTEM` | 0 | Canonical | Instructions or context provided as a system message. | | `ROLE_USER` | 1 | Canonical | Input supplied by the user or customer application. | | `ROLE_ASSISTANT` | 2 | Canonical | Content produced by the assistant, including its tool-call requests. | | `ROLE_TOOL` | 3 | Canonical | A tool result supplied back to the assistant. |
Exactly one of: Variant 1: Type: `string` Enum: `ROLE_SYSTEM`, `ROLE_USER`, `ROLE_ASSISTANT`, `ROLE_TOOL` Variant 2: Type: `integer(int32)` Enum: `0`, `1`, `2`, `3` **content** `array[llm_v1_common_v1_ContentPartInput]` Content parts composing the chat message. Content parts composing a message, using a flattened structure for JSON compatibility. The `type` identifies how the content is represented; only defined content types are accepted. Model reference: [ContentPart](/api/models/schema-1hqi9r2bhh#request). **type** `any` Kind of content carried by this message part. Discriminator identifying which content representation a message part carries.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTENT_PART_TYPE_TEXT` | 0 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_URL` | 1 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_BASE64` | 2 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_ID` | 3 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_PATH` | 4 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_URL` | 5 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_DATA_URL` | 6 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_AUDIO_BASE64` | 7 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_REASONING` | 8 | Canonical | See meaning below. | **`CONTENT_PART_TYPE_TEXT`** Plain text carried by the content part. Plain text content **`CONTENT_PART_TYPE_IMAGE_URL`** An image supplied through a remote URL. Remote image URL **`CONTENT_PART_TYPE_IMAGE_BASE64`** An image supplied as base64-encoded bytes. Base64-encoded image data **`CONTENT_PART_TYPE_FILE_ID`** A provider file identifier or internal storage identifier resolved before generation. File ID — a provider file ID (e.g., OpenAI) OR an internal storage file ID; resolved to a signed FILE\_URL just-in-time before the model-provider request **`CONTENT_PART_TYPE_FILE_PATH`** A reference to a local file path. Local file path reference **`CONTENT_PART_TYPE_FILE_URL`** A file supplied through a public or signed URL. Public or signed file URL (e.g., PDF URL or data: URL) **`CONTENT_PART_TYPE_FILE_DATA_URL`** A file embedded in a data URL, including its media type and encoded data. data\:application/pdf;base64,... or similar **`CONTENT_PART_TYPE_AUDIO_BASE64`** Base64-encoded audio; the part metadata identifies its audio format. Base64-encoded audio (metadata.format required, e.g., wav/mp3) **`CONTENT_PART_TYPE_REASONING`** A reasoning segment returned by a model provider, when available. Reasoning/thinking content from chain-of-thought models
Exactly one of: Variant 1: Type: `string` Enum: `CONTENT_PART_TYPE_TEXT`, `CONTENT_PART_TYPE_IMAGE_URL`, `CONTENT_PART_TYPE_IMAGE_BASE64`, `CONTENT_PART_TYPE_FILE_ID`, `CONTENT_PART_TYPE_FILE_PATH`, `CONTENT_PART_TYPE_FILE_URL`, `CONTENT_PART_TYPE_FILE_DATA_URL`, `CONTENT_PART_TYPE_AUDIO_BASE64`, `CONTENT_PART_TYPE_REASONING` Variant 2: Type: `integer(int32)` Enum: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8` **content** `string` Text content, image URL, file ID, or base64-encoded data. **metadata** `map[string, string]` Additional type-specific metadata (dimensions, mime\_type, etc.). **cachePreferred** `boolean` Hint that this part is eligible for provider prompt caching. **structuredMessage** `any` Populated on TEXT parts for structured output responses. All of: Variant 1: A structured message whose JSON payload has been validated against a declared schema. Consumers can trust that json\_payload conforms to the schema identified by schema\_name. Inspect the run outcome before treating any message as complete. Current structured metadata is attached to a text content part through [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage) can be absent. Use an object at the schema root and validate the exact final response your application consumes; server validation covers only the first model choice. For integers that your JSON client cannot represent exactly, define string-valued fields in your schema instead of converting them through floating point. Model reference: [StructuredMessage](/api/models/schema-1ho1lk4ndj#request). **jsonPayload** `map[string, any]` The validated JSON payload as a Struct (preserves types) **schemaName** `string` Schema identifier (from ResponseFormat.schema\_name) **healed** `boolean` Whether response healing is reported for this structured message. Currently returned as false. **toolCalls** `array[llm_v1_common_v1_ToolCallInput]` Assistant-to-tool invocations. A single structured tool call emitted by the model [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat) is the client answer window. Expiry ends that wait and rejects late results; the timeout policy determines the outcome. Model reference: [ToolCall](/api/models/schema-1it6mqsqoo#request). **id** `string` Provider-supplied call id. **name** `string` Name of the tool or function being invoked. **argumentsJson** `map[string, any]` JSON object payload. **status** `any` Execution status recorded for the tool call. Execution state of a tool call, including approval waiting and terminal outcomes. The terminal outcomes are COMPLETED, FAILED, CANCELLED and TIMED\_OUT; inspect ToolCall.end\_reason for why a call ended rather than treating the reason as another status. Use a listed execution status. The end reason explains the outcome separately from the status.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_EXECUTION_STATUS_PENDING` | 0 | Canonical | The tool call is waiting to begin execution. | | `TOOL_EXECUTION_STATUS_EXECUTING` | 1 | Canonical | The tool call is currently executing. | | `TOOL_EXECUTION_STATUS_COMPLETED` | 2 | Canonical | The tool call completed successfully. This is a terminal outcome. | | `TOOL_EXECUTION_STATUS_FAILED` | 3 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. | | `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 4 | Canonical | The tool call is waiting for approval before it can execute. | | `TOOL_EXECUTION_STATUS_CANCELLED` | 5 | Canonical | The tool call was cancelled before normal completion. | | `TOOL_EXECUTION_STATUS_TIMED_OUT` | 6 | Canonical | Tool execution ended because its time limit elapsed. |
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_EXECUTION_STATUS_PENDING`, `TOOL_EXECUTION_STATUS_EXECUTING`, `TOOL_EXECUTION_STATUS_COMPLETED`, `TOOL_EXECUTION_STATUS_FAILED`, `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, `TOOL_EXECUTION_STATUS_CANCELLED`, `TOOL_EXECUTION_STATUS_TIMED_OUT` Variant 2: Type: `integer(int32)` **resultJson** `map[string, any]` Tool execution result (object). **executedAt** `string(date-time)` Time when the tool execution was recorded. **serverId** `string` Which server provides this tool (for MCP tools). **isClientTool** `boolean` True if this is a client-side tool handled by client. **description** `string` Tool description captured from the resolved tool definition when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. **parametersJsonSchema** `map[string, any]` JSON Schema describing the tool’s input arguments. **requiresApprovalAt** `string(date-time)` Deadline for an approval decision, calculated from the effective approval timeout. This is not the time the call began waiting. An approval received after the deadline is rejected. **approvedAt** `string(date-time)` Timestamp when approval decision was recorded (if approved/rejected) **approvedBy** `string` Identifier of the approver (user id, email, or actor key) **executionDuration** `string` End-to-end execution duration once terminal (includes tool server latency or client-side time) Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **endReason** `string` Why this call ended, in one short phrase — "approval rejected", "approval timeout", or the underlying error. Set only once `status` is terminal, and empty on a clean COMPLETED. Use this reason to distinguish a rejection from a failure without parsing the tool result. **clientToolDeadlineAt** `string(date-time)` Deadline by which the client must submit a result for this call, stamped when the call is dispatched to a caller. **name** `string` Name identifying the sender of the chat message. optional sender name **timestamp** `string(date-time)` Timestamp associated with the conversation message or event. **messageId** `string` Unique message identifier. **annotations** `array[llm_v1_common_v1_AnnotationInput]` Structured annotations (e.g., standardized web search URL citations, PDF reuse tokens) Tagged provider annotation attached to generated content, such as a citation or PDF reference. Model reference: [Annotation](/api/models/schema-1i0hjer0pd#request). **kind** `any` Selected kind; determines which submessage is populated Kind of source annotation associated with generated content.
| Value | No. | Form | Meaning | |---|---|---|---| | `ANNOTATION_KIND_URL_CITATION` | 0 | Canonical | A citation to a source identified by its URL. | | `ANNOTATION_KIND_PDF` | 1 | Canonical | An annotation identifying source content in a PDF document. |
Exactly one of: Variant 1: Type: `string` Enum: `ANNOTATION_KIND_URL_CITATION`, `ANNOTATION_KIND_PDF` Variant 2: Type: `integer(int32)` **urlCitation** `any` Submessage fields (optional); populate the one matching kind All of: Variant 1: Web source and character range cited in generated message content. Model reference: [UrlCitation](/api/models/schema-1hujls61ng#request). **url** `string` URL of the cited web page. **title** `string` Title of the web page cited by this annotation. **content** `string` Optional excerpt or snippet of the cited web page. **startIndex** `string(int64)` Character index in message content. Pattern: ^-?\d+$ **endIndex** `string(int64)` Character index in message content. Pattern: ^-?\d+$ **pdf** `any` PDF annotation identifying the parsed file and available parsing output. All of: Variant 1: Provider annotation identifying a parsed PDF and reusable parsing output. Model reference: [PdfAnnotation](/api/models/schema-1hsi58i6pb#request). **filename** `string` Optional identifying information about the original file **engine** `string` PDF parsing engine used by provider (e.g., "pdf-text", "mistral-ocr", "native") **token** `string` Opaque provider token or handle allowing reuse without re-parsing **sourceUrl** `string` Optional: original source reference (public URL or data: URL) **hash** `string` Provider-supplied hash identifying the parsed file. **content** `array[llm_v1_common_v1_ContentPartInput]` Optional structured content returned by provider annotations (text, image URLs, etc.) Note: This can be large; include only if you need to round-trip provider annotations. Content parts composing a message, using a flattened structure for JSON compatibility. The `type` identifies how the content is represented; only defined content types are accepted. Model reference: [ContentPart](/api/models/schema-1hqi9r2bhh#request). **type** `any` Kind of content carried by this message part. Discriminator identifying which content representation a message part carries.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTENT_PART_TYPE_TEXT` | 0 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_URL` | 1 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_BASE64` | 2 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_ID` | 3 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_PATH` | 4 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_URL` | 5 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_DATA_URL` | 6 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_AUDIO_BASE64` | 7 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_REASONING` | 8 | Canonical | See meaning below. | **`CONTENT_PART_TYPE_TEXT`** Plain text carried by the content part. Plain text content **`CONTENT_PART_TYPE_IMAGE_URL`** An image supplied through a remote URL. Remote image URL **`CONTENT_PART_TYPE_IMAGE_BASE64`** An image supplied as base64-encoded bytes. Base64-encoded image data **`CONTENT_PART_TYPE_FILE_ID`** A provider file identifier or internal storage identifier resolved before generation. File ID — a provider file ID (e.g., OpenAI) OR an internal storage file ID; resolved to a signed FILE\_URL just-in-time before the model-provider request **`CONTENT_PART_TYPE_FILE_PATH`** A reference to a local file path. Local file path reference **`CONTENT_PART_TYPE_FILE_URL`** A file supplied through a public or signed URL. Public or signed file URL (e.g., PDF URL or data: URL) **`CONTENT_PART_TYPE_FILE_DATA_URL`** A file embedded in a data URL, including its media type and encoded data. data\:application/pdf;base64,... or similar **`CONTENT_PART_TYPE_AUDIO_BASE64`** Base64-encoded audio; the part metadata identifies its audio format. Base64-encoded audio (metadata.format required, e.g., wav/mp3) **`CONTENT_PART_TYPE_REASONING`** A reasoning segment returned by a model provider, when available. Reasoning/thinking content from chain-of-thought models
Exactly one of: Variant 1: Type: `string` Enum: `CONTENT_PART_TYPE_TEXT`, `CONTENT_PART_TYPE_IMAGE_URL`, `CONTENT_PART_TYPE_IMAGE_BASE64`, `CONTENT_PART_TYPE_FILE_ID`, `CONTENT_PART_TYPE_FILE_PATH`, `CONTENT_PART_TYPE_FILE_URL`, `CONTENT_PART_TYPE_FILE_DATA_URL`, `CONTENT_PART_TYPE_AUDIO_BASE64`, `CONTENT_PART_TYPE_REASONING` Variant 2: Type: `integer(int32)` Enum: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8` **content** `string` Text content, image URL, file ID, or base64-encoded data. **metadata** `map[string, string]` Additional type-specific metadata (dimensions, mime\_type, etc.). **cachePreferred** `boolean` Hint that this part is eligible for provider prompt caching. **structuredMessage** `any` Populated on TEXT parts for structured output responses. All of: Variant 1: A structured message whose JSON payload has been validated against a declared schema. Consumers can trust that json\_payload conforms to the schema identified by schema\_name. Inspect the run outcome before treating any message as complete. Current structured metadata is attached to a text content part through [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage) can be absent. Use an object at the schema root and validate the exact final response your application consumes; server validation covers only the first model choice. For integers that your JSON client cannot represent exactly, define string-valued fields in your schema instead of converting them through floating point. Model reference: [StructuredMessage](/api/models/schema-1ho1lk4ndj#request). **jsonPayload** `map[string, any]` The validated JSON payload as a Struct (preserves types) **schemaName** `string` Schema identifier (from ResponseFormat.schema\_name) **healed** `boolean` Whether response healing is reported for this structured message. Currently returned as false. **metadata** `map[string, string]` Provider-specific extras. **sequence** `string(int64)` Monotonic, per-conversation sequence number for stable ordering (1-based) Pattern: ^-?\d+$ **generatedBy** `string` Workflow run id or generator key that produced this message (e.g., workflow run key) **usage** `any` Token usage for this generation (populated for assistant messages) All of: Variant 1: Usage accounting Model reference: [Usage](/api/models/schema-1j1vov2uoh#request). **promptTokens** `string(int64)` Prompt-token usage reported by the model provider. Pattern: ^-?\d+$ **completionTokens** `string(int64)` Completion-token usage reported by the model provider. Pattern: ^-?\d+$ **totalTokens** `string(int64)` Total token usage reported by the model provider. Pattern: ^-?\d+$ **costEstimate** `any` Estimated cost in USD. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completionTokensDetails** `any` Breakdown of completion tokens. All of: Variant 1: Breakdown of completion-token usage. Categories are measured by different upstream tokenizers and need not sum to completion\_tokens; reasoning\_tokens can exceed completion\_tokens. One category must not be derived by subtracting the others. Model reference: [CompletionTokensDetails](/api/models/schema-1i6q4qpg72#request). **reasoningTokens** `string(int64)` Tokens used for reasoning/thinking. Pattern: ^-?\d+$ **imageTokens** `string(int64)` Completion tokens emitted as image output. Pattern: ^-?\d+$ **audioTokens** `string(int64)` Completion tokens emitted as audio output. Pattern: ^-?\d+$ **promptTokensDetails** `any` Breakdown of prompt tokens (cache). All of: Variant 1: Breakdown of prompt token usage by category (input-side cache accounting) Subset semantics: cached\_tokens and cache\_write\_tokens are a breakdown *of* prompt\_tokens, so cached\_tokens + cache\_write\_tokens \<= Usage.prompt\_tokens. Ordinary (full-rate) prompt tokens = prompt\_tokens - cached\_tokens - cache\_write\_tokens. audio\_tokens / video\_tokens are modality breakdowns of prompt\_tokens (also a subset). Model reference: [PromptTokensDetails](/api/models/schema-1ivj82m55o#request). **cachedTokens** `string(int64)` Prompt tokens served from cache (cache READ). Pattern: ^-?\d+$ **cacheWriteTokens** `string(int64)` Prompt tokens written to cache this call (cache WRITE). Pattern: ^-?\d+$ **audioTokens** `string(int64)` Prompt tokens from audio input (multimodal). Pattern: ^-?\d+$ **videoTokens** `string(int64)` Prompt tokens from video input (multimodal). Pattern: ^-?\d+$ **costDetails** `any` Breakdown of upstream provider cost (BYOK routes). All of: Variant 1: Breakdown of model-provider cost. When the customer supplies the provider key, usage.cost is zero and upstream\_inference\_cost reports the provider spend, split into prompt and completion components. Model reference: [CostDetails](/api/models/schema-1ia0h761lm#request). **upstreamInferenceCost** `any` Total upstream provider cost (USD) on BYOK routes. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferencePromptCost** `any` Upstream cost attributed to prompt tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferenceCompletionCost** `any` Upstream cost attributed to completion tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **isByok** `boolean` Whether this generation used the customer's own model-provider key. **model** `string` Model that generated this message (e.g., "anthropic/claude-sonnet-4") **generationContext** `any` Dynamic context that shaped this generation (memories, search params, turn info) All of: Variant 1: Snapshot of retrieval inputs, prompt provenance, and turn position that shaped a generated message. Model reference: [GenerationContext](/api/models/schema-1im79fphmq#request). **memories** `array[llm_v1_common_v1_MemoryReferenceInput]` Memory records captured in the generation context. A memory record retrieved and included in generation context. Model reference: [MemoryReference](/api/models/schema-1ie9a4bgk5#request). **memoryId** `string` Identifier of the retrieved memory record. **score** `any` Relevance score reported by the memory provider for this match. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **memoryText** `string` Text of the retrieved memory record. **createdAt** `string(date-time)` Time when this record was created. **updatedAt** `string(date-time)` Time when this record was last updated. **relations** `array[llm_v1_common_v1_RelationReferenceInput]` Graph relationships captured in the generation context. A graph relationship retrieved and included in generation context. Model reference: [RelationReference](/api/models/schema-1ijit8ceuv#request). **source** `string` Source entity of the memory graph relationship. **relationship** `string` Relationship label connecting the source and destination entities. **destination** `string` Destination entity of the memory graph relationship. **memorySearch** `any` Memory-query parameters and counts recorded for this generation. All of: Variant 1: Parameters used to retrieve relevant memories during generation. Model reference: [MemorySearchParams](/api/models/schema-1igd5iut01#request). **query** `string` Text submitted to memory retrieval for this generation. **topK** `string(int64)` Maximum memory matches requested during generation-context retrieval. Pattern: ^-?\d+$ **threshold** `any` Minimum relevance threshold requested for the memory query. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **rerank** `boolean` Whether reranking was requested for the memory search. **resultsReturned** `string(int64)` Number of memory records returned by the search. Pattern: ^-?\d+$ **relationsReturned** `string(int64)` Number of graph relationships returned by the search. Pattern: ^-?\d+$ **turn** `any` Turn position and limit within the generation run. All of: Variant 1: Turn position within an agentic generation run Model reference: [TurnInfo](/api/models/schema-1ilcikuhu8#request). **currentTurn** `string(int64)` Current turn position within the generation run. Pattern: ^-?\d+$ **maxTurns** `string(int64)` Maximum turns configured for the generation run. Pattern: ^-?\d+$ **languagePreference** `string` Language preference associated with the generation context. **resolvedSystemPrompt** `string` System prompt selected for this generation after prompt precedence is resolved. This field is retained in the schema but is not populated; use resolved\_prompt\_hash for recorded prompt identity. **profileId** `string` Agent profile that produced this message ("" if none active). **model** `string` Model actually used for this generation. **promptSource** `any` Which precedence tier supplied the prompt. Source that supplied the effective system prompt for a generation turn. Distinguishes a client override, a profile template and the conversation default configuration for prompt attribution.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROMPT_SOURCE_CLIENT_OVERRIDE` | 0 | Canonical | See meaning below. | | `PROMPT_SOURCE_PROFILE_TEMPLATE` | 1 | Canonical | See meaning below. | | `PROMPT_SOURCE_DEFAULT_CONFIG` | 2 | Canonical | See meaning below. | **`PROMPT_SOURCE_CLIENT_OVERRIDE`** The caller supplied the prompt through the send request's generation-configuration override. SendRequest.override\_generation\_config **`PROMPT_SOURCE_PROFILE_TEMPLATE`** The prompt was rendered from the active agent profile template. active agent profile's rendered template **`PROMPT_SOURCE_DEFAULT_CONFIG`** The prompt came from the conversation or project default generation configuration. conversation/project default\_generation\_config
Exactly one of: Variant 1: Type: `string` Enum: `PROMPT_SOURCE_CLIENT_OVERRIDE`, `PROMPT_SOURCE_PROFILE_TEMPLATE`, `PROMPT_SOURCE_DEFAULT_CONFIG` Variant 2: Type: `integer(int32)` **baseConfig** `any` Generation configuration resolved at send time before per-call overrides and timeout adjustments, with system\_prompt omitted. The active profile supplies the base when selected; otherwise the conversation default does. Use prompt\_source and profile\_id for prompt attribution. The base configuration can be absent when neither source supplies one or no snapshot was captured. For a supplied per-call override, the populated top-level fields of override\_config overlay base\_config to form the effective configuration. override\_config can be absent when no override was supplied. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#request). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#request). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#request). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#request). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#request). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#request). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinitionInput]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#request). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinitionInput]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRuleInput]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#request). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#request). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#request). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRuleInput]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#request). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#request). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfigInput]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#request). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#request). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#request). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#request). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) Minimum length: 2 Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$ **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#request). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" Maximum length: 50 **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" Enum: ``, `friendly`, `iso8601`, `date_only` Maximum length: 50 **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#request). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` **required** Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" Enum: `minimal`, `standard`, `verbose` **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#request). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#request). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **overrideConfig** `any` Per-call generation configuration supplied before the override merge. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#request). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#request). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#request). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#request). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#request). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#request). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinitionInput]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#request). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinitionInput]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRuleInput]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#request). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#request). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#request). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRuleInput]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#request). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#request). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfigInput]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#request). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#request). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#request). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#request). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) Minimum length: 2 Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$ **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#request). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" Maximum length: 50 **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" Enum: ``, `friendly`, `iso8601`, `date_only` Maximum length: 50 **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#request). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` **required** Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" Enum: `minimal`, `standard`, `verbose` **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#request). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#request). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **profileVersion** `string(int64)` Immutable version of the active agent profile used to render this turn’s prompt. Absent on older turns and turns without a profile template. Pattern: ^-?\d+$ **fragmentsVersion** `string(int64)` Version of the prompt-fragment set used to render the profile prompt. Pattern: ^-?\d+$ **promptVariables** `map[string, any]` Values bound to the prompt template for this generation. **profileRenderFailed** `boolean` Whether rendering the profile prompt failed for this generation. **resolvedPromptHash** `string` SHA-256 hash, as 64 hexadecimal characters, of the resolved system prompt before the current-time instruction is appended. Identifies prompt content only, excluding model and sampling parameters. Absent on older turns without prompt capture. **resolvedUserContext** `string` The literal user-context text supplied to the model for this turn, including the available name, locale and location conditions. It is a captured prompt input, not a reconstruction from the user’s current profile. The value is computed once per turn and reused across its model calls. It can be empty when location context is unavailable, enrichment fails or the turn predates capture. **resolvedMcpServers** `array[llm_v1_common_v1_MCPServerReferenceInput]` The MCP server list used for this turn after resolving conversation settings, the active profile, and any per-turn `override_mcp_servers`. It determines both tool discovery and the allow/block rules applied by `CallTool`. A per-turn override does not change the conversation's stored MCP settings. Compare this snapshot with `settings.mcp_servers` to inspect how the turn's tool set differed. Empty on turns predating capture and on threads with no MCP servers. MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#request). **serverId** `string` **required** ID of pre-configured MCP server (e.g., "github", "filesystem"). Minimum length: 1 **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **clientContext** `any` Arbitrary client-supplied context attached by the client for this message All of: Variant 1: Opaque caller-supplied attributes attached to a conversation message. Values are strings, including values such as `"false"`. The schema allows at most 32 pairs, keys of at most 64 characters, and values of at most 1,024 characters. Keep the entire map well below 8 KiB: Travila also applies an encoded-size limit that includes field overhead and drops context that exceeds it. Short page identifiers and a few relevant values are preferable to a page dump; an oversized map is not automatically shortened. Model reference: [ClientContext](/api/models/schema-1i2sndrl93#request). **values** `map[string, string]` Arbitrary client-supplied context for this message (e.g. page, referrer, device, in-app flow). Keys/values are opaque strings. Maximum properties: 32 **feedback** `array[llm_v1_common_v1_MessageFeedbackInput]` Feedback on an assistant message, with one entry per rater identified by rated\_by. A later rating by the same rater replaces their earlier entry. One user's feedback on an assistant-generated message. kind must select a listed feedback representation. Requiredness and allowed values are declared separately. Model reference: [MessageFeedback](/api/models/schema-1iroqctqt1#request). **kind** `any` **required** Rating representation used to interpret the feedback value. Value scale used to interpret recorded feedback.
| Value | No. | Form | Meaning | |---|---|---|---| | `FEEDBACK_KIND_THUMB` | 0 | Canonical | See meaning below. | | `FEEDBACK_KIND_SCALE` | 1 | Canonical | See meaning below. | **`FEEDBACK_KIND_THUMB`** Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. binary thumbs up / down **`FEEDBACK_KIND_SCALE`** Feedback expressed as an integer rating from 1 through 10. 1-10 integer scale
Exactly one of: Variant 1: Type: `string` Enum: `FEEDBACK_KIND_THUMB`, `FEEDBACK_KIND_SCALE` Variant 2: Type: `integer(int32)` Enum: `0`, `1` **thumbUp** `boolean` Positive when true and negative when false; used for THUMB feedback. **rating** `string(int64)` Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent. Pattern: ^-?\d+$ **reason** `string` Optional explanation for the rating. Maximum length: 1000 **ratedAt** `string(date-time)` Timestamp when feedback was submitted (server-set) **ratedBy** `string` Identifier of the user who submitted this feedback. Set by the server from the authenticated user identity; never client-supplied. Each user has one feedback entry per message. **sourceUserMessageId** `string` Identifier of the user message that opened this conversation turn. Generated messages in the same turn share this value; a user message carries its own message\_id. Empty on historical messages that predate turn attribution. Use this field for turn attribution rather than inferring it from message adjacency or a client-supplied message\_id. The generated\_by identifier groups messages by generation run but does not identify the user message that opened the turn. **finishReason** `string` Why the model stopped, verbatim from the provider: "stop", "tool\_calls", "length", "error". Empty for historical messages. #### conversations-appendMessage-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "conversationKey": "example_123", "message": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Hello" } ] } } ``` #### cookbook-managed-agents-conversations-generation-04-request Guide request for Separate recipe: record an onboarding event without another reply. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842", "message": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "CONTEXT UPDATE: user completed onboarding." } ] } } ``` ## Responses ### 200 — Message appended Content type: `application/json` Result of adding a message to conversation history without starting generation. This message declares no response fields. #### conversations-appendMessage-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json {} ``` Document ID: `DOC-MA-conversations-api-appendMessage`. [Section identities and revisions](/documentation-manifest.json). - Append a message without generating: `DOC-MA-conversations-api-appendMessage#overview` - Request: `DOC-MA-conversations-api-appendMessage#request` - Responses: `DOC-MA-conversations-api-appendMessage#responses` --- # Compact a conversation URL: https://docs.travila.ai/api/conversations/compact-conversation **POST** `/api/v1/llm/compact-conversation` Triggers context compaction, summarizing older conversation messages. The trigger estimate can differ from the next request's actual size, especially after changing prompts or tools. Leave room below the model limit and handle context-limit errors. When configured for asynchronous compaction, this call returns a pending result immediately. Use the returned `compactionId` to inspect the completed record in `conversation-state`'s `compactions` array. Compaction can still delay other messages in the conversation; asynchronous acceptance does not guarantee uninterrupted concurrent messaging. See [Context and compaction](/api/conversations/context-and-compaction) for strategy selection and outcome handling. Use this in a guide: [Resume a long conversation with a compacted history](/managed-agents/conversations/context-management) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for compacting the conversation’s model context. **conversationKey** `string` **required** Identifier of the conversation thread. Minimum length: 1 #### conversations-compactConversation-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "conversationKey": "example_123" } ``` #### cookbook-managed-agents-conversations-context-management-02-request Guide request for Recipe: compact the older history, then continue the thread. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "support-chat-001" } ``` ## Responses ### 200 — Compaction completed Content type: `application/json` Result of compacting the conversation's model context. Token counts describe the selected source span and its replacement summary, not the entire context window. Counts and duration are unavailable while asynchronous compaction is pending. **compactionId** `string` Identifier assigned to this context compaction. **tokensBefore** `string(int64)` Estimated tokens in the source messages being summarized, not the compaction trigger estimate. Pattern: ^-?\d+$ **tokensAfter** `string(int64)` Tokens in the generated summary, using provider-reported usage when available. Pattern: ^-?\d+$ **tokensSaved** `string(int64)` Source count minus summary count. The counts can use different methods; this is not an invoice saving. Pattern: ^-?\d+$ **durationMs** `string(int64)` Recorded compaction duration in milliseconds; it can be zero. Measure client elapsed time for latency comparisons. Pattern: ^-?\d+$ **status** `any` Status reported for this context compaction. Execution state of a conversation context-compaction attempt.
| Value | No. | Form | Meaning | |---|---|---|---| | `COMPACTION_STATUS_PENDING` | 0 | Canonical | Compaction was started and its result is still pending. | | `COMPACTION_STATUS_COMPLETED` | 1 | Canonical | Compaction completed and produced its result. | | `COMPACTION_STATUS_FAILED` | 2 | Canonical | Compaction failed; inspect the associated error. |
Exactly one of: Variant 1: Type: `string` Enum: `COMPACTION_STATUS_PENDING`, `COMPACTION_STATUS_COMPLETED`, `COMPACTION_STATUS_FAILED` Variant 2: Type: `integer(int32)` #### conversations-compactConversation-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "compactionId": "example_123", "tokensBefore": 1, "tokensAfter": 1, "tokensSaved": 1, "durationMs": "1", "status": "COMPACTION_STATUS_PENDING" } ``` #### cookbook-managed-agents-conversations-context-management-json-01-response Illustrative response for Recipe: compact the older history, then continue the thread. Replace example resource identifiers with your own authorized values. ```json { "compactionId": "cmp_a1b2c3d4", "tokensBefore": 48211, "tokensAfter": 604, "tokensSaved": 47607, "durationMs": "4120", "status": "COMPACTION_STATUS_COMPLETED" } ``` Document ID: `DOC-MA-conversations-api-compactConversation`. [Section identities and revisions](/documentation-manifest.json). - Compact a conversation: `DOC-MA-conversations-api-compactConversation#overview` - Request: `DOC-MA-conversations-api-compactConversation#request` - Responses: `DOC-MA-conversations-api-compactConversation#responses` --- # LLM APIs URL: https://docs.travila.ai/api/conversations Version: `aju17f20mq` Use the reference below for request and response fields and operation-specific requirements. # Overview \{#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](https://docs.travila.ai/managed-agents/voice-media). Native endpoints do not use the OpenAI wire protocol. ## Authentication \{#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](https://docs.travila.ai/core-platform/identity-access/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](https://docs.travila.ai/managed-agents/conversations), [Agent tools](https://docs.travila.ai/integrations/tools-connections), [Memory](https://docs.travila.ai/managed-agents/memory-knowledge), [Streaming availability](https://docs.travila.ai/managed-agents/conversations/streaming) ### JSON conventions \{#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](https://docs.travila.ai/api). ## Threads \{#reference-group-1} Conversation containers — create and list threads. See the [Conversations guide](https://docs.travila.ai/managed-agents/conversations) for thread lifecycle, async generation, and configuration. * [Create a new conversation thread](/api/conversations/create-thread) * [List conversation threads](/api/conversations/list-threads) ## Messages \{#reference-group-2} Send messages and trigger generation. See the [Conversations guide](https://docs.travila.ai/managed-agents/conversations) for the full message lifecycle and async polling recipe. * [Send a message to a conversation](/api/conversations/send-message) * [Append a message without generating](/api/conversations/append-message) * [Send a message and wait for the result](/api/conversations/send-message-sync) ## Conversations \{#reference-group-3} Conversation state, settings, and context management. See the [Conversations guide](https://docs.travila.ai/managed-agents/conversations). * [Update conversation settings](/api/conversations/update-settings) * [Update prompt variables](/api/conversations/update-prompt-variables) * [Update default generation config](/api/conversations/update-default-generation-config) * [Update context management settings](/api/conversations/update-context-management-settings) * [Compact a conversation](/api/conversations/compact-conversation) * [Get full conversation state](/api/conversations/get-conversation-state) ## Feedback \{#reference-group-4} 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. * [Rate an assistant message](/api/conversations/rate-message) * [Withdraw your rating on a message](/api/conversations/delete-message-rating) ## Voice \{#reference-group-5} Hosted-provider voice sessions; configured voice services and credentials are required. * [Create a voice session (in progress)](/api/conversations/create-daily-session) * [Mint a speech-to-text token (in progress)](/api/conversations/mint-stt-token) ## Tool Approvals \{#reference-group-6} Manage tool call approval workflows. See the [Agent tools guide](https://docs.travila.ai/integrations/tools-connections) for the full approval flow. * [List pending tool approvals](/api/conversations/list-pending-approvals) * [Approve or reject pending tool calls](/api/conversations/submit-tool-approvals) ## Client Tools \{#reference-group-7} Submit results from client-side tool executions. See the [Agent tools guide](https://docs.travila.ai/integrations/tools-connections) for client-side tool patterns. * [Submit client-side tool execution results](/api/conversations/submit-client-tool-results) * [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) * [List client-side tool calls awaiting a result](/api/conversations/list-pending-client-tools) * [Get a single tool call by ID](/api/conversations/get-tool-call) ## MCP Servers \{#reference-group-8} Discover and introspect registered MCP servers. See the [Agent tools guide](https://docs.travila.ai/integrations/tools-connections). * [List available MCP servers](/api/conversations/mcp-list-available-servers) * [Get detailed MCP server info](/api/conversations/mcp-get-server-info) ## MCP Tools \{#reference-group-9} List and directly invoke MCP tools. See the [Agent tools guide](https://docs.travila.ai/integrations/tools-connections). * [List available MCP tools](/api/conversations/mcp-list-tools) * [Execute an MCP tool](/api/conversations/mcp-call-tool) ## MCP Resources \{#reference-group-10} MCP resource retrieval is not yet available. These endpoints currently return empty responses. See the [Agent tools guide](https://docs.travila.ai/integrations/tools-connections). * [List MCP resources](/api/conversations/mcp-list-resources) * [Read an MCP resource](/api/conversations/mcp-read-resource) ## MCP Prompts \{#reference-group-11} MCP prompt retrieval is not yet available. These endpoints currently return empty responses. See the [Agent tools guide](https://docs.travila.ai/integrations/tools-connections). * [List MCP prompt templates](/api/conversations/mcp-list-prompts) * [Get an MCP prompt template](/api/conversations/mcp-get-prompt) ## Memory \{#reference-group-12} Semantic memory search and CRUD. See the [Memory guide](https://docs.travila.ai/managed-agents/memory-knowledge) for how memories integrate with conversations. * [Semantic search over memories](/api/conversations/search-memories) * [List user memories](/api/conversations/list-memories) * [Get a specific memory](/api/conversations/get-memory) * [Update a memory](/api/conversations/update-memory) * [Delete a memory](/api/conversations/delete-memory) ## Server 1 \{#reference-server-1} Travila API [https://api.travila.ai](https://api.travila.ai) ## X-API-Key \{#authentication-apiKeyAuth} 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 \{#authentication-onBehalfOf} 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 \{#authentication-bearerAuth} 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

### apiKeyAuth Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-API-Key` ### onBehalfOf Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-On-Behalf-Of` ### bearerAuth Security scheme type: `http` HTTP authorization scheme: `bearer` ## Operations - [Create a new conversation thread](/api/conversations/create-thread) — `POST /api/v1/llm/create-thread` - [List conversation threads](/api/conversations/list-threads) — `POST /api/v1/llm/list-threads` - [Send a message to a conversation](/api/conversations/send-message) — `POST /api/v1/llm/send-message` - [Append a message without generating](/api/conversations/append-message) — `POST /api/v1/llm/append-message` - [Rate an assistant message](/api/conversations/rate-message) — `POST /api/v1/llm/rate-message` - [Withdraw your rating on a message](/api/conversations/delete-message-rating) — `POST /api/v1/llm/delete-message-rating` - [Send a message and wait for the result](/api/conversations/send-message-sync) — `POST /api/v1/llm/send-message-sync` - [Update conversation settings](/api/conversations/update-settings) — `POST /api/v1/llm/update-settings` - [Update prompt variables](/api/conversations/update-prompt-variables) — `POST /api/v1/llm/update-prompt-variables` - [Update default generation config](/api/conversations/update-default-generation-config) — `POST /api/v1/llm/update-default-generation-config` - [Update context management settings](/api/conversations/update-context-management-settings) — `POST /api/v1/llm/update-context-management-settings` - [Compact a conversation](/api/conversations/compact-conversation) — `POST /api/v1/llm/compact-conversation` - [Get full conversation state](/api/conversations/get-conversation-state) — `POST /api/v1/llm/conversation-state` - [Create a voice session (in progress)](/api/conversations/create-daily-session) — `POST /api/v1/llm/create-daily-session` - [Mint a speech-to-text token (in progress)](/api/conversations/mint-stt-token) — `POST /api/v1/llm/stt-token` - [List pending tool approvals](/api/conversations/list-pending-approvals) — `POST /api/v1/llm/list-pending-approvals` - [Approve or reject pending tool calls](/api/conversations/submit-tool-approvals) — `POST /api/v1/llm/submit-tool-approvals` - [Submit client-side tool execution results](/api/conversations/submit-client-tool-results) — `POST /api/v1/llm/submit-client-tool-results` - [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) — `POST /api/v1/llm/submit-client-tool-results-sync` - [List client-side tool calls awaiting a result](/api/conversations/list-pending-client-tools) — `POST /api/v1/llm/list-pending-client-tools` - [Get a single tool call by ID](/api/conversations/get-tool-call) — `POST /api/v1/llm/get-tool-call` - [List available MCP servers](/api/conversations/mcp-list-available-servers) — `POST /api/v1/llm/mcp-list-available-servers` - [Get detailed MCP server info](/api/conversations/mcp-get-server-info) — `POST /api/v1/llm/mcp-get-server-info` - [List available MCP tools](/api/conversations/mcp-list-tools) — `POST /api/v1/llm/mcp-list-tools` - [Execute an MCP tool](/api/conversations/mcp-call-tool) — `POST /api/v1/llm/mcp-call-tool` - [List MCP resources](/api/conversations/mcp-list-resources) — `POST /api/v1/llm/mcp-list-resources` - [Read an MCP resource](/api/conversations/mcp-read-resource) — `POST /api/v1/llm/mcp-read-resource` - [List MCP prompt templates](/api/conversations/mcp-list-prompts) — `POST /api/v1/llm/mcp-list-prompts` - [Get an MCP prompt template](/api/conversations/mcp-get-prompt) — `POST /api/v1/llm/mcp-get-prompt` - [Semantic search over memories](/api/conversations/search-memories) — `POST /api/v1/llm/search-memories` - [List user memories](/api/conversations/list-memories) — `POST /api/v1/llm/list-memories` - [Get a specific memory](/api/conversations/get-memory) — `POST /api/v1/llm/get-memory` - [Update a memory](/api/conversations/update-memory) — `POST /api/v1/llm/update-memory` - [Delete a memory](/api/conversations/delete-memory) — `POST /api/v1/llm/delete-memory` Document ID: `DOC-API-conversations-overview`. [Section identities and revisions](/documentation-manifest.json). - 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` --- # Create a voice session (in progress) URL: https://docs.travila.ai/api/conversations/create-daily-session **POST** `/api/v1/llm/create-daily-session` Starts the configured hosted-provider voice session for an initialized conversation. Confirm room connection and agent readiness through provider events. A returned session alone does not establish that the agent joined or that transcripts were stored in conversation history. At session end, handle room expiry and the client's local capture separately; a local disconnect alone does not establish remote cleanup. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Add a spoken conversation to your app (Preview)](/managed-agents/voice-media) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Daily session (Pipecat) Input for starting a Pipecat voice session for the conversation. **conversationKey** `string` **required** Identifier of the conversation thread. Minimum length: 1 **agentName** `string` Name of the Pipecat agent to start for the voice session. required **socayoConfig** `any` Socayo-specific agent configuration All of: Variant 1: Socayo-specific agent configuration (bundled) Model reference: [SocayoAgentConfig](/api/models/schema-phip2o3ju4#request). **conversationKey** `string` **required** Conversation thread identifier associated with the voice session. Minimum length: 1 **userId** `string` **required** Identifier of the user associated with the operation. Minimum length: 1 **provider** `any` Backend provider to use for session orchestration; defaults to PIPECAT\_CLOUD Hosting backend used to deploy or start a voice agent.
| Value | No. | Form | Meaning | |---|---|---|---| | `AGENT_PROVIDER_PIPECAT_CLOUD` | 0 | Canonical | Use the Pipecat Cloud hosting backend. | | `AGENT_PROVIDER_CEREBRIUM` | 1 | Canonical | Use the Cerebrium hosting backend. |
Exactly one of: Variant 1: Type: `string` Enum: `AGENT_PROVIDER_PIPECAT_CLOUD`, `AGENT_PROVIDER_CEREBRIUM` Variant 2: Type: `integer(int32)` **tts** `any` Bundled sub-configs Speech-synthesis configuration supplied to the Socayo agent. All of: Variant 1: Cartesia Sonic-3 text-to-speech configuration for a Socayo agent. Model reference: [TTSConfig](/api/models/schema-on2m1c27d9#request). **voiceId** `string` **required** Provider-specific voice identifier (Cartesia voice\_id) Minimum length: 1 **model** `string` Optional Cartesia model identifier (e.g., "sonic-english") **sampleRate** `string(int64)` Optional sample rate override (Hz) Pattern: ^-?\d+$ **volume** `number(double)` **required** Volume multiplier (0.5..2.0) Minimum: 0.5 Maximum: 2 **speed** `number(double)` **required** Speed multiplier (0.6..1.5) Minimum: 0.6 Maximum: 1.5 **emotion** `string` Single emotion string (e.g., "neutral", "excited") **language** `string` Cartesia language code (e.g., "EN") **heygen** `any` HeyGen avatar and voice configuration for the Socayo agent. All of: Variant 1: HeyGen avatar/video configuration Model reference: [HeyGenConfig](/api/models/schema-pd3vbf0eel#request). **enabled** `boolean` Whether this configuration is enabled. **avatarId** `string` Identifier of the HeyGen avatar used for the session. **version** `string` Version of the resource represented by this message. **quality** `string` Video-quality setting requested for the HeyGen avatar. "high" | "medium" | "low" **videoEncoding** `string` Video codec requested for the HeyGen avatar stream. "H264" | "VP8" **voice** `any` Voice configuration used by the HeyGen avatar. All of: Variant 1: HeyGen voice settings Model reference: [HeyGenVoiceSettings](/api/models/schema-p3askj7st1#request). **voiceId** `string` Provider voice identifier used for speech synthesis. **rate** `any` Speech-rate setting passed to the HeyGen voice provider. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **emotion** `string` Emotion setting passed to HeyGen voice synthesis. "EXCITED" | "SERIOUS" | "FRIENDLY" | "SOOTHING" | "BROADCASTER" **elevenlabsSettings** `any` ElevenLabs synthesis settings associated with the HeyGen voice. All of: Variant 1: ElevenLabs settings used within HeyGen voice configuration Model reference: [HeyGenElevenLabsSettings](/api/models/schema-on0k8c8den#request). **stability** `any` ElevenLabs voice-stability setting passed through HeyGen. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **similarityBoost** `any` ElevenLabs voice-similarity setting passed through HeyGen. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **modelId** `string` ElevenLabs model identifier used for HeyGen voice synthesis. **style** `string(int64)` Integer style code. Pattern: ^-?\d+$ **useSpeakerBoost** `boolean` Whether ElevenLabs speaker boost is requested for the HeyGen voice. **knowledgeId** `string` Identifier of the HeyGen knowledge resource associated with the avatar. **knowledgeBase** `string` Knowledge text supplied to the HeyGen avatar configuration. **disableIdleTimeout** `boolean` Whether HeyGen’s session idle timeout is disabled. **activityIdleTimeout** `any` HeyGen activity idle timeout, in seconds. seconds Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **transport** `any` Audio transport settings used by the Socayo agent. All of: Variant 1: Transport audio configuration Model reference: [TransportConfig](/api/models/schema-on4mqk0ok8#request). **audioInSampleRate** `string(int64)` Sample rate of incoming audio, in hertz. Pattern: ^-?\d+$ **audioOutSampleRate** `string(int64)` Sample rate of outgoing audio, in hertz. Pattern: ^-?\d+$ **extras** `map[string, any]` Optional extras for forward-compat **createDailyRoom** `boolean` Whether session creation should also create a Daily room. **dailyRoomProperties** `any` Properties passed to Daily when creating the session room. All of: Variant 1: Daily room configuration (subset of frequently used fields) Model reference: [DailyRoomProperties](/api/models/schema-1kp6t31pq7#request). **nbf** `string(int64)` Earliest time at which the Daily room can be joined, as Unix seconds. Pattern: ^-?\d+$ **exp** `string(int64)` Expiration time of the Daily room, as Unix seconds. Pattern: ^-?\d+$ **maxParticipants** `string(int64)` Maximum number of participants allowed in the Daily room. Pattern: ^-?\d+$ **enablePeopleUi** `boolean` Whether the Daily room exposes participant-list controls. **enablePipUi** `boolean` Whether the Daily room enables picture-in-picture controls. **enableEmojiReactions** `boolean` Whether the Daily room enables emoji reactions. **enableHandRaising** `boolean` Whether the Daily room enables hand-raising controls. **enablePrejoinUi** `boolean` Whether the Daily room enables its prejoin screen. **enableLiveCaptionsUi** `boolean` Whether the Daily room exposes live-caption controls. **enableNetworkUi** `boolean` Whether the Daily room exposes network-information controls. **enableNoiseCancellationUi** `boolean` Whether the Daily room exposes noise-cancellation controls. **enableBreakoutRooms** `boolean` Whether the Daily room enables breakout rooms. **enableKnocking** `boolean` When true, requests Daily’s knocking feature for a private room, allowing a participant without a meeting token to ask a meeting owner for admission. It does not restrict a public room. The current room-property mapping forwards true only; false or omission does not explicitly disable a provider setting. **ownerOnlyBroadcast** `boolean` Whether broadcasting is restricted to Daily room owners. **enforceUniqueUserIds** `boolean` Whether the Daily room requires participant user identifiers to be unique. **enableScreenshare** `boolean` Whether screen sharing is enabled in the Daily room. **enableVideoProcessingUi** `boolean` Whether the Daily room exposes video-processing controls. **enableChat** `boolean` Whether chat is enabled in the Daily room. **enableSharedChatHistory** `boolean` Whether the Daily room enables shared chat history. **enableAdvancedChat** `boolean` Whether the Daily room enables advanced chat features. **enableHiddenParticipants** `boolean` Whether the Daily room allows hidden participants. **startVideoOff** `boolean` Whether participants join the Daily room with video initially off. **startAudioOff** `boolean` Whether participants join the Daily room with audio initially off. **enableRecording** `any` Recording mode configured for the Daily room. Recording mode requested when configuring a Daily room.
| Value | No. | Form | Meaning | |---|---|---|---| | `RECORDING_MODE_CLOUD` | 0 | Canonical | See meaning below. | | `RECORDING_MODE_LOCAL` | 1 | Canonical | See meaning below. | | `RECORDING_MODE_RAW_TRACKS` | 2 | Canonical | See meaning below. | | `RECORDING_MODE_DISABLED` | 3 | Canonical | See meaning below. | **`RECORDING_MODE_CLOUD`** Request the provider's cloud recording mode. "cloud" **`RECORDING_MODE_LOCAL`** Request the provider's local recording mode. "local" **`RECORDING_MODE_RAW_TRACKS`** Request separate raw media tracks for recording. "raw-tracks" **`RECORDING_MODE_DISABLED`** Explicitly disable room recording. explicitly disabled
Exactly one of: Variant 1: Type: `string` Enum: `RECORDING_MODE_CLOUD`, `RECORDING_MODE_LOCAL`, `RECORDING_MODE_RAW_TRACKS`, `RECORDING_MODE_DISABLED` Variant 2: Type: `integer(int32)` **ejectAtRoomExp** `boolean` Whether participants are removed when the Daily room expires. **ejectAfterElapsed** `string(int64)` Elapsed session duration after which participants are removed, in seconds. Pattern: ^-?\d+$ **enableMeshSfu** `boolean` When true, forwards Daily’s `enable_mesh_sfu` room-topology option. Confirm provider support and its effect for your Daily account before relying on it. The current room-property mapping forwards true only; false or omission does not explicitly disable a provider setting. **sfuSwitchover** `any` Daily topology setting controlling the switch to SFU transport. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enableAdaptiveSimulcast** `boolean` Whether adaptive simulcast is enabled for the Daily room. **enableMultipartyAdaptiveSimulcast** `boolean` Whether multiparty adaptive simulcast is enabled for the Daily room. **experimentalOptimizeLargeCalls** `boolean` Whether Daily’s experimental large-call optimization is requested. **lang** `string` Language code configured for the Daily room interface, such as en, es, or pt-BR. **meetingJoinHook** `string` Webhook URL invoked by the Daily meeting-join hook. **geo** `string` Region selected for the Daily room media infrastructure, such as eu-west-2. **rtmpGeo** `string` Region selected for Daily RTMP streaming, such as us-west-2. **disableRtmpGeoFallback** `boolean` Whether automatic RTMP region fallback is disabled. **recordingsBucket** `any` Storage destination configured for Daily recordings. All of: Variant 1: Object-storage destination and access settings for Daily recordings. Model reference: [RecordingBucketConfig](/api/models/schema-1klrt9eoq8#request). **bucketName** `string` Object-storage bucket used for Daily recordings. **bucketRegion** `string` Region containing the Daily recordings bucket. **assumeRoleArn** `string` Role ARN Daily uses when accessing the storage bucket. **allowApiAccess** `boolean` Whether Daily API access to bucket content is enabled. **allowStreamingFromBucket** `boolean` Whether streaming directly from the recording bucket is enabled. **transcriptionBucket** `any` Storage destination configured for Daily transcriptions. All of: Variant 1: Object-storage destination and access settings for Daily transcriptions. Model reference: [TranscriptionBucketConfig](/api/models/schema-1knm9ns9ab#request). **bucketName** `string` Object-storage bucket used for Daily transcriptions. **bucketRegion** `string` Region containing the Daily transcriptions bucket. **assumeRoleArn** `string` Role ARN Daily uses when accessing the storage bucket. **allowApiAccess** `boolean` Whether Daily API access to bucket content is enabled. **recordingsTemplate** `string` Template used for recording object names in storage. **transcriptionTemplate** `string` Template used for transcription object names in storage. **dailyMeetingTokenProperties** `any` Properties passed to Daily when issuing the meeting token. All of: Variant 1: Daily meeting token configuration (subset of common fields) Model reference: [DailyMeetingTokenProperties](/api/models/schema-1kic2mada4#request). **isOwner** `boolean` Whether the issued Daily meeting token grants room-owner privileges. **enableAutoRecording** `boolean` Whether the Daily meeting token requests automatic recording. **userData** `any` User data passed to the Pipecat agent at session startup. All of: Variant 1: Arbitrary user data passed when starting a session, as simple key/value pairs Model reference: [StartSessionUserData](/api/models/schema-1kri473p8r#request). **fields** `map[string, any]` Structured user data passed to the session-start request. #### conversations-createDailySession-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "conversationKey": "example_123" } ``` #### cookbook-managed-agents-voice-media-index-01-request Guide request for Step 1: Start the voice session for the existing thread. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "support-chat-001", "agentName": "my-voice-agent", "createDailyRoom": true, "dailyRoomProperties": { "enableRecording": "RECORDING_MODE_DISABLED" } } ``` ## Responses ### 200 — Voice session created Content type: `application/json` Result of starting a Pipecat voice session for the conversation. **session** `any` Daily voice session connection information. All of: Variant 1: Session metadata for a Daily/Pipecat voice session Model reference: [DailySession](/api/models/schema-1ktuo6mcah#response). **agentName** `string` Name of the Pipecat agent running this voice session. **sessionId** `string` Identifier of the Pipecat voice session. **dailyRoom** `string` Daily room address associated with the voice session. **dailyToken** `string` Daily meeting token issued for the voice session. **userData** `any` Generic body payload used to start. All of: Variant 1: Arbitrary user data passed when starting a session, as simple key/value pairs Model reference: [StartSessionUserData](/api/models/schema-1kri473p8r#response). **fields** `map[string, any]` Structured user data passed to the session-start request. **dailyRoomProperties** `any` Properties passed to Daily when configuring the session room. All of: Variant 1: Daily room configuration (subset of frequently used fields) Model reference: [DailyRoomProperties](/api/models/schema-1kp6t31pq7#response). **nbf** `string(int64)` Earliest time at which the Daily room can be joined, as Unix seconds. Pattern: ^-?\d+$ **exp** `string(int64)` Expiration time of the Daily room, as Unix seconds. Pattern: ^-?\d+$ **maxParticipants** `string(int64)` Maximum number of participants allowed in the Daily room. Pattern: ^-?\d+$ **enablePeopleUi** `boolean` Whether the Daily room exposes participant-list controls. **enablePipUi** `boolean` Whether the Daily room enables picture-in-picture controls. **enableEmojiReactions** `boolean` Whether the Daily room enables emoji reactions. **enableHandRaising** `boolean` Whether the Daily room enables hand-raising controls. **enablePrejoinUi** `boolean` Whether the Daily room enables its prejoin screen. **enableLiveCaptionsUi** `boolean` Whether the Daily room exposes live-caption controls. **enableNetworkUi** `boolean` Whether the Daily room exposes network-information controls. **enableNoiseCancellationUi** `boolean` Whether the Daily room exposes noise-cancellation controls. **enableBreakoutRooms** `boolean` Whether the Daily room enables breakout rooms. **enableKnocking** `boolean` When true, requests Daily’s knocking feature for a private room, allowing a participant without a meeting token to ask a meeting owner for admission. It does not restrict a public room. The current room-property mapping forwards true only; false or omission does not explicitly disable a provider setting. **ownerOnlyBroadcast** `boolean` Whether broadcasting is restricted to Daily room owners. **enforceUniqueUserIds** `boolean` Whether the Daily room requires participant user identifiers to be unique. **enableScreenshare** `boolean` Whether screen sharing is enabled in the Daily room. **enableVideoProcessingUi** `boolean` Whether the Daily room exposes video-processing controls. **enableChat** `boolean` Whether chat is enabled in the Daily room. **enableSharedChatHistory** `boolean` Whether the Daily room enables shared chat history. **enableAdvancedChat** `boolean` Whether the Daily room enables advanced chat features. **enableHiddenParticipants** `boolean` Whether the Daily room allows hidden participants. **startVideoOff** `boolean` Whether participants join the Daily room with video initially off. **startAudioOff** `boolean` Whether participants join the Daily room with audio initially off. **enableRecording** `any` Recording mode configured for the Daily room. Recording mode requested when configuring a Daily room.
| Value | No. | Form | Meaning | |---|---|---|---| | `RECORDING_MODE_CLOUD` | 0 | Canonical | See meaning below. | | `RECORDING_MODE_LOCAL` | 1 | Canonical | See meaning below. | | `RECORDING_MODE_RAW_TRACKS` | 2 | Canonical | See meaning below. | | `RECORDING_MODE_DISABLED` | 3 | Canonical | See meaning below. | **`RECORDING_MODE_CLOUD`** Request the provider's cloud recording mode. "cloud" **`RECORDING_MODE_LOCAL`** Request the provider's local recording mode. "local" **`RECORDING_MODE_RAW_TRACKS`** Request separate raw media tracks for recording. "raw-tracks" **`RECORDING_MODE_DISABLED`** Explicitly disable room recording. explicitly disabled
Exactly one of: Variant 1: Type: `string` Enum: `RECORDING_MODE_CLOUD`, `RECORDING_MODE_LOCAL`, `RECORDING_MODE_RAW_TRACKS`, `RECORDING_MODE_DISABLED` Variant 2: Type: `integer(int32)` **ejectAtRoomExp** `boolean` Whether participants are removed when the Daily room expires. **ejectAfterElapsed** `string(int64)` Elapsed session duration after which participants are removed, in seconds. Pattern: ^-?\d+$ **enableMeshSfu** `boolean` When true, forwards Daily’s `enable_mesh_sfu` room-topology option. Confirm provider support and its effect for your Daily account before relying on it. The current room-property mapping forwards true only; false or omission does not explicitly disable a provider setting. **sfuSwitchover** `any` Daily topology setting controlling the switch to SFU transport. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enableAdaptiveSimulcast** `boolean` Whether adaptive simulcast is enabled for the Daily room. **enableMultipartyAdaptiveSimulcast** `boolean` Whether multiparty adaptive simulcast is enabled for the Daily room. **experimentalOptimizeLargeCalls** `boolean` Whether Daily’s experimental large-call optimization is requested. **lang** `string` Language code configured for the Daily room interface, such as en, es, or pt-BR. **meetingJoinHook** `string` Webhook URL invoked by the Daily meeting-join hook. **geo** `string` Region selected for the Daily room media infrastructure, such as eu-west-2. **rtmpGeo** `string` Region selected for Daily RTMP streaming, such as us-west-2. **disableRtmpGeoFallback** `boolean` Whether automatic RTMP region fallback is disabled. **recordingsBucket** `any` Storage destination configured for Daily recordings. All of: Variant 1: Object-storage destination and access settings for Daily recordings. Model reference: [RecordingBucketConfig](/api/models/schema-1klrt9eoq8#response). **bucketName** `string` Object-storage bucket used for Daily recordings. **bucketRegion** `string` Region containing the Daily recordings bucket. **assumeRoleArn** `string` Role ARN Daily uses when accessing the storage bucket. **allowApiAccess** `boolean` Whether Daily API access to bucket content is enabled. **allowStreamingFromBucket** `boolean` Whether streaming directly from the recording bucket is enabled. **transcriptionBucket** `any` Storage destination configured for Daily transcriptions. All of: Variant 1: Object-storage destination and access settings for Daily transcriptions. Model reference: [TranscriptionBucketConfig](/api/models/schema-1knm9ns9ab#response). **bucketName** `string` Object-storage bucket used for Daily transcriptions. **bucketRegion** `string` Region containing the Daily transcriptions bucket. **assumeRoleArn** `string` Role ARN Daily uses when accessing the storage bucket. **allowApiAccess** `boolean` Whether Daily API access to bucket content is enabled. **recordingsTemplate** `string` Template used for recording object names in storage. **transcriptionTemplate** `string` Template used for transcription object names in storage. **dailyMeetingTokenProperties** `any` Properties passed to Daily when issuing the meeting token. All of: Variant 1: Daily meeting token configuration (subset of common fields) Model reference: [DailyMeetingTokenProperties](/api/models/schema-1kic2mada4#response). **isOwner** `boolean` Whether the issued Daily meeting token grants room-owner privileges. **enableAutoRecording** `boolean` Whether the Daily meeting token requests automatic recording. **startedAt** `string(date-time)` Time when the operation started. #### conversations-createDailySession-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "session": { "agentName": "example", "sessionId": "example_123", "dailyRoom": "example", "dailyToken": "example", "userData": {}, "dailyRoomProperties": { "nbf": "1", "exp": "1", "maxParticipants": 1, "enablePeopleUi": true, "enablePipUi": true, "enableEmojiReactions": true, "enableHandRaising": true, "enablePrejoinUi": true, "enableLiveCaptionsUi": true, "enableNetworkUi": true, "enableNoiseCancellationUi": true, "enableBreakoutRooms": true, "enableKnocking": true, "ownerOnlyBroadcast": true, "enforceUniqueUserIds": true, "enableScreenshare": true, "enableVideoProcessingUi": true, "enableChat": true, "enableSharedChatHistory": true, "enableAdvancedChat": true, "enableHiddenParticipants": true, "startVideoOff": true, "startAudioOff": true, "enableRecording": "RECORDING_MODE_CLOUD", "ejectAtRoomExp": true, "ejectAfterElapsed": 1, "enableMeshSfu": true, "sfuSwitchover": 1, "enableAdaptiveSimulcast": true, "enableMultipartyAdaptiveSimulcast": true, "experimentalOptimizeLargeCalls": true, "lang": "example", "meetingJoinHook": "example", "geo": "example", "rtmpGeo": "example", "disableRtmpGeoFallback": true, "recordingsTemplate": "example", "transcriptionTemplate": "example" }, "dailyMeetingTokenProperties": { "isOwner": true, "enableAutoRecording": true }, "startedAt": "2026-09-16T12:00:00Z" } } ``` #### cookbook-managed-agents-voice-media-index-json-01-response Illustrative response for Step 2: Join the room and confirm the exchange. Replace example resource identifiers with your own authorized values. ```json { "session": { "sessionId": "sess_abc123", "agentName": "my-voice-agent", "dailyRoom": "travila-abc123", "dailyToken": "eyJ...", "startedAt": "2026-08-17T10:00:00Z", "userData": { "fields": { "displayName": "Alex" } }, "dailyRoomProperties": { "exp": "1786964400" }, "dailyMeetingTokenProperties": { "isOwner": false } } } ``` Document ID: `DOC-MA-conversations-api-createDailySession`. [Section identities and revisions](/documentation-manifest.json). - Create a voice session (in progress): `DOC-MA-conversations-api-createDailySession#overview` - Request: `DOC-MA-conversations-api-createDailySession#request` - Responses: `DOC-MA-conversations-api-createDailySession#responses` --- # Create a new conversation thread URL: https://docs.travila.ai/api/conversations/create-thread **POST** `/api/v1/llm/create-thread` Creates a conversation thread for the authenticated user. Use this in a guide: [Build a support conversation the user can return to](/managed-agents/conversations) · [Let a customer navigate your app through chat](/managed-agents/delegation-approvals/build-agent-with-tools) · [Build a reusable assistant profile](/managed-agents/profiles-prompts) · [Build a research, bulk-summary or structured-summary flow](/managed-agents/model-controls/examples) · [Route an image question to a capable model](/managed-agents/model-controls/filtering) · [Keep a model on the providers you choose](/managed-agents/model-controls/provider-pinning) · [Build a signed-in support chat that survives reconnects](/managed-agents/conversations/build-chat-assistant) · [Configure a support conversation that stays predictable](/managed-agents/conversations/configuration) · [Complete your first support-chat turn](/managed-agents/conversations/quickstart) · [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps) · [Profile selection and prompt versions](/api/agent-profiles/selection-and-versioning) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Thread management Input for creating a conversation thread with its initial configuration. **title** `string` Display title of the conversation thread. **tags** `array[string]` Labels associated with the conversation thread. Type: `string` **activeProfileId** `string` Agent profile selected as the conversation’s active profile at creation. **activeProfileVersion** `string(int64)` Immutable version of the active profile to use. Zero selects its latest version. Pattern: ^-?\d+$ **externalId** `string` Caller-supplied identifier associated with the conversation thread. Maximum length: 255 **defaultGenerationConfig** `any` Base model and tool configuration for turns in this conversation. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#request). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#request). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#request). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#request). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#request). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#request). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinitionInput]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#request). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinitionInput]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRuleInput]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#request). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#request). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#request). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRuleInput]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#request). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#request). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfigInput]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#request). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#request). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#request). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#request). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) Minimum length: 2 Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$ **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#request). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" Maximum length: 50 **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" Enum: ``, `friendly`, `iso8601`, `date_only` Maximum length: 50 **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#request). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` **required** Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" Enum: `minimal`, `standard`, `verbose` **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#request). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#request). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **conversationSettings** `any` Initial conversation settings, including prompt and integration configuration. All of: Variant 1: Conversation-level settings controlling behavior across sends [`maxLoops`](/api/models/schema-ph6avse89k#request-field-maxloops) caps the **total number of generations** in a run — not the number of tool round trips. Default is **2**, which is what one round trip costs: a first generation to emit the tool call, a second to synthesize its result. On the final generation the model is sent **no tools at all** (the request omits the [`tools`](/api/models/schema-1h82h7ri5p#request-field-tools) array), so it cannot emit a call there. `maxLoops: 1` therefore means a single tool-free reply — a valid way to ask for one, but not a way to get one tool round trip. Model reference: [ConversationSettings](/api/models/schema-ph6avse89k#request). **interruptPolicy** `any` Policy for an incoming message while another generation run is active. How a conversation handles a new send while another generation run is active.
| Value | No. | Form | Meaning | |---|---|---|---| | `INTERRUPT_POLICY_REJECT_NEW` | 0 | Canonical | See meaning below. | | `INTERRUPT_POLICY_CANCEL_ONGOING` | 1 | Canonical | See meaning below. | | `INTERRUPT_POLICY_QUEUE` | 2 | Canonical | See meaning below. | | `INTERRUPT_POLICY_IGNORE` | 3 | Canonical | Accept the send without persisting its message or starting a new run; let the ongoing run continue. | **`INTERRUPT_POLICY_REJECT_NEW`** Reject the new send with an error while a run is active; do not append its user message. Reject the new Send with an error if a run is active **`INTERRUPT_POLICY_CANCEL_ONGOING`** Cancel the ongoing run and start a new run for the incoming message. Cancel the ongoing run and immediately start a new one with the new message **`INTERRUPT_POLICY_QUEUE`** Queue the incoming message to run after the current run completes. Queue the new Send; it will run after the current run completes
Exactly one of: Variant 1: Type: `string` Enum: `INTERRUPT_POLICY_REJECT_NEW`, `INTERRUPT_POLICY_CANCEL_ONGOING`, `INTERRUPT_POLICY_QUEUE`, `INTERRUPT_POLICY_IGNORE` Variant 2: Type: `integer(int32)` **maxLoops** `string(int64)` Default limit on agentic generation loops for the conversation. Pattern: ^-?\d+$ **maxParallelTools** `string(int64)` Maximum number of tool executions allowed concurrently by this configuration. Pattern: ^-?\d+$ **mcpServers** `array[llm_v1_common_v1_MCPServerReferenceInput]` MCP servers available to this conversation; used for tool discovery/filtering MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#request). **serverId** `string` **required** ID of pre-configured MCP server (e.g., "github", "filesystem"). Minimum length: 1 **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **toolPolicy** `any` Optional per-conversation tool execution policy applied to AgentConfig All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRuleInput]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#request). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#request). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#request). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRuleInput]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#request). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **promptVariables** `map[string, any]` Typed values used when rendering profile prompt templates. Numbers, arrays, Boolean values and strings retain their respective JSON types. The values are shared by profiles in the conversation and can be refreshed with UpdatePromptVariables. Switching profiles renders the new template with the same values. **contextManagementSettings** `any` Optional context-management settings for the new conversation. All of: Variant 1: Configuration for context management Model reference: [ContextManagementSettings](/api/models/schema-1hgrvsu34j#request). **strategy** `any` Context management strategy selected for the conversation. How stored conversation history is selected or summarized for model context.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTEXT_STRATEGY_COMPACTION` | 0 | Canonical | Use completed compaction summaries and remaining history; fall back to windowing when no completed summary is available. | | `CONTEXT_STRATEGY_WINDOWING` | 1 | Canonical | Keep a bounded window of recent conversation messages according to the windowing configuration. | | `CONTEXT_STRATEGY_NONE` | 2 | Canonical | Pass the conversation history without applying compaction or windowing. |
Exactly one of: Variant 1: Type: `string` Enum: `CONTEXT_STRATEGY_COMPACTION`, `CONTEXT_STRATEGY_WINDOWING`, `CONTEXT_STRATEGY_NONE` Variant 2: Type: `integer(int32)` **compactionConfig** `any` Configuration applied when summarizing the conversation context. All of: Variant 1: Configuration for compaction strategy Model reference: [CompactionConfig](/api/models/schema-1hbvkcgu5m#request). **mode** `any` Context compaction mode selected by the operation. SYNC, ASYNC Whether context compaction blocks the triggering operation or proceeds asynchronously.
| Value | No. | Form | Meaning | |---|---|---|---| | `COMPACTION_MODE_SYNC` | 0 | Canonical | Wait for compaction to finish before continuing the dependent operation. | | `COMPACTION_MODE_ASYNC` | 1 | Canonical | Start compaction asynchronously and apply its result when it becomes available. |
Exactly one of: Variant 1: Type: `string` Enum: `COMPACTION_MODE_SYNC`, `COMPACTION_MODE_ASYNC` Variant 2: Type: `integer(int32)` **threshold** `any` Token-count or context-window-percentage threshold that triggers compaction. All of: Variant 1: Threshold configuration for triggering compaction token\_count and percentage are mutually exclusive alternatives. Independent tracked fields do not enforce this relationship. Model reference: [ThresholdConfig](/api/models/schema-1frig4k431#request). **tokenCount** `string(int64)` Absolute token limit. Pattern: ^-?\d+$ **percentage** `string(int64)` % of model's context window. Pattern: ^-?\d+$ **generationConfig** `any` Separate config for compaction LLM calls. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#request). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#request). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#request). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#request). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#request). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#request). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinitionInput]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#request). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinitionInput]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRuleInput]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#request). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#request). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#request). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRuleInput]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#request). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#request). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfigInput]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#request). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#request). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#request). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#request). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) Minimum length: 2 Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$ **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#request). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" Maximum length: 50 **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" Enum: ``, `friendly`, `iso8601`, `date_only` Maximum length: 50 **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#request). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` **required** Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" Enum: `minimal`, `standard`, `verbose` **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#request). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#request). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **preserveRecent** `string(int64)` Messages to keep uncompacted. Pattern: ^-?\d+$ **windowingConfig** `any` Rules selecting the message window retained in model context. All of: Variant 1: Configuration for windowing strategy Model reference: [WindowingConfig](/api/models/schema-1he7ulevif#request). **maxMessages** `string(int64)` Maximum number of conversation messages to retain in the context window. Default: 100 Pattern: ^-?\d+$ **selectiveExclusionConfig** `any` Rules selecting content to omit from the model context. All of: Variant 1: Configuration for selective exclusion Model reference: [SelectiveExclusionConfig](/api/models/schema-1hc73qpaio#request). **excludeToolResults** `boolean` Whether tool-result content is excluded from model context. **excludeImages** `boolean` Whether image content is excluded from model context. **excludeFiles** `boolean` Whether file content is excluded from model context. **excludeReasoning** `boolean` When true, reasoning/thinking content parts are excluded from context #### conversations-createThread-request Create a titled conversation; identity comes from authenticated context. ```json { "title": "Travel planning", "tags": [ "travel" ] } ``` #### cookbook-integrations-tools-connections-connected-apps-04-request Guide request for 2. Give this conversation access to the calendar. Replace example resource identifiers with your own authorized values. ```json { "conversationSettings": { "mcpServers": [ { "serverId": "pipedream:google_calendar", "enabled": true } ] } } ``` #### cookbook-managed-agents-conversations-build-chat-assistant-02-request Guide request for Step 2: Start one support conversation. Replace example resource identifiers with your own authorized values. ```json { "title": "My First Thread" } ``` #### cookbook-managed-agents-conversations-index-01-request Guide request for Step 1: Create the support thread once. Replace example resource identifiers with your own authorized values. ```json { "title": "Support Chat" } ``` #### cookbook-managed-agents-delegation-approvals-build-agent-with-tools-01-request Guide request for Step 1: Describe the navigation your app can perform. Replace example resource identifiers with your own authorized values. ```json { "defaultGenerationConfig": { "clientTools": [ { "name": "navigate_to", "serverId": "client", "description": "Navigate the app to a given screen", "parametersJsonSchema": { "type": "object", "properties": { "screen": { "type": "string", "description": "Screen identifier, e.g. \"/settings\"" } }, "required": [ "screen" ] } } ] } } ``` #### cookbook-managed-agents-model-controls-examples-01-request Guide request for Recipe: keep a research conversation on large-context candidates. Replace example resource identifiers with your own authorized values. ```json { "title": "Long research thread", "defaultGenerationConfig": { "models": [ "google/gemini-3.6-flash:nitro", "anthropic/claude-sonnet-4.6:nitro", "anthropic/claude-sonnet-5" ], "modelRoutingFilter": { "minContextLength": 128000 } } } ``` #### cookbook-managed-agents-model-controls-filtering-02-request Guide request for Variant: keep a capability requirement for a long research thread. Replace example resource identifiers with your own authorized values. ```json { "title": "Long research thread", "defaultGenerationConfig": { "models": [ "google/gemini-3.6-flash:nitro", "anthropic/claude-sonnet-4.6:nitro", "anthropic/claude-sonnet-5" ], "modelRoutingFilter": { "minContextLength": "128000" } } } ``` #### cookbook-managed-agents-conversations-configuration-json-01-request Guide request for Variant: reuse the same assistant setup across conversations. Replace example resource identifiers with your own authorized values. ```json { "title": "Nutrition check-in", "activeProfileId": "nutrition_coach" } ``` ## Responses ### 200 — Thread created successfully Content type: `application/json` Result of creating a conversation thread with its initial configuration. **thread** `any` Conversation thread returned by creation. All of: Variant 1: Lightweight conversation-thread registry record used for managing multiple threads. Model reference: [ConversationThread](/api/models/schema-1i84dsgmg6#response). **threadId** `string` Identifier of the conversation thread. key used for ConversationActorService **title** `string` Display title of the conversation thread. **tags** `array[string]` Labels associated with the resource for organization or filtering. Type: `string` **createdAt** `string(date-time)` Time when this record was created. **updatedAt** `string(date-time)` Time when this record was last updated. **externalId** `string` Caller-supplied identifier associated with the conversation thread. #### conversations-createThread-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "thread": { "threadId": "example_123", "title": "example", "tags": [ "example" ], "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z", "externalId": "example_123" } } ``` #### cookbook-managed-agents-conversations-build-chat-assistant-json-02-response Illustrative response for Step 2: Start one support conversation. Replace example resource identifiers with your own authorized values. ```json { "thread": { "threadId": "b81d5345-c1f9-4fb9-b558-a6327c75b842", "title": "My First Thread", "createdAt": "2026-04-23T16:34:02.673Z", "updatedAt": "2026-04-23T16:34:02.673Z" } } ``` #### cookbook-managed-agents-delegation-approvals-build-agent-with-tools-json-01-response Illustrative response for Step 1: Describe the navigation your app can perform. Replace example resource identifiers with your own authorized values. ```json { "thread": { "threadId": "b81d5345-c1f9-4fb9-b558-a6327c75b842" } } ``` Document ID: `DOC-MA-conversations-api-createThread`. [Section identities and revisions](/documentation-manifest.json). - Create a new conversation thread: `DOC-MA-conversations-api-createThread#overview` - Request: `DOC-MA-conversations-api-createThread#request` - Responses: `DOC-MA-conversations-api-createThread#responses` --- # Delete a memory URL: https://docs.travila.ai/api/conversations/delete-memory **POST** `/api/v1/llm/delete-memory` Requests deletion of a memory by ID. Full project/user ownership checks are not currently enforced for these by-ID operations. They are not a supported access boundary for an untrusted end-user client. Deletion does not remove copies already included in conversation context or confirm backup erasure. See [Memory](/managed-agents/memory-knowledge). The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Use remembered preferences in a returning user’s conversation](/managed-agents/memory-knowledge) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for deleting a memory record by its identifier. **memoryId** `string` **required** Memory ID to delete Minimum length: 1 #### conversations-deleteMemory-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "memoryId": "example_123" } ``` #### cookbook-managed-agents-memory-knowledge-index-05-request Guide request for Remove the selected record. Replace example resource identifiers with your own authorized values. ```json { "memoryId": "mem_abc123" } ``` ## Responses ### 200 — Memory deleted Content type: `application/json` Result of deleting a memory record by its identifier. **success** `boolean` Whether deletion was successful #### conversations-deleteMemory-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "success": true } ``` Document ID: `DOC-MA-conversations-api-deleteMemory`. [Section identities and revisions](/documentation-manifest.json). - Delete a memory: `DOC-MA-conversations-api-deleteMemory#overview` - Request: `DOC-MA-conversations-api-deleteMemory#request` - Responses: `DOC-MA-conversations-api-deleteMemory#responses` --- # Withdraw your rating on a message URL: https://docs.travila.ai/api/conversations/delete-message-rating **POST** `/api/v1/llm/delete-message-rating` Removes the caller's own rating from a message. As with `rate-message`, the rater is derived server-side from the verified request headers. This is idempotent: withdrawing a rating that was never left is a success, not an error — the response returns `removed: false` in that case. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Collect message feedback](/insights/evaluation/message-feedback) · [Feedback and score attribution](/api/evals/scoring) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Withdraw the caller's own rating on a message in a thread. As with RateMessage, the rater is derived server-side from the verified request headers; there is deliberately no "whose rating" parameter. **conversationKey** `string` **required** Identifier of the conversation thread. Minimum length: 1 **messageSequence** `string(int64)` **required** Message whose rating to withdraw (by sequence number) Pattern: ^-?\d+$ #### conversations-deleteMessageRating-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "conversationKey": "example_123", "messageSequence": "1" } ``` #### cookbook-insights-evaluation-message-feedback-02-request Guide request for Let the user remove their judgment. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "support-chat-001", "messageSequence": 8 } ``` ## Responses ### 200 — Rating withdrawn (or confirmed absent) Content type: `application/json` Result of withdrawing the caller’s rating on a conversation message. **ratedMessage** `any` The message with the caller's entry removed from the feedback list All of: Variant 1: Chat message At least one of content or tool\_calls must contain an entry; both lists may be nonempty. role must select a listed message role. Requiredness and allowed values are declared separately. Model reference: [Message](/api/models/schema-1j3dcf7kvu#response). **role** `any` Role of the participant that produced the chat message. Participant role attached to a conversation message and forwarded in model context.
| Value | No. | Form | Meaning | |---|---|---|---| | `ROLE_SYSTEM` | 0 | Canonical | Instructions or context provided as a system message. | | `ROLE_USER` | 1 | Canonical | Input supplied by the user or customer application. | | `ROLE_ASSISTANT` | 2 | Canonical | Content produced by the assistant, including its tool-call requests. | | `ROLE_TOOL` | 3 | Canonical | A tool result supplied back to the assistant. |
Exactly one of: Variant 1: Type: `string` Enum: `ROLE_SYSTEM`, `ROLE_USER`, `ROLE_ASSISTANT`, `ROLE_TOOL` Variant 2: Type: `integer(int32)` **content** `array[llm_v1_common_v1_ContentPart]` Content parts composing the chat message. Content parts composing a message, using a flattened structure for JSON compatibility. The `type` identifies how the content is represented; only defined content types are accepted. Model reference: [ContentPart](/api/models/schema-1hqi9r2bhh#response). **type** `any` Kind of content carried by this message part. Discriminator identifying which content representation a message part carries.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTENT_PART_TYPE_TEXT` | 0 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_URL` | 1 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_BASE64` | 2 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_ID` | 3 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_PATH` | 4 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_URL` | 5 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_DATA_URL` | 6 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_AUDIO_BASE64` | 7 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_REASONING` | 8 | Canonical | See meaning below. | **`CONTENT_PART_TYPE_TEXT`** Plain text carried by the content part. Plain text content **`CONTENT_PART_TYPE_IMAGE_URL`** An image supplied through a remote URL. Remote image URL **`CONTENT_PART_TYPE_IMAGE_BASE64`** An image supplied as base64-encoded bytes. Base64-encoded image data **`CONTENT_PART_TYPE_FILE_ID`** A provider file identifier or internal storage identifier resolved before generation. File ID — a provider file ID (e.g., OpenAI) OR an internal storage file ID; resolved to a signed FILE\_URL just-in-time before the model-provider request **`CONTENT_PART_TYPE_FILE_PATH`** A reference to a local file path. Local file path reference **`CONTENT_PART_TYPE_FILE_URL`** A file supplied through a public or signed URL. Public or signed file URL (e.g., PDF URL or data: URL) **`CONTENT_PART_TYPE_FILE_DATA_URL`** A file embedded in a data URL, including its media type and encoded data. data\:application/pdf;base64,... or similar **`CONTENT_PART_TYPE_AUDIO_BASE64`** Base64-encoded audio; the part metadata identifies its audio format. Base64-encoded audio (metadata.format required, e.g., wav/mp3) **`CONTENT_PART_TYPE_REASONING`** A reasoning segment returned by a model provider, when available. Reasoning/thinking content from chain-of-thought models
Exactly one of: Variant 1: Type: `string` Enum: `CONTENT_PART_TYPE_TEXT`, `CONTENT_PART_TYPE_IMAGE_URL`, `CONTENT_PART_TYPE_IMAGE_BASE64`, `CONTENT_PART_TYPE_FILE_ID`, `CONTENT_PART_TYPE_FILE_PATH`, `CONTENT_PART_TYPE_FILE_URL`, `CONTENT_PART_TYPE_FILE_DATA_URL`, `CONTENT_PART_TYPE_AUDIO_BASE64`, `CONTENT_PART_TYPE_REASONING` Variant 2: Type: `integer(int32)` **content** `string` Text content, image URL, file ID, or base64-encoded data. **metadata** `map[string, string]` Additional type-specific metadata (dimensions, mime\_type, etc.). **cachePreferred** `boolean` Hint that this part is eligible for provider prompt caching. **structuredMessage** `any` Populated on TEXT parts for structured output responses. All of: Variant 1: A structured message whose JSON payload has been validated against a declared schema. Consumers can trust that json\_payload conforms to the schema identified by schema\_name. Inspect the run outcome before treating any message as complete. Current structured metadata is attached to a text content part through [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage) can be absent. Use an object at the schema root and validate the exact final response your application consumes; server validation covers only the first model choice. For integers that your JSON client cannot represent exactly, define string-valued fields in your schema instead of converting them through floating point. Model reference: [StructuredMessage](/api/models/schema-1ho1lk4ndj#response). **jsonPayload** `map[string, any]` The validated JSON payload as a Struct (preserves types) **schemaName** `string` Schema identifier (from ResponseFormat.schema\_name) **healed** `boolean` Whether response healing is reported for this structured message. Currently returned as false. **toolCalls** `array[llm_v1_common_v1_ToolCall]` Assistant-to-tool invocations. A single structured tool call emitted by the model [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat) is the client answer window. Expiry ends that wait and rejects late results; the timeout policy determines the outcome. Model reference: [ToolCall](/api/models/schema-1it6mqsqoo#response). **id** `string` Provider-supplied call id. **name** `string` Name of the tool or function being invoked. **argumentsJson** `map[string, any]` JSON object payload. **status** `any` Execution status recorded for the tool call. Execution state of a tool call, including approval waiting and terminal outcomes. The terminal outcomes are COMPLETED, FAILED, CANCELLED and TIMED\_OUT; inspect ToolCall.end\_reason for why a call ended rather than treating the reason as another status. Use a listed execution status. The end reason explains the outcome separately from the status.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_EXECUTION_STATUS_PENDING` | 0 | Canonical | The tool call is waiting to begin execution. | | `TOOL_EXECUTION_STATUS_EXECUTING` | 1 | Canonical | The tool call is currently executing. | | `TOOL_EXECUTION_STATUS_COMPLETED` | 2 | Canonical | The tool call completed successfully. This is a terminal outcome. | | `TOOL_EXECUTION_STATUS_FAILED` | 3 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. | | `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 4 | Canonical | The tool call is waiting for approval before it can execute. | | `TOOL_EXECUTION_STATUS_CANCELLED` | 5 | Canonical | The tool call was cancelled before normal completion. | | `TOOL_EXECUTION_STATUS_TIMED_OUT` | 6 | Canonical | Tool execution ended because its time limit elapsed. |
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_EXECUTION_STATUS_PENDING`, `TOOL_EXECUTION_STATUS_EXECUTING`, `TOOL_EXECUTION_STATUS_COMPLETED`, `TOOL_EXECUTION_STATUS_FAILED`, `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, `TOOL_EXECUTION_STATUS_CANCELLED`, `TOOL_EXECUTION_STATUS_TIMED_OUT` Variant 2: Type: `integer(int32)` **resultJson** `map[string, any]` Tool execution result (object). **executedAt** `string(date-time)` Time when the tool execution was recorded. **serverId** `string` Which server provides this tool (for MCP tools). **isClientTool** `boolean` True if this is a client-side tool handled by client. **description** `string` Tool description captured from the resolved tool definition when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. **parametersJsonSchema** `map[string, any]` JSON Schema describing the tool’s input arguments. **requiresApprovalAt** `string(date-time)` Deadline for an approval decision, calculated from the effective approval timeout. This is not the time the call began waiting. An approval received after the deadline is rejected. **approvedAt** `string(date-time)` Timestamp when approval decision was recorded (if approved/rejected) **approvedBy** `string` Identifier of the approver (user id, email, or actor key) **executionDuration** `string` End-to-end execution duration once terminal (includes tool server latency or client-side time) Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **endReason** `string` Why this call ended, in one short phrase — "approval rejected", "approval timeout", or the underlying error. Set only once `status` is terminal, and empty on a clean COMPLETED. Use this reason to distinguish a rejection from a failure without parsing the tool result. **clientToolDeadlineAt** `string(date-time)` Deadline by which the client must submit a result for this call, stamped when the call is dispatched to a caller. **name** `string` Name identifying the sender of the chat message. optional sender name **timestamp** `string(date-time)` Timestamp associated with the conversation message or event. **messageId** `string` Unique message identifier. **annotations** `array[llm_v1_common_v1_Annotation]` Structured annotations (e.g., standardized web search URL citations, PDF reuse tokens) Tagged provider annotation attached to generated content, such as a citation or PDF reference. Model reference: [Annotation](/api/models/schema-1i0hjer0pd#response). **kind** `any` Selected kind; determines which submessage is populated Kind of source annotation associated with generated content.
| Value | No. | Form | Meaning | |---|---|---|---| | `ANNOTATION_KIND_URL_CITATION` | 0 | Canonical | A citation to a source identified by its URL. | | `ANNOTATION_KIND_PDF` | 1 | Canonical | An annotation identifying source content in a PDF document. |
Exactly one of: Variant 1: Type: `string` Enum: `ANNOTATION_KIND_URL_CITATION`, `ANNOTATION_KIND_PDF` Variant 2: Type: `integer(int32)` **urlCitation** `any` Submessage fields (optional); populate the one matching kind All of: Variant 1: Web source and character range cited in generated message content. Model reference: [UrlCitation](/api/models/schema-1hujls61ng#response). **url** `string` URL of the cited web page. **title** `string` Title of the web page cited by this annotation. **content** `string` Optional excerpt or snippet of the cited web page. **startIndex** `string(int64)` Character index in message content. Pattern: ^-?\d+$ **endIndex** `string(int64)` Character index in message content. Pattern: ^-?\d+$ **pdf** `any` PDF annotation identifying the parsed file and available parsing output. All of: Variant 1: Provider annotation identifying a parsed PDF and reusable parsing output. Model reference: [PdfAnnotation](/api/models/schema-1hsi58i6pb#response). **filename** `string` Optional identifying information about the original file **engine** `string` PDF parsing engine used by provider (e.g., "pdf-text", "mistral-ocr", "native") **token** `string` Opaque provider token or handle allowing reuse without re-parsing **sourceUrl** `string` Optional: original source reference (public URL or data: URL) **hash** `string` Provider-supplied hash identifying the parsed file. **content** `array[llm_v1_common_v1_ContentPart]` Optional structured content returned by provider annotations (text, image URLs, etc.) Note: This can be large; include only if you need to round-trip provider annotations. Content parts composing a message, using a flattened structure for JSON compatibility. The `type` identifies how the content is represented; only defined content types are accepted. Model reference: [ContentPart](/api/models/schema-1hqi9r2bhh#response). **type** `any` Kind of content carried by this message part. Discriminator identifying which content representation a message part carries.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTENT_PART_TYPE_TEXT` | 0 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_URL` | 1 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_BASE64` | 2 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_ID` | 3 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_PATH` | 4 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_URL` | 5 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_DATA_URL` | 6 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_AUDIO_BASE64` | 7 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_REASONING` | 8 | Canonical | See meaning below. | **`CONTENT_PART_TYPE_TEXT`** Plain text carried by the content part. Plain text content **`CONTENT_PART_TYPE_IMAGE_URL`** An image supplied through a remote URL. Remote image URL **`CONTENT_PART_TYPE_IMAGE_BASE64`** An image supplied as base64-encoded bytes. Base64-encoded image data **`CONTENT_PART_TYPE_FILE_ID`** A provider file identifier or internal storage identifier resolved before generation. File ID — a provider file ID (e.g., OpenAI) OR an internal storage file ID; resolved to a signed FILE\_URL just-in-time before the model-provider request **`CONTENT_PART_TYPE_FILE_PATH`** A reference to a local file path. Local file path reference **`CONTENT_PART_TYPE_FILE_URL`** A file supplied through a public or signed URL. Public or signed file URL (e.g., PDF URL or data: URL) **`CONTENT_PART_TYPE_FILE_DATA_URL`** A file embedded in a data URL, including its media type and encoded data. data\:application/pdf;base64,... or similar **`CONTENT_PART_TYPE_AUDIO_BASE64`** Base64-encoded audio; the part metadata identifies its audio format. Base64-encoded audio (metadata.format required, e.g., wav/mp3) **`CONTENT_PART_TYPE_REASONING`** A reasoning segment returned by a model provider, when available. Reasoning/thinking content from chain-of-thought models
Exactly one of: Variant 1: Type: `string` Enum: `CONTENT_PART_TYPE_TEXT`, `CONTENT_PART_TYPE_IMAGE_URL`, `CONTENT_PART_TYPE_IMAGE_BASE64`, `CONTENT_PART_TYPE_FILE_ID`, `CONTENT_PART_TYPE_FILE_PATH`, `CONTENT_PART_TYPE_FILE_URL`, `CONTENT_PART_TYPE_FILE_DATA_URL`, `CONTENT_PART_TYPE_AUDIO_BASE64`, `CONTENT_PART_TYPE_REASONING` Variant 2: Type: `integer(int32)` **content** `string` Text content, image URL, file ID, or base64-encoded data. **metadata** `map[string, string]` Additional type-specific metadata (dimensions, mime\_type, etc.). **cachePreferred** `boolean` Hint that this part is eligible for provider prompt caching. **structuredMessage** `any` Populated on TEXT parts for structured output responses. All of: Variant 1: A structured message whose JSON payload has been validated against a declared schema. Consumers can trust that json\_payload conforms to the schema identified by schema\_name. Inspect the run outcome before treating any message as complete. Current structured metadata is attached to a text content part through [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage) can be absent. Use an object at the schema root and validate the exact final response your application consumes; server validation covers only the first model choice. For integers that your JSON client cannot represent exactly, define string-valued fields in your schema instead of converting them through floating point. Model reference: [StructuredMessage](/api/models/schema-1ho1lk4ndj#response). **jsonPayload** `map[string, any]` The validated JSON payload as a Struct (preserves types) **schemaName** `string` Schema identifier (from ResponseFormat.schema\_name) **healed** `boolean` Whether response healing is reported for this structured message. Currently returned as false. **metadata** `map[string, string]` Provider-specific extras. **sequence** `string(int64)` Monotonic, per-conversation sequence number for stable ordering (1-based) Pattern: ^-?\d+$ **generatedBy** `string` Workflow run id or generator key that produced this message (e.g., workflow run key) **usage** `any` Token usage for this generation (populated for assistant messages) All of: Variant 1: Usage accounting Model reference: [Usage](/api/models/schema-1j1vov2uoh#response). **promptTokens** `string(int64)` Prompt-token usage reported by the model provider. Pattern: ^-?\d+$ **completionTokens** `string(int64)` Completion-token usage reported by the model provider. Pattern: ^-?\d+$ **totalTokens** `string(int64)` Total token usage reported by the model provider. Pattern: ^-?\d+$ **costEstimate** `any` Estimated cost in USD. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completionTokensDetails** `any` Breakdown of completion tokens. All of: Variant 1: Breakdown of completion-token usage. Categories are measured by different upstream tokenizers and need not sum to completion\_tokens; reasoning\_tokens can exceed completion\_tokens. One category must not be derived by subtracting the others. Model reference: [CompletionTokensDetails](/api/models/schema-1i6q4qpg72#response). **reasoningTokens** `string(int64)` Tokens used for reasoning/thinking. Pattern: ^-?\d+$ **imageTokens** `string(int64)` Completion tokens emitted as image output. Pattern: ^-?\d+$ **audioTokens** `string(int64)` Completion tokens emitted as audio output. Pattern: ^-?\d+$ **promptTokensDetails** `any` Breakdown of prompt tokens (cache). All of: Variant 1: Breakdown of prompt token usage by category (input-side cache accounting) Subset semantics: cached\_tokens and cache\_write\_tokens are a breakdown *of* prompt\_tokens, so cached\_tokens + cache\_write\_tokens \<= Usage.prompt\_tokens. Ordinary (full-rate) prompt tokens = prompt\_tokens - cached\_tokens - cache\_write\_tokens. audio\_tokens / video\_tokens are modality breakdowns of prompt\_tokens (also a subset). Model reference: [PromptTokensDetails](/api/models/schema-1ivj82m55o#response). **cachedTokens** `string(int64)` Prompt tokens served from cache (cache READ). Pattern: ^-?\d+$ **cacheWriteTokens** `string(int64)` Prompt tokens written to cache this call (cache WRITE). Pattern: ^-?\d+$ **audioTokens** `string(int64)` Prompt tokens from audio input (multimodal). Pattern: ^-?\d+$ **videoTokens** `string(int64)` Prompt tokens from video input (multimodal). Pattern: ^-?\d+$ **costDetails** `any` Breakdown of upstream provider cost (BYOK routes). All of: Variant 1: Breakdown of model-provider cost. When the customer supplies the provider key, usage.cost is zero and upstream\_inference\_cost reports the provider spend, split into prompt and completion components. Model reference: [CostDetails](/api/models/schema-1ia0h761lm#response). **upstreamInferenceCost** `any` Total upstream provider cost (USD) on BYOK routes. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferencePromptCost** `any` Upstream cost attributed to prompt tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferenceCompletionCost** `any` Upstream cost attributed to completion tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **isByok** `boolean` Whether this generation used the customer's own model-provider key. **model** `string` Model that generated this message (e.g., "anthropic/claude-sonnet-4") **generationContext** `any` Dynamic context that shaped this generation (memories, search params, turn info) All of: Variant 1: Snapshot of retrieval inputs, prompt provenance, and turn position that shaped a generated message. Model reference: [GenerationContext](/api/models/schema-1im79fphmq#response). **memories** `array[llm_v1_common_v1_MemoryReference]` Memory records captured in the generation context. A memory record retrieved and included in generation context. Model reference: [MemoryReference](/api/models/schema-1ie9a4bgk5#response). **memoryId** `string` Identifier of the retrieved memory record. **score** `any` Relevance score reported by the memory provider for this match. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **memoryText** `string` Text of the retrieved memory record. **createdAt** `string(date-time)` Time when this record was created. **updatedAt** `string(date-time)` Time when this record was last updated. **relations** `array[llm_v1_common_v1_RelationReference]` Graph relationships captured in the generation context. A graph relationship retrieved and included in generation context. Model reference: [RelationReference](/api/models/schema-1ijit8ceuv#response). **source** `string` Source entity of the memory graph relationship. **relationship** `string` Relationship label connecting the source and destination entities. **destination** `string` Destination entity of the memory graph relationship. **memorySearch** `any` Memory-query parameters and counts recorded for this generation. All of: Variant 1: Parameters used to retrieve relevant memories during generation. Model reference: [MemorySearchParams](/api/models/schema-1igd5iut01#response). **query** `string` Text submitted to memory retrieval for this generation. **topK** `string(int64)` Maximum memory matches requested during generation-context retrieval. Pattern: ^-?\d+$ **threshold** `any` Minimum relevance threshold requested for the memory query. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **rerank** `boolean` Whether reranking was requested for the memory search. **resultsReturned** `string(int64)` Number of memory records returned by the search. Pattern: ^-?\d+$ **relationsReturned** `string(int64)` Number of graph relationships returned by the search. Pattern: ^-?\d+$ **turn** `any` Turn position and limit within the generation run. All of: Variant 1: Turn position within an agentic generation run Model reference: [TurnInfo](/api/models/schema-1ilcikuhu8#response). **currentTurn** `string(int64)` Current turn position within the generation run. Pattern: ^-?\d+$ **maxTurns** `string(int64)` Maximum turns configured for the generation run. Pattern: ^-?\d+$ **languagePreference** `string` Language preference associated with the generation context. **resolvedSystemPrompt** `string` System prompt selected for this generation after prompt precedence is resolved. This field is retained in the schema but is not populated; use resolved\_prompt\_hash for recorded prompt identity. **profileId** `string` Agent profile that produced this message ("" if none active). **model** `string` Model actually used for this generation. **promptSource** `any` Which precedence tier supplied the prompt. Source that supplied the effective system prompt for a generation turn. Distinguishes a client override, a profile template and the conversation default configuration for prompt attribution.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROMPT_SOURCE_CLIENT_OVERRIDE` | 0 | Canonical | See meaning below. | | `PROMPT_SOURCE_PROFILE_TEMPLATE` | 1 | Canonical | See meaning below. | | `PROMPT_SOURCE_DEFAULT_CONFIG` | 2 | Canonical | See meaning below. | **`PROMPT_SOURCE_CLIENT_OVERRIDE`** The caller supplied the prompt through the send request's generation-configuration override. SendRequest.override\_generation\_config **`PROMPT_SOURCE_PROFILE_TEMPLATE`** The prompt was rendered from the active agent profile template. active agent profile's rendered template **`PROMPT_SOURCE_DEFAULT_CONFIG`** The prompt came from the conversation or project default generation configuration. conversation/project default\_generation\_config
Exactly one of: Variant 1: Type: `string` Enum: `PROMPT_SOURCE_CLIENT_OVERRIDE`, `PROMPT_SOURCE_PROFILE_TEMPLATE`, `PROMPT_SOURCE_DEFAULT_CONFIG` Variant 2: Type: `integer(int32)` **baseConfig** `any` Generation configuration resolved at send time before per-call overrides and timeout adjustments, with system\_prompt omitted. The active profile supplies the base when selected; otherwise the conversation default does. Use prompt\_source and profile\_id for prompt attribution. The base configuration can be absent when neither source supplies one or no snapshot was captured. For a supplied per-call override, the populated top-level fields of override\_config overlay base\_config to form the effective configuration. override\_config can be absent when no override was supplied. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#response). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#response). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#response). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#response). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#response). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#response). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#response). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinition]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#response). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfig]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#response). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#response). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#response). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#response). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#response). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#response). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#response). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#response). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **overrideConfig** `any` Per-call generation configuration supplied before the override merge. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#response). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#response). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#response). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#response). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#response). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#response). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#response). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinition]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#response). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfig]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#response). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#response). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#response). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#response). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#response). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#response). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#response). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#response). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **profileVersion** `string(int64)` Immutable version of the active agent profile used to render this turn’s prompt. Absent on older turns and turns without a profile template. Pattern: ^-?\d+$ **fragmentsVersion** `string(int64)` Version of the prompt-fragment set used to render the profile prompt. Pattern: ^-?\d+$ **promptVariables** `map[string, any]` Values bound to the prompt template for this generation. **profileRenderFailed** `boolean` Whether rendering the profile prompt failed for this generation. **resolvedPromptHash** `string` SHA-256 hash, as 64 hexadecimal characters, of the resolved system prompt before the current-time instruction is appended. Identifies prompt content only, excluding model and sampling parameters. Absent on older turns without prompt capture. **resolvedUserContext** `string` The literal user-context text supplied to the model for this turn, including the available name, locale and location conditions. It is a captured prompt input, not a reconstruction from the user’s current profile. The value is computed once per turn and reused across its model calls. It can be empty when location context is unavailable, enrichment fails or the turn predates capture. **resolvedMcpServers** `array[llm_v1_common_v1_MCPServerReference]` The MCP server list used for this turn after resolving conversation settings, the active profile, and any per-turn `override_mcp_servers`. It determines both tool discovery and the allow/block rules applied by `CallTool`. A per-turn override does not change the conversation's stored MCP settings. Compare this snapshot with `settings.mcp_servers` to inspect how the turn's tool set differed. Empty on turns predating capture and on threads with no MCP servers. MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#response). **serverId** `string` ID of pre-configured MCP server (e.g., "github", "filesystem"). **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **clientContext** `any` Arbitrary client-supplied context attached by the client for this message All of: Variant 1: Opaque caller-supplied attributes attached to a conversation message. Values are strings, including values such as `"false"`. The schema allows at most 32 pairs, keys of at most 64 characters, and values of at most 1,024 characters. Keep the entire map well below 8 KiB: Travila also applies an encoded-size limit that includes field overhead and drops context that exceeds it. Short page identifiers and a few relevant values are preferable to a page dump; an oversized map is not automatically shortened. Model reference: [ClientContext](/api/models/schema-1i2sndrl93#response). **values** `map[string, string]` Arbitrary client-supplied context for this message (e.g. page, referrer, device, in-app flow). Keys/values are opaque strings. **feedback** `array[llm_v1_common_v1_MessageFeedback]` Feedback on an assistant message, with one entry per rater identified by rated\_by. A later rating by the same rater replaces their earlier entry. One user's feedback on an assistant-generated message. kind must select a listed feedback representation. Requiredness and allowed values are declared separately. Model reference: [MessageFeedback](/api/models/schema-1iroqctqt1#response). **kind** `any` Rating representation used to interpret the feedback value. Value scale used to interpret recorded feedback.
| Value | No. | Form | Meaning | |---|---|---|---| | `FEEDBACK_KIND_THUMB` | 0 | Canonical | See meaning below. | | `FEEDBACK_KIND_SCALE` | 1 | Canonical | See meaning below. | **`FEEDBACK_KIND_THUMB`** Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. binary thumbs up / down **`FEEDBACK_KIND_SCALE`** Feedback expressed as an integer rating from 1 through 10. 1-10 integer scale
Exactly one of: Variant 1: Type: `string` Enum: `FEEDBACK_KIND_THUMB`, `FEEDBACK_KIND_SCALE` Variant 2: Type: `integer(int32)` **thumbUp** `boolean` Positive when true and negative when false; used for THUMB feedback. **rating** `string(int64)` Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent. Pattern: ^-?\d+$ **reason** `string` Optional explanation for the rating. **ratedAt** `string(date-time)` Timestamp when feedback was submitted (server-set) **ratedBy** `string` Identifier of the user who submitted this feedback. Set by the server from the authenticated user identity; never client-supplied. Each user has one feedback entry per message. **sourceUserMessageId** `string` Identifier of the user message that opened this conversation turn. Generated messages in the same turn share this value; a user message carries its own message\_id. Empty on historical messages that predate turn attribution. Use this field for turn attribution rather than inferring it from message adjacency or a client-supplied message\_id. The generated\_by identifier groups messages by generation run but does not identify the user message that opened the turn. **finishReason** `string` Why the model stopped, verbatim from the provider: "stop", "tool\_calls", "length", "error". Empty for historical messages. **removed** `boolean` False when the caller had no rating on this message — an idempotent success, not an error. #### conversations-deleteMessageRating-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "ratedMessage": { "role": "ROLE_SYSTEM", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Example text", "cachePreferred": true } ], "toolCalls": [ { "id": "example_123", "name": "example", "status": "TOOL_EXECUTION_STATUS_PENDING", "serverId": "example_123", "isClientTool": true, "description": "example", "approvedBy": "example", "endReason": "example" } ], "name": "example", "timestamp": "2026-09-16T12:00:00Z", "messageId": "example_123", "annotations": [ { "kind": "ANNOTATION_KIND_URL_CITATION" } ], "sequence": "1", "generatedBy": "example", "usage": { "promptTokens": 1, "completionTokens": 1, "totalTokens": 1, "costEstimate": 1, "isByok": true }, "model": "example", "generationContext": { "languagePreference": "en-US", "resolvedSystemPrompt": "Example text", "profileId": "example_123", "model": "example", "promptSource": "PROMPT_SOURCE_CLIENT_OVERRIDE", "profileVersion": 1, "fragmentsVersion": 1, "profileRenderFailed": true, "resolvedPromptHash": "Example text", "resolvedUserContext": "Example text" }, "clientContext": {}, "feedback": [ { "kind": "FEEDBACK_KIND_THUMB", "thumbUp": true, "reason": "example", "ratedBy": "example" } ], "sourceUserMessageId": "example_123", "finishReason": "example" }, "removed": true } ``` #### cookbook-insights-evaluation-message-feedback-json-03-response Illustrative response for Let the user remove their judgment. Replace example resource identifiers with your own authorized values. ```json { "ratedMessage": { "role": "ROLE_ASSISTANT", "sequence": "8", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "…" } ] }, "removed": true } ``` Document ID: `DOC-MA-conversations-api-deleteMessageRating`. [Section identities and revisions](/documentation-manifest.json). - Withdraw your rating on a message: `DOC-MA-conversations-api-deleteMessageRating#overview` - Request: `DOC-MA-conversations-api-deleteMessageRating#request` - Responses: `DOC-MA-conversations-api-deleteMessageRating#responses` --- # Get full conversation state URL: https://docs.travila.ai/api/conversations/get-conversation-state **POST** `/api/v1/llm/conversation-state` Returns the complete conversation state. An unknown or non-owned `externalId` returns `404`. When polling, the absence of an active run does not prove that an accepted or queued request completed. Reconcile the original `runId` and its outcome before retrying an accepted send. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build a support conversation the user can return to](/managed-agents/conversations) · [Build an assistant that researches the web](/integrations/tools-connections) · [Build a signed-in support chat that survives reconnects](/managed-agents/conversations/build-chat-assistant) · [Resume a long conversation with a compacted history](/managed-agents/conversations/context-management) · [Get a customer’s reply and recover an interrupted send](/managed-agents/conversations/generation) · [Complete your first support-chat turn](/managed-agents/conversations/quickstart) · [Show one correct chat history as updates arrive](/managed-agents/conversations/streaming/payloads) · [Restore a chat after the connection drops](/managed-agents/conversations/streaming/subscribing) · [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps) · [Messages and runs](/api/conversations/messages-and-runs) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for reading conversation history and current generation state. Supply exactly one of conversation\_key or external\_id; either addresses the same stored conversation. **conversationKey** `string` Generated conversation thread ID. Leave empty when addressing by external\_id. **externalId** `string` Client-supplied conversation identifier from CreateThread, resolved within the caller’s ownership scope. Maximum length: 255 #### conversations-getConversationState-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "conversationKey": "example_123" } ``` #### cookbook-managed-agents-conversations-build-chat-assistant-04-request Guide request for Poll conversation state. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842" } ``` #### cookbook-managed-agents-conversations-context-management-03-request Guide request for Recipe: compact the older history, then continue the thread. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "support-chat-001" } ``` ## Responses ### 200 — Conversation state returned Content type: `application/json` Result of reading conversation history and current generation state. **messageHistory** `array[llm_v1_common_v1_Message]` Messages recorded in the conversation history. Chat message At least one of content or tool\_calls must contain an entry; both lists may be nonempty. role must select a listed message role. Requiredness and allowed values are declared separately. Model reference: [Message](/api/models/schema-1j3dcf7kvu#response). **role** `any` Role of the participant that produced the chat message. Participant role attached to a conversation message and forwarded in model context.
| Value | No. | Form | Meaning | |---|---|---|---| | `ROLE_SYSTEM` | 0 | Canonical | Instructions or context provided as a system message. | | `ROLE_USER` | 1 | Canonical | Input supplied by the user or customer application. | | `ROLE_ASSISTANT` | 2 | Canonical | Content produced by the assistant, including its tool-call requests. | | `ROLE_TOOL` | 3 | Canonical | A tool result supplied back to the assistant. |
Exactly one of: Variant 1: Type: `string` Enum: `ROLE_SYSTEM`, `ROLE_USER`, `ROLE_ASSISTANT`, `ROLE_TOOL` Variant 2: Type: `integer(int32)` **content** `array[llm_v1_common_v1_ContentPart]` Content parts composing the chat message. Content parts composing a message, using a flattened structure for JSON compatibility. The `type` identifies how the content is represented; only defined content types are accepted. Model reference: [ContentPart](/api/models/schema-1hqi9r2bhh#response). **type** `any` Kind of content carried by this message part. Discriminator identifying which content representation a message part carries.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTENT_PART_TYPE_TEXT` | 0 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_URL` | 1 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_BASE64` | 2 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_ID` | 3 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_PATH` | 4 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_URL` | 5 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_DATA_URL` | 6 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_AUDIO_BASE64` | 7 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_REASONING` | 8 | Canonical | See meaning below. | **`CONTENT_PART_TYPE_TEXT`** Plain text carried by the content part. Plain text content **`CONTENT_PART_TYPE_IMAGE_URL`** An image supplied through a remote URL. Remote image URL **`CONTENT_PART_TYPE_IMAGE_BASE64`** An image supplied as base64-encoded bytes. Base64-encoded image data **`CONTENT_PART_TYPE_FILE_ID`** A provider file identifier or internal storage identifier resolved before generation. File ID — a provider file ID (e.g., OpenAI) OR an internal storage file ID; resolved to a signed FILE\_URL just-in-time before the model-provider request **`CONTENT_PART_TYPE_FILE_PATH`** A reference to a local file path. Local file path reference **`CONTENT_PART_TYPE_FILE_URL`** A file supplied through a public or signed URL. Public or signed file URL (e.g., PDF URL or data: URL) **`CONTENT_PART_TYPE_FILE_DATA_URL`** A file embedded in a data URL, including its media type and encoded data. data\:application/pdf;base64,... or similar **`CONTENT_PART_TYPE_AUDIO_BASE64`** Base64-encoded audio; the part metadata identifies its audio format. Base64-encoded audio (metadata.format required, e.g., wav/mp3) **`CONTENT_PART_TYPE_REASONING`** A reasoning segment returned by a model provider, when available. Reasoning/thinking content from chain-of-thought models
Exactly one of: Variant 1: Type: `string` Enum: `CONTENT_PART_TYPE_TEXT`, `CONTENT_PART_TYPE_IMAGE_URL`, `CONTENT_PART_TYPE_IMAGE_BASE64`, `CONTENT_PART_TYPE_FILE_ID`, `CONTENT_PART_TYPE_FILE_PATH`, `CONTENT_PART_TYPE_FILE_URL`, `CONTENT_PART_TYPE_FILE_DATA_URL`, `CONTENT_PART_TYPE_AUDIO_BASE64`, `CONTENT_PART_TYPE_REASONING` Variant 2: Type: `integer(int32)` **content** `string` Text content, image URL, file ID, or base64-encoded data. **metadata** `map[string, string]` Additional type-specific metadata (dimensions, mime\_type, etc.). **cachePreferred** `boolean` Hint that this part is eligible for provider prompt caching. **structuredMessage** `any` Populated on TEXT parts for structured output responses. All of: Variant 1: A structured message whose JSON payload has been validated against a declared schema. Consumers can trust that json\_payload conforms to the schema identified by schema\_name. Inspect the run outcome before treating any message as complete. Current structured metadata is attached to a text content part through [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage) can be absent. Use an object at the schema root and validate the exact final response your application consumes; server validation covers only the first model choice. For integers that your JSON client cannot represent exactly, define string-valued fields in your schema instead of converting them through floating point. Model reference: [StructuredMessage](/api/models/schema-1ho1lk4ndj#response). **jsonPayload** `map[string, any]` The validated JSON payload as a Struct (preserves types) **schemaName** `string` Schema identifier (from ResponseFormat.schema\_name) **healed** `boolean` Whether response healing is reported for this structured message. Currently returned as false. **toolCalls** `array[llm_v1_common_v1_ToolCall]` Assistant-to-tool invocations. A single structured tool call emitted by the model [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat) is the client answer window. Expiry ends that wait and rejects late results; the timeout policy determines the outcome. Model reference: [ToolCall](/api/models/schema-1it6mqsqoo#response). **id** `string` Provider-supplied call id. **name** `string` Name of the tool or function being invoked. **argumentsJson** `map[string, any]` JSON object payload. **status** `any` Execution status recorded for the tool call. Execution state of a tool call, including approval waiting and terminal outcomes. The terminal outcomes are COMPLETED, FAILED, CANCELLED and TIMED\_OUT; inspect ToolCall.end\_reason for why a call ended rather than treating the reason as another status. Use a listed execution status. The end reason explains the outcome separately from the status.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_EXECUTION_STATUS_PENDING` | 0 | Canonical | The tool call is waiting to begin execution. | | `TOOL_EXECUTION_STATUS_EXECUTING` | 1 | Canonical | The tool call is currently executing. | | `TOOL_EXECUTION_STATUS_COMPLETED` | 2 | Canonical | The tool call completed successfully. This is a terminal outcome. | | `TOOL_EXECUTION_STATUS_FAILED` | 3 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. | | `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 4 | Canonical | The tool call is waiting for approval before it can execute. | | `TOOL_EXECUTION_STATUS_CANCELLED` | 5 | Canonical | The tool call was cancelled before normal completion. | | `TOOL_EXECUTION_STATUS_TIMED_OUT` | 6 | Canonical | Tool execution ended because its time limit elapsed. |
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_EXECUTION_STATUS_PENDING`, `TOOL_EXECUTION_STATUS_EXECUTING`, `TOOL_EXECUTION_STATUS_COMPLETED`, `TOOL_EXECUTION_STATUS_FAILED`, `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, `TOOL_EXECUTION_STATUS_CANCELLED`, `TOOL_EXECUTION_STATUS_TIMED_OUT` Variant 2: Type: `integer(int32)` **resultJson** `map[string, any]` Tool execution result (object). **executedAt** `string(date-time)` Time when the tool execution was recorded. **serverId** `string` Which server provides this tool (for MCP tools). **isClientTool** `boolean` True if this is a client-side tool handled by client. **description** `string` Tool description captured from the resolved tool definition when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. **parametersJsonSchema** `map[string, any]` JSON Schema describing the tool’s input arguments. **requiresApprovalAt** `string(date-time)` Deadline for an approval decision, calculated from the effective approval timeout. This is not the time the call began waiting. An approval received after the deadline is rejected. **approvedAt** `string(date-time)` Timestamp when approval decision was recorded (if approved/rejected) **approvedBy** `string` Identifier of the approver (user id, email, or actor key) **executionDuration** `string` End-to-end execution duration once terminal (includes tool server latency or client-side time) Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **endReason** `string` Why this call ended, in one short phrase — "approval rejected", "approval timeout", or the underlying error. Set only once `status` is terminal, and empty on a clean COMPLETED. Use this reason to distinguish a rejection from a failure without parsing the tool result. **clientToolDeadlineAt** `string(date-time)` Deadline by which the client must submit a result for this call, stamped when the call is dispatched to a caller. **name** `string` Name identifying the sender of the chat message. optional sender name **timestamp** `string(date-time)` Timestamp associated with the conversation message or event. **messageId** `string` Unique message identifier. **annotations** `array[llm_v1_common_v1_Annotation]` Structured annotations (e.g., standardized web search URL citations, PDF reuse tokens) Tagged provider annotation attached to generated content, such as a citation or PDF reference. Model reference: [Annotation](/api/models/schema-1i0hjer0pd#response). **kind** `any` Selected kind; determines which submessage is populated Kind of source annotation associated with generated content.
| Value | No. | Form | Meaning | |---|---|---|---| | `ANNOTATION_KIND_URL_CITATION` | 0 | Canonical | A citation to a source identified by its URL. | | `ANNOTATION_KIND_PDF` | 1 | Canonical | An annotation identifying source content in a PDF document. |
Exactly one of: Variant 1: Type: `string` Enum: `ANNOTATION_KIND_URL_CITATION`, `ANNOTATION_KIND_PDF` Variant 2: Type: `integer(int32)` **urlCitation** `any` Submessage fields (optional); populate the one matching kind All of: Variant 1: Web source and character range cited in generated message content. Model reference: [UrlCitation](/api/models/schema-1hujls61ng#response). **url** `string` URL of the cited web page. **title** `string` Title of the web page cited by this annotation. **content** `string` Optional excerpt or snippet of the cited web page. **startIndex** `string(int64)` Character index in message content. Pattern: ^-?\d+$ **endIndex** `string(int64)` Character index in message content. Pattern: ^-?\d+$ **pdf** `any` PDF annotation identifying the parsed file and available parsing output. All of: Variant 1: Provider annotation identifying a parsed PDF and reusable parsing output. Model reference: [PdfAnnotation](/api/models/schema-1hsi58i6pb#response). **filename** `string` Optional identifying information about the original file **engine** `string` PDF parsing engine used by provider (e.g., "pdf-text", "mistral-ocr", "native") **token** `string` Opaque provider token or handle allowing reuse without re-parsing **sourceUrl** `string` Optional: original source reference (public URL or data: URL) **hash** `string` Provider-supplied hash identifying the parsed file. **content** `array[llm_v1_common_v1_ContentPart]` Optional structured content returned by provider annotations (text, image URLs, etc.) Note: This can be large; include only if you need to round-trip provider annotations. Content parts composing a message, using a flattened structure for JSON compatibility. The `type` identifies how the content is represented; only defined content types are accepted. Model reference: [ContentPart](/api/models/schema-1hqi9r2bhh#response). **type** `any` Kind of content carried by this message part. Discriminator identifying which content representation a message part carries.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTENT_PART_TYPE_TEXT` | 0 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_URL` | 1 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_BASE64` | 2 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_ID` | 3 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_PATH` | 4 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_URL` | 5 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_DATA_URL` | 6 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_AUDIO_BASE64` | 7 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_REASONING` | 8 | Canonical | See meaning below. | **`CONTENT_PART_TYPE_TEXT`** Plain text carried by the content part. Plain text content **`CONTENT_PART_TYPE_IMAGE_URL`** An image supplied through a remote URL. Remote image URL **`CONTENT_PART_TYPE_IMAGE_BASE64`** An image supplied as base64-encoded bytes. Base64-encoded image data **`CONTENT_PART_TYPE_FILE_ID`** A provider file identifier or internal storage identifier resolved before generation. File ID — a provider file ID (e.g., OpenAI) OR an internal storage file ID; resolved to a signed FILE\_URL just-in-time before the model-provider request **`CONTENT_PART_TYPE_FILE_PATH`** A reference to a local file path. Local file path reference **`CONTENT_PART_TYPE_FILE_URL`** A file supplied through a public or signed URL. Public or signed file URL (e.g., PDF URL or data: URL) **`CONTENT_PART_TYPE_FILE_DATA_URL`** A file embedded in a data URL, including its media type and encoded data. data\:application/pdf;base64,... or similar **`CONTENT_PART_TYPE_AUDIO_BASE64`** Base64-encoded audio; the part metadata identifies its audio format. Base64-encoded audio (metadata.format required, e.g., wav/mp3) **`CONTENT_PART_TYPE_REASONING`** A reasoning segment returned by a model provider, when available. Reasoning/thinking content from chain-of-thought models
Exactly one of: Variant 1: Type: `string` Enum: `CONTENT_PART_TYPE_TEXT`, `CONTENT_PART_TYPE_IMAGE_URL`, `CONTENT_PART_TYPE_IMAGE_BASE64`, `CONTENT_PART_TYPE_FILE_ID`, `CONTENT_PART_TYPE_FILE_PATH`, `CONTENT_PART_TYPE_FILE_URL`, `CONTENT_PART_TYPE_FILE_DATA_URL`, `CONTENT_PART_TYPE_AUDIO_BASE64`, `CONTENT_PART_TYPE_REASONING` Variant 2: Type: `integer(int32)` **content** `string` Text content, image URL, file ID, or base64-encoded data. **metadata** `map[string, string]` Additional type-specific metadata (dimensions, mime\_type, etc.). **cachePreferred** `boolean` Hint that this part is eligible for provider prompt caching. **structuredMessage** `any` Populated on TEXT parts for structured output responses. All of: Variant 1: A structured message whose JSON payload has been validated against a declared schema. Consumers can trust that json\_payload conforms to the schema identified by schema\_name. Inspect the run outcome before treating any message as complete. Current structured metadata is attached to a text content part through [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage) can be absent. Use an object at the schema root and validate the exact final response your application consumes; server validation covers only the first model choice. For integers that your JSON client cannot represent exactly, define string-valued fields in your schema instead of converting them through floating point. Model reference: [StructuredMessage](/api/models/schema-1ho1lk4ndj#response). **jsonPayload** `map[string, any]` The validated JSON payload as a Struct (preserves types) **schemaName** `string` Schema identifier (from ResponseFormat.schema\_name) **healed** `boolean` Whether response healing is reported for this structured message. Currently returned as false. **metadata** `map[string, string]` Provider-specific extras. **sequence** `string(int64)` Monotonic, per-conversation sequence number for stable ordering (1-based) Pattern: ^-?\d+$ **generatedBy** `string` Workflow run id or generator key that produced this message (e.g., workflow run key) **usage** `any` Token usage for this generation (populated for assistant messages) All of: Variant 1: Usage accounting Model reference: [Usage](/api/models/schema-1j1vov2uoh#response). **promptTokens** `string(int64)` Prompt-token usage reported by the model provider. Pattern: ^-?\d+$ **completionTokens** `string(int64)` Completion-token usage reported by the model provider. Pattern: ^-?\d+$ **totalTokens** `string(int64)` Total token usage reported by the model provider. Pattern: ^-?\d+$ **costEstimate** `any` Estimated cost in USD. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completionTokensDetails** `any` Breakdown of completion tokens. All of: Variant 1: Breakdown of completion-token usage. Categories are measured by different upstream tokenizers and need not sum to completion\_tokens; reasoning\_tokens can exceed completion\_tokens. One category must not be derived by subtracting the others. Model reference: [CompletionTokensDetails](/api/models/schema-1i6q4qpg72#response). **reasoningTokens** `string(int64)` Tokens used for reasoning/thinking. Pattern: ^-?\d+$ **imageTokens** `string(int64)` Completion tokens emitted as image output. Pattern: ^-?\d+$ **audioTokens** `string(int64)` Completion tokens emitted as audio output. Pattern: ^-?\d+$ **promptTokensDetails** `any` Breakdown of prompt tokens (cache). All of: Variant 1: Breakdown of prompt token usage by category (input-side cache accounting) Subset semantics: cached\_tokens and cache\_write\_tokens are a breakdown *of* prompt\_tokens, so cached\_tokens + cache\_write\_tokens \<= Usage.prompt\_tokens. Ordinary (full-rate) prompt tokens = prompt\_tokens - cached\_tokens - cache\_write\_tokens. audio\_tokens / video\_tokens are modality breakdowns of prompt\_tokens (also a subset). Model reference: [PromptTokensDetails](/api/models/schema-1ivj82m55o#response). **cachedTokens** `string(int64)` Prompt tokens served from cache (cache READ). Pattern: ^-?\d+$ **cacheWriteTokens** `string(int64)` Prompt tokens written to cache this call (cache WRITE). Pattern: ^-?\d+$ **audioTokens** `string(int64)` Prompt tokens from audio input (multimodal). Pattern: ^-?\d+$ **videoTokens** `string(int64)` Prompt tokens from video input (multimodal). Pattern: ^-?\d+$ **costDetails** `any` Breakdown of upstream provider cost (BYOK routes). All of: Variant 1: Breakdown of model-provider cost. When the customer supplies the provider key, usage.cost is zero and upstream\_inference\_cost reports the provider spend, split into prompt and completion components. Model reference: [CostDetails](/api/models/schema-1ia0h761lm#response). **upstreamInferenceCost** `any` Total upstream provider cost (USD) on BYOK routes. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferencePromptCost** `any` Upstream cost attributed to prompt tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferenceCompletionCost** `any` Upstream cost attributed to completion tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **isByok** `boolean` Whether this generation used the customer's own model-provider key. **model** `string` Model that generated this message (e.g., "anthropic/claude-sonnet-4") **generationContext** `any` Dynamic context that shaped this generation (memories, search params, turn info) All of: Variant 1: Snapshot of retrieval inputs, prompt provenance, and turn position that shaped a generated message. Model reference: [GenerationContext](/api/models/schema-1im79fphmq#response). **memories** `array[llm_v1_common_v1_MemoryReference]` Memory records captured in the generation context. A memory record retrieved and included in generation context. Model reference: [MemoryReference](/api/models/schema-1ie9a4bgk5#response). **memoryId** `string` Identifier of the retrieved memory record. **score** `any` Relevance score reported by the memory provider for this match. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **memoryText** `string` Text of the retrieved memory record. **createdAt** `string(date-time)` Time when this record was created. **updatedAt** `string(date-time)` Time when this record was last updated. **relations** `array[llm_v1_common_v1_RelationReference]` Graph relationships captured in the generation context. A graph relationship retrieved and included in generation context. Model reference: [RelationReference](/api/models/schema-1ijit8ceuv#response). **source** `string` Source entity of the memory graph relationship. **relationship** `string` Relationship label connecting the source and destination entities. **destination** `string` Destination entity of the memory graph relationship. **memorySearch** `any` Memory-query parameters and counts recorded for this generation. All of: Variant 1: Parameters used to retrieve relevant memories during generation. Model reference: [MemorySearchParams](/api/models/schema-1igd5iut01#response). **query** `string` Text submitted to memory retrieval for this generation. **topK** `string(int64)` Maximum memory matches requested during generation-context retrieval. Pattern: ^-?\d+$ **threshold** `any` Minimum relevance threshold requested for the memory query. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **rerank** `boolean` Whether reranking was requested for the memory search. **resultsReturned** `string(int64)` Number of memory records returned by the search. Pattern: ^-?\d+$ **relationsReturned** `string(int64)` Number of graph relationships returned by the search. Pattern: ^-?\d+$ **turn** `any` Turn position and limit within the generation run. All of: Variant 1: Turn position within an agentic generation run Model reference: [TurnInfo](/api/models/schema-1ilcikuhu8#response). **currentTurn** `string(int64)` Current turn position within the generation run. Pattern: ^-?\d+$ **maxTurns** `string(int64)` Maximum turns configured for the generation run. Pattern: ^-?\d+$ **languagePreference** `string` Language preference associated with the generation context. **resolvedSystemPrompt** `string` System prompt selected for this generation after prompt precedence is resolved. This field is retained in the schema but is not populated; use resolved\_prompt\_hash for recorded prompt identity. **profileId** `string` Agent profile that produced this message ("" if none active). **model** `string` Model actually used for this generation. **promptSource** `any` Which precedence tier supplied the prompt. Source that supplied the effective system prompt for a generation turn. Distinguishes a client override, a profile template and the conversation default configuration for prompt attribution.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROMPT_SOURCE_CLIENT_OVERRIDE` | 0 | Canonical | See meaning below. | | `PROMPT_SOURCE_PROFILE_TEMPLATE` | 1 | Canonical | See meaning below. | | `PROMPT_SOURCE_DEFAULT_CONFIG` | 2 | Canonical | See meaning below. | **`PROMPT_SOURCE_CLIENT_OVERRIDE`** The caller supplied the prompt through the send request's generation-configuration override. SendRequest.override\_generation\_config **`PROMPT_SOURCE_PROFILE_TEMPLATE`** The prompt was rendered from the active agent profile template. active agent profile's rendered template **`PROMPT_SOURCE_DEFAULT_CONFIG`** The prompt came from the conversation or project default generation configuration. conversation/project default\_generation\_config
Exactly one of: Variant 1: Type: `string` Enum: `PROMPT_SOURCE_CLIENT_OVERRIDE`, `PROMPT_SOURCE_PROFILE_TEMPLATE`, `PROMPT_SOURCE_DEFAULT_CONFIG` Variant 2: Type: `integer(int32)` **baseConfig** `any` Generation configuration resolved at send time before per-call overrides and timeout adjustments, with system\_prompt omitted. The active profile supplies the base when selected; otherwise the conversation default does. Use prompt\_source and profile\_id for prompt attribution. The base configuration can be absent when neither source supplies one or no snapshot was captured. For a supplied per-call override, the populated top-level fields of override\_config overlay base\_config to form the effective configuration. override\_config can be absent when no override was supplied. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#response). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#response). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#response). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#response). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#response). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#response). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#response). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinition]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#response). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfig]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#response). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#response). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#response). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#response). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#response). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#response). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#response). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#response). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **overrideConfig** `any` Per-call generation configuration supplied before the override merge. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#response). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#response). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#response). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#response). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#response). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#response). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#response). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinition]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#response). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfig]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#response). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#response). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#response). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#response). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#response). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#response). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#response). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#response). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **profileVersion** `string(int64)` Immutable version of the active agent profile used to render this turn’s prompt. Absent on older turns and turns without a profile template. Pattern: ^-?\d+$ **fragmentsVersion** `string(int64)` Version of the prompt-fragment set used to render the profile prompt. Pattern: ^-?\d+$ **promptVariables** `map[string, any]` Values bound to the prompt template for this generation. **profileRenderFailed** `boolean` Whether rendering the profile prompt failed for this generation. **resolvedPromptHash** `string` SHA-256 hash, as 64 hexadecimal characters, of the resolved system prompt before the current-time instruction is appended. Identifies prompt content only, excluding model and sampling parameters. Absent on older turns without prompt capture. **resolvedUserContext** `string` The literal user-context text supplied to the model for this turn, including the available name, locale and location conditions. It is a captured prompt input, not a reconstruction from the user’s current profile. The value is computed once per turn and reused across its model calls. It can be empty when location context is unavailable, enrichment fails or the turn predates capture. **resolvedMcpServers** `array[llm_v1_common_v1_MCPServerReference]` The MCP server list used for this turn after resolving conversation settings, the active profile, and any per-turn `override_mcp_servers`. It determines both tool discovery and the allow/block rules applied by `CallTool`. A per-turn override does not change the conversation's stored MCP settings. Compare this snapshot with `settings.mcp_servers` to inspect how the turn's tool set differed. Empty on turns predating capture and on threads with no MCP servers. MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#response). **serverId** `string` ID of pre-configured MCP server (e.g., "github", "filesystem"). **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **clientContext** `any` Arbitrary client-supplied context attached by the client for this message All of: Variant 1: Opaque caller-supplied attributes attached to a conversation message. Values are strings, including values such as `"false"`. The schema allows at most 32 pairs, keys of at most 64 characters, and values of at most 1,024 characters. Keep the entire map well below 8 KiB: Travila also applies an encoded-size limit that includes field overhead and drops context that exceeds it. Short page identifiers and a few relevant values are preferable to a page dump; an oversized map is not automatically shortened. Model reference: [ClientContext](/api/models/schema-1i2sndrl93#response). **values** `map[string, string]` Arbitrary client-supplied context for this message (e.g. page, referrer, device, in-app flow). Keys/values are opaque strings. **feedback** `array[llm_v1_common_v1_MessageFeedback]` Feedback on an assistant message, with one entry per rater identified by rated\_by. A later rating by the same rater replaces their earlier entry. One user's feedback on an assistant-generated message. kind must select a listed feedback representation. Requiredness and allowed values are declared separately. Model reference: [MessageFeedback](/api/models/schema-1iroqctqt1#response). **kind** `any` Rating representation used to interpret the feedback value. Value scale used to interpret recorded feedback.
| Value | No. | Form | Meaning | |---|---|---|---| | `FEEDBACK_KIND_THUMB` | 0 | Canonical | See meaning below. | | `FEEDBACK_KIND_SCALE` | 1 | Canonical | See meaning below. | **`FEEDBACK_KIND_THUMB`** Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. binary thumbs up / down **`FEEDBACK_KIND_SCALE`** Feedback expressed as an integer rating from 1 through 10. 1-10 integer scale
Exactly one of: Variant 1: Type: `string` Enum: `FEEDBACK_KIND_THUMB`, `FEEDBACK_KIND_SCALE` Variant 2: Type: `integer(int32)` **thumbUp** `boolean` Positive when true and negative when false; used for THUMB feedback. **rating** `string(int64)` Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent. Pattern: ^-?\d+$ **reason** `string` Optional explanation for the rating. **ratedAt** `string(date-time)` Timestamp when feedback was submitted (server-set) **ratedBy** `string` Identifier of the user who submitted this feedback. Set by the server from the authenticated user identity; never client-supplied. Each user has one feedback entry per message. **sourceUserMessageId** `string` Identifier of the user message that opened this conversation turn. Generated messages in the same turn share this value; a user message carries its own message\_id. Empty on historical messages that predate turn attribution. Use this field for turn attribution rather than inferring it from message adjacency or a client-supplied message\_id. The generated\_by identifier groups messages by generation run but does not identify the user message that opened the turn. **finishReason** `string` Why the model stopped, verbatim from the provider: "stop", "tool\_calls", "length", "error". Empty for historical messages. **defaultGenerationConfig** `any` Base model and tool configuration for turns in this conversation. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#response). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#response). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#response). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#response). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#response). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#response). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#response). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinition]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#response). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfig]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#response). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#response). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#response). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#response). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#response). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#response). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#response). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#response). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **settings** `any` Conversation settings returned or supplied for this operation. All of: Variant 1: Conversation-level settings controlling behavior across sends [`maxLoops`](/api/models/schema-ph6avse89k#request-field-maxloops) caps the **total number of generations** in a run — not the number of tool round trips. Default is **2**, which is what one round trip costs: a first generation to emit the tool call, a second to synthesize its result. On the final generation the model is sent **no tools at all** (the request omits the [`tools`](/api/models/schema-1h82h7ri5p#request-field-tools) array), so it cannot emit a call there. `maxLoops: 1` therefore means a single tool-free reply — a valid way to ask for one, but not a way to get one tool round trip. Model reference: [ConversationSettings](/api/models/schema-ph6avse89k#response). **interruptPolicy** `any` Policy for an incoming message while another generation run is active. How a conversation handles a new send while another generation run is active.
| Value | No. | Form | Meaning | |---|---|---|---| | `INTERRUPT_POLICY_REJECT_NEW` | 0 | Canonical | See meaning below. | | `INTERRUPT_POLICY_CANCEL_ONGOING` | 1 | Canonical | See meaning below. | | `INTERRUPT_POLICY_QUEUE` | 2 | Canonical | See meaning below. | | `INTERRUPT_POLICY_IGNORE` | 3 | Canonical | Accept the send without persisting its message or starting a new run; let the ongoing run continue. | **`INTERRUPT_POLICY_REJECT_NEW`** Reject the new send with an error while a run is active; do not append its user message. Reject the new Send with an error if a run is active **`INTERRUPT_POLICY_CANCEL_ONGOING`** Cancel the ongoing run and start a new run for the incoming message. Cancel the ongoing run and immediately start a new one with the new message **`INTERRUPT_POLICY_QUEUE`** Queue the incoming message to run after the current run completes. Queue the new Send; it will run after the current run completes
Exactly one of: Variant 1: Type: `string` Enum: `INTERRUPT_POLICY_REJECT_NEW`, `INTERRUPT_POLICY_CANCEL_ONGOING`, `INTERRUPT_POLICY_QUEUE`, `INTERRUPT_POLICY_IGNORE` Variant 2: Type: `integer(int32)` **maxLoops** `string(int64)` Default limit on agentic generation loops for the conversation. Pattern: ^-?\d+$ **maxParallelTools** `string(int64)` Maximum number of tool executions allowed concurrently by this configuration. Pattern: ^-?\d+$ **mcpServers** `array[llm_v1_common_v1_MCPServerReference]` MCP servers available to this conversation; used for tool discovery/filtering MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#response). **serverId** `string` ID of pre-configured MCP server (e.g., "github", "filesystem"). **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **toolPolicy** `any` Optional per-conversation tool execution policy applied to AgentConfig All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **promptVariables** `map[string, any]` Typed values used when rendering profile prompt templates. Numbers, arrays, Boolean values and strings retain their respective JSON types. The values are shared by profiles in the conversation and can be refreshed with UpdatePromptVariables. Switching profiles renders the new template with the same values. **activeRunId** `string` Run tracked by the conversation. Older threads can retain the last run ID after it ends; inspect active\_running before interpreting this as a currently active run. **activeRunning** `boolean` Whether an active run was observed. False may be omitted from JSON; it does not establish that an accepted or queued request completed. **contextManagementSettings** `any` Configuration governing the conversation’s context management and compaction. All of: Variant 1: Configuration for context management Model reference: [ContextManagementSettings](/api/models/schema-1hgrvsu34j#response). **strategy** `any` Context management strategy selected for the conversation. How stored conversation history is selected or summarized for model context.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTEXT_STRATEGY_COMPACTION` | 0 | Canonical | Use completed compaction summaries and remaining history; fall back to windowing when no completed summary is available. | | `CONTEXT_STRATEGY_WINDOWING` | 1 | Canonical | Keep a bounded window of recent conversation messages according to the windowing configuration. | | `CONTEXT_STRATEGY_NONE` | 2 | Canonical | Pass the conversation history without applying compaction or windowing. |
Exactly one of: Variant 1: Type: `string` Enum: `CONTEXT_STRATEGY_COMPACTION`, `CONTEXT_STRATEGY_WINDOWING`, `CONTEXT_STRATEGY_NONE` Variant 2: Type: `integer(int32)` **compactionConfig** `any` Configuration applied when summarizing the conversation context. All of: Variant 1: Configuration for compaction strategy Model reference: [CompactionConfig](/api/models/schema-1hbvkcgu5m#response). **mode** `any` Context compaction mode selected by the operation. SYNC, ASYNC Whether context compaction blocks the triggering operation or proceeds asynchronously.
| Value | No. | Form | Meaning | |---|---|---|---| | `COMPACTION_MODE_SYNC` | 0 | Canonical | Wait for compaction to finish before continuing the dependent operation. | | `COMPACTION_MODE_ASYNC` | 1 | Canonical | Start compaction asynchronously and apply its result when it becomes available. |
Exactly one of: Variant 1: Type: `string` Enum: `COMPACTION_MODE_SYNC`, `COMPACTION_MODE_ASYNC` Variant 2: Type: `integer(int32)` **threshold** `any` Token-count or context-window-percentage threshold that triggers compaction. All of: Variant 1: Threshold configuration for triggering compaction token\_count and percentage are mutually exclusive alternatives. Independent tracked fields do not enforce this relationship. Model reference: [ThresholdConfig](/api/models/schema-1frig4k431#response). **tokenCount** `string(int64)` Absolute token limit. Pattern: ^-?\d+$ **percentage** `string(int64)` % of model's context window. Pattern: ^-?\d+$ **generationConfig** `any` Separate config for compaction LLM calls. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#response). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#response). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#response). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#response). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#response). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#response). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#response). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinition]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#response). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfig]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#response). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#response). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#response). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#response). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#response). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#response). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#response). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#response). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **preserveRecent** `string(int64)` Messages to keep uncompacted. Pattern: ^-?\d+$ **windowingConfig** `any` Rules selecting the message window retained in model context. All of: Variant 1: Configuration for windowing strategy Model reference: [WindowingConfig](/api/models/schema-1he7ulevif#response). **maxMessages** `string(int64)` Maximum number of conversation messages to retain in the context window. Default: 100 Pattern: ^-?\d+$ **selectiveExclusionConfig** `any` Rules selecting content to omit from the model context. All of: Variant 1: Configuration for selective exclusion Model reference: [SelectiveExclusionConfig](/api/models/schema-1hc73qpaio#response). **excludeToolResults** `boolean` Whether tool-result content is excluded from model context. **excludeImages** `boolean` Whether image content is excluded from model context. **excludeFiles** `boolean` Whether file content is excluded from model context. **excludeReasoning** `boolean` When true, reasoning/thinking content parts are excluded from context **compactions** `array[llm_v1_actors_conversation_v1_Compaction]` Recorded context compaction operations for the conversation. Compaction metadata Model reference: [Compaction](/api/models/schema-1fpqunnq41#response). **id** `string` Identifier of the compaction record. **startSequence** `string(int64)` Sequence number of the first conversation message represented by the compaction. Pattern: ^-?\d+$ **endSequence** `string(int64)` Sequence number of the last conversation message represented by the compaction. Pattern: ^-?\d+$ **summary** `string` Summary text produced by conversation compaction. **originalTokenCount** `string(int64)` Estimated token count of the context before compaction. Pattern: ^-?\d+$ **summaryTokenCount** `string(int64)` Estimated token count of the generated summary. Pattern: ^-?\d+$ **modelUsed** `string` Model identifier used for the context compaction. **createdAt** `string(date-time)` Time when this record was created. **status** `any` Execution state of the conversation compaction. Execution state of a conversation context-compaction attempt.
| Value | No. | Form | Meaning | |---|---|---|---| | `COMPACTION_STATUS_PENDING` | 0 | Canonical | Compaction was started and its result is still pending. | | `COMPACTION_STATUS_COMPLETED` | 1 | Canonical | Compaction completed and produced its result. | | `COMPACTION_STATUS_FAILED` | 2 | Canonical | Compaction failed; inspect the associated error. |
Exactly one of: Variant 1: Type: `string` Enum: `COMPACTION_STATUS_PENDING`, `COMPACTION_STATUS_COMPLETED`, `COMPACTION_STATUS_FAILED` Variant 2: Type: `integer(int32)` **triggerReason** `any` Reason for triggering this compaction (auto threshold vs manual) Compaction Events Reason a conversation context-compaction attempt was started.
| Value | No. | Form | Meaning | |---|---|---|---| | `COMPACTION_TRIGGER_REASON_THRESHOLD_EXCEEDED` | 0 | Canonical | Context usage crossed the configured compaction threshold. | | `COMPACTION_TRIGGER_REASON_MANUAL` | 1 | Canonical | A caller explicitly requested compaction. |
Exactly one of: Variant 1: Type: `string` Enum: `COMPACTION_TRIGGER_REASON_THRESHOLD_EXCEEDED`, `COMPACTION_TRIGGER_REASON_MANUAL` Variant 2: Type: `integer(int32)` **compactionInProgress** `boolean` Whether a context compaction is currently in progress. **totalUsage** `any` Cumulative token usage and cost for the conversation. Read from conversation state rather than a delayed list projection. Absent when no usage has accrued. All of: Variant 1: Usage accounting Model reference: [Usage](/api/models/schema-1j1vov2uoh#response). **promptTokens** `string(int64)` Prompt-token usage reported by the model provider. Pattern: ^-?\d+$ **completionTokens** `string(int64)` Completion-token usage reported by the model provider. Pattern: ^-?\d+$ **totalTokens** `string(int64)` Total token usage reported by the model provider. Pattern: ^-?\d+$ **costEstimate** `any` Estimated cost in USD. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completionTokensDetails** `any` Breakdown of completion tokens. All of: Variant 1: Breakdown of completion-token usage. Categories are measured by different upstream tokenizers and need not sum to completion\_tokens; reasoning\_tokens can exceed completion\_tokens. One category must not be derived by subtracting the others. Model reference: [CompletionTokensDetails](/api/models/schema-1i6q4qpg72#response). **reasoningTokens** `string(int64)` Tokens used for reasoning/thinking. Pattern: ^-?\d+$ **imageTokens** `string(int64)` Completion tokens emitted as image output. Pattern: ^-?\d+$ **audioTokens** `string(int64)` Completion tokens emitted as audio output. Pattern: ^-?\d+$ **promptTokensDetails** `any` Breakdown of prompt tokens (cache). All of: Variant 1: Breakdown of prompt token usage by category (input-side cache accounting) Subset semantics: cached\_tokens and cache\_write\_tokens are a breakdown *of* prompt\_tokens, so cached\_tokens + cache\_write\_tokens \<= Usage.prompt\_tokens. Ordinary (full-rate) prompt tokens = prompt\_tokens - cached\_tokens - cache\_write\_tokens. audio\_tokens / video\_tokens are modality breakdowns of prompt\_tokens (also a subset). Model reference: [PromptTokensDetails](/api/models/schema-1ivj82m55o#response). **cachedTokens** `string(int64)` Prompt tokens served from cache (cache READ). Pattern: ^-?\d+$ **cacheWriteTokens** `string(int64)` Prompt tokens written to cache this call (cache WRITE). Pattern: ^-?\d+$ **audioTokens** `string(int64)` Prompt tokens from audio input (multimodal). Pattern: ^-?\d+$ **videoTokens** `string(int64)` Prompt tokens from video input (multimodal). Pattern: ^-?\d+$ **costDetails** `any` Breakdown of upstream provider cost (BYOK routes). All of: Variant 1: Breakdown of model-provider cost. When the customer supplies the provider key, usage.cost is zero and upstream\_inference\_cost reports the provider spend, split into prompt and completion components. Model reference: [CostDetails](/api/models/schema-1ia0h761lm#response). **upstreamInferenceCost** `any` Total upstream provider cost (USD) on BYOK routes. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferencePromptCost** `any` Upstream cost attributed to prompt tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferenceCompletionCost** `any` Upstream cost attributed to completion tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **isByok** `boolean` Whether this generation used the customer's own model-provider key. **externalId** `string` Echoed back so a caller addressing by conversation\_key can reconcile its own identifier without a second lookup. Empty when none was supplied. **conversationKey** `string` System thread id keying the conversation, always populated. Mirror of external\_id for the other direction: a caller addressing by external\_id learns the thread id without a second lookup. **lastRunStatus** `any` Terminal status of the last generation run that has ended. Unset until a run has ended. Execution state of an agent generation run, separate from the reason a terminal run ended. The terminal states are COMPLETED, FAILED, CANCELLED and TIMED\_OUT. Treat every other or unrecognized value as non-terminal. Reasons such as rejected, malformed or discarded belong in the reason field rather than in this status.
| Value | No. | Form | Meaning | |---|---|---|---| | `AGENT_STATUS_ACTIVE` | 0 | Canonical | The run is active and has not yet reached a more specific execution phase or terminal outcome. | | `AGENT_STATUS_GENERATING` | 1 | Canonical | The run is generating a model response. | | `AGENT_STATUS_EXECUTING_TOOLS` | 2 | Canonical | The run is executing server-side tools. | | `AGENT_STATUS_COMPLETED` | 3 | Canonical | The run finished successfully. | | `AGENT_STATUS_FAILED` | 4 | Canonical | The run ended with a failure; inspect its error or end reason. | | `AGENT_STATUS_QUEUED` | 5 | Canonical | See meaning below. | | `AGENT_STATUS_AWAITING_CLIENT_TOOLS` | 6 | Canonical | The run is waiting for the caller to execute client-side tools and submit their results. This is a non-terminal phase. EXECUTING\_TOOLS instead means the server is running an MCP tool. | | `AGENT_STATUS_CANCELLED` | 7 | Canonical | See meaning below. | | `AGENT_STATUS_TIMED_OUT` | 8 | Canonical | See meaning below. | **`AGENT_STATUS_QUEUED`** The incoming message is queued behind an ongoing run under the queue interruption policy. Message was queued due to QUEUE interrupt policy **`AGENT_STATUS_CANCELLED`** The run ended because a client or its invocation cancelled it. Terminal: stopped by a client cancel or a cancelled invocation **`AGENT_STATUS_TIMED_OUT`** The run ended because a run-level time limit elapsed. Terminal: a run-level bound elapsed
Exactly one of: Variant 1: Type: `string` Enum: `AGENT_STATUS_ACTIVE`, `AGENT_STATUS_GENERATING`, `AGENT_STATUS_EXECUTING_TOOLS`, `AGENT_STATUS_COMPLETED`, `AGENT_STATUS_FAILED`, `AGENT_STATUS_QUEUED`, `AGENT_STATUS_AWAITING_CLIENT_TOOLS`, `AGENT_STATUS_CANCELLED`, `AGENT_STATUS_TIMED_OUT` Variant 2: Type: `integer(int32)` #### conversations-getConversationState-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "messageHistory": [ { "role": "ROLE_SYSTEM", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Example text", "cachePreferred": true } ], "toolCalls": [ { "id": "example_123", "name": "example", "status": "TOOL_EXECUTION_STATUS_PENDING", "serverId": "example_123", "isClientTool": true, "description": "example", "approvedBy": "example", "endReason": "example" } ], "name": "example", "timestamp": "2026-09-16T12:00:00Z", "messageId": "example_123", "annotations": [ { "kind": "ANNOTATION_KIND_URL_CITATION" } ], "sequence": "1", "generatedBy": "example", "usage": { "promptTokens": 1, "completionTokens": 1, "totalTokens": 1, "costEstimate": 1, "isByok": true }, "model": "example", "generationContext": { "languagePreference": "en-US", "resolvedSystemPrompt": "Example text", "profileId": "example_123", "model": "example", "promptSource": "PROMPT_SOURCE_CLIENT_OVERRIDE", "profileVersion": 1, "fragmentsVersion": 1, "profileRenderFailed": true, "resolvedPromptHash": "Example text", "resolvedUserContext": "Example text" }, "clientContext": {}, "feedback": [ { "kind": "FEEDBACK_KIND_THUMB", "thumbUp": true, "reason": "example", "ratedBy": "example" } ], "sourceUserMessageId": "example_123", "finishReason": "example" } ], "defaultGenerationConfig": { "model": "example", "models": [ "example" ], "systemPrompt": "Example text", "modelRoutingFilter": { "minContextLength": "1", "minMaxCompletionTokens": "1", "requiredInputModalities": [ "example" ], "requiredOutputModalities": [ "example" ], "maxPromptCost": 1, "maxCompletionCost": 1, "excludeModerated": true, "requiredParameters": [ "example" ] }, "provider": { "order": [ "example" ], "allowFallbacks": true, "requireParameters": true, "dataCollection": "DATA_COLLECTION_MODE_ALLOW", "zdr": true, "only": [ "example" ], "ignore": [ "example" ], "quantizations": [ "example" ], "sort": "PROVIDER_SORT_PRICE", "enforceDistillableText": true }, "reasoning": { "effort": "EFFORT_HIGH", "maxTokens": 1, "exclude": true, "includeReasoningHistory": true }, "usage": { "include": true }, "transforms": [ "example" ], "tools": [ { "name": "example", "description": "example", "serverId": "example_123", "tags": [ "example" ], "documentationUrl": "https://example.com/resource" } ], "toolChoice": { "kind": "TOOL_CHOICE_KIND_AUTO", "specificToolName": "example" }, "clientTools": [ { "name": "example", "description": "example", "serverId": "example_123", "tags": [ "example" ], "documentationUrl": "https://example.com/resource" } ], "toolPolicy": { "requireApprovalToolNamePatterns": [ "example" ], "requireApprovalServerIds": [ "example_123" ], "autoApproveToolNamePatterns": [ "example" ], "autoApproveServerIds": [ "example_123" ], "approvalMode": "APPROVAL_MODE_MIXED", "clientToolMode": "CLIENT_TOOL_MODE_MIXED", "approvalTimeoutMs": 1, "failOnApprovalTimeoutToolNamePatterns": [ "example" ], "stableSortByCallIndexOnTie": true, "maxParallelToolCalls": 1, "maxToolCallsPerLoop": 1, "maxTotalToolCalls": 1, "retriableToolNamePatterns": [ "example" ], "maxRetries": 1, "retryableErrorSubstrings": [ "example" ], "nonRetryableErrorSubstrings": [ "example" ], "clientToolTimeoutMs": 1, "failureMode": "FAILURE_MODE_CONTINUE" }, "temperature": 1, "topP": 1, "maxOutputTokens": 1, "frequencyPenalty": 1, "presencePenalty": 1, "stopSequences": [ "example" ], "seed": "1", "responseFormat": { "jsonObject": true, "schemaName": "example", "validate": true, "maxValidationRetries": 1, "responseHealing": true }, "allowParallelToolCalls": true, "topK": 1, "repetitionPenalty": 1, "logitBias": {}, "topLogprobs": 1, "minP": 1, "topA": 1, "user": "example", "modalities": [ "MODALITY_TEXT" ], "plugins": [ { "id": "example_123" } ], "languagePreference": "en-US", "timeAware": { "includeCurrentTime": true, "includeMessageTimestamps": true, "includeFileTimestamps": true, "timezone": "example", "timestampFormat": "" }, "turnContext": { "enabled": true, "includeToolGuidance": true, "format": "minimal" }, "mem0": { "enabled": true, "searchTopK": 1, "searchThreshold": 1, "injectAsSystemContext": true, "searchQueryOverride": "Example text", "enableRerank": true, "addMemoriesAsync": true, "customExtractionPrompt": "Example text", "enableGraph": true, "agentIdOverride": "example_123", "exposeAsMcpTool": true, "includeAssistantMessages": true, "injectMemoryTimestamps": true }, "requestTimeoutSeconds": 1, "fileResolution": { "failureMode": "FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION" }, "clearTools": true }, "settings": { "interruptPolicy": "INTERRUPT_POLICY_REJECT_NEW", "maxLoops": 1, "maxParallelTools": 1, "mcpServers": [ { "serverId": "example_123", "enabled": true, "priority": 1, "allowlistToolPatterns": [ "example" ], "blocklistToolPatterns": [ "example" ] } ], "toolPolicy": { "requireApprovalToolNamePatterns": [ "example" ], "requireApprovalServerIds": [ "example_123" ], "autoApproveToolNamePatterns": [ "example" ], "autoApproveServerIds": [ "example_123" ], "approvalMode": "APPROVAL_MODE_MIXED", "clientToolMode": "CLIENT_TOOL_MODE_MIXED", "approvalTimeoutMs": 1, "failOnApprovalTimeoutToolNamePatterns": [ "example" ], "stableSortByCallIndexOnTie": true, "maxParallelToolCalls": 1, "maxToolCallsPerLoop": 1, "maxTotalToolCalls": 1, "retriableToolNamePatterns": [ "example" ], "maxRetries": 1, "retryableErrorSubstrings": [ "example" ], "nonRetryableErrorSubstrings": [ "example" ], "clientToolTimeoutMs": 1, "failureMode": "FAILURE_MODE_CONTINUE" }, "promptVariables": { "example": "value" } }, "activeRunId": "example_123", "activeRunning": true, "contextManagementSettings": { "strategy": "CONTEXT_STRATEGY_COMPACTION", "compactionConfig": { "mode": "COMPACTION_MODE_SYNC", "preserveRecent": 1 }, "windowingConfig": { "maxMessages": 1 }, "selectiveExclusionConfig": { "excludeToolResults": true, "excludeImages": true, "excludeFiles": true, "excludeReasoning": true } }, "compactions": [ { "id": "example_123", "startSequence": "1", "endSequence": "1", "summary": "example", "originalTokenCount": 1, "summaryTokenCount": 1, "modelUsed": "example", "createdAt": "2026-09-16T12:00:00Z", "status": "COMPACTION_STATUS_PENDING", "triggerReason": "COMPACTION_TRIGGER_REASON_THRESHOLD_EXCEEDED" } ], "compactionInProgress": true, "totalUsage": { "promptTokens": 1, "completionTokens": 1, "totalTokens": 1, "costEstimate": 1, "completionTokensDetails": { "reasoningTokens": 1, "imageTokens": 1, "audioTokens": 1 }, "promptTokensDetails": { "cachedTokens": 1, "cacheWriteTokens": 1, "audioTokens": 1, "videoTokens": 1 }, "costDetails": { "upstreamInferenceCost": 1, "upstreamInferencePromptCost": 1, "upstreamInferenceCompletionCost": 1 }, "isByok": true }, "externalId": "example_123", "conversationKey": "example_123", "lastRunStatus": "AGENT_STATUS_ACTIVE" } ``` #### cookbook-managed-agents-conversations-build-chat-assistant-json-04-response Illustrative response for Poll conversation state. Replace example resource identifiers with your own authorized values. ```json { "messageHistory": [ { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "What can you help me with?" } ], "timestamp": "2026-04-23T22:43:44.123Z", "messageId": "2a1f33ce-1abc-4a5d-9e22-1c0d1a2b3c4d", "sequence": "1" } ], "activeRunId": "64403669-5989-4ec3-ad9c-d84223f9679f", "activeRunning": true } ``` #### cookbook-managed-agents-conversations-build-chat-assistant-json-05-response Illustrative response for Poll conversation state. Replace example resource identifiers with your own authorized values. ```json { "messageHistory": [ { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "What can you help me with?" } ], "timestamp": "2026-04-23T22:43:44.123Z", "messageId": "2a1f33ce-1abc-4a5d-9e22-1c0d1a2b3c4d", "sequence": "1" }, { "role": "ROLE_ASSISTANT", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "I can assist you with a variety of tasks..." } ], "timestamp": "2026-04-23T22:43:51.653Z", "messageId": "3f2d44de-8db6-4f67-8e51-5c600902491b", "sequence": "2", "generatedBy": "64403669-5989-4ec3-ad9c-d84223f9679f", "usage": { "promptTokens": 359, "completionTokens": 65, "totalTokens": 424 }, "model": "google/gemini-3.1-flash-lite" } ], "lastRunStatus": "AGENT_STATUS_COMPLETED" } ``` #### cookbook-managed-agents-conversations-generation-json-02-response Illustrative response for Step 1: Send once and read the same conversation. Replace example resource identifiers with your own authorized values. ```json { "messageHistory": [ { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Hello, what can you help me with?" } ], "timestamp": "2026-04-23T22:43:44.123Z", "messageId": "2a1f33ce-1abc-4a5d-9e22-1c0d1a2b3c4d", "sequence": "1" } ], "activeRunId": "64403669-5989-4ec3-ad9c-d84223f9679f", "activeRunning": true } ``` #### cookbook-managed-agents-conversations-generation-json-03-response Illustrative response for Step 1: Send once and read the same conversation. Replace example resource identifiers with your own authorized values. ```json { "messageHistory": [ { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Hello, what can you help me with?" } ], "timestamp": "2026-04-23T22:43:44.123Z", "messageId": "2a1f33ce-1abc-4a5d-9e22-1c0d1a2b3c4d", "sequence": "1" }, { "role": "ROLE_ASSISTANT", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "I can assist you with..." } ], "timestamp": "2026-04-23T22:43:51.653Z", "messageId": "3f2d44de-8db6-4f67-8e51-5c600902491b", "sequence": "2", "generatedBy": "64403669-5989-4ec3-ad9c-d84223f9679f", "usage": { "promptTokens": 359, "completionTokens": 65, "totalTokens": 424 }, "model": "google/gemini-3.1-flash-lite" } ], "lastRunStatus": "AGENT_STATUS_COMPLETED" } ``` Document ID: `DOC-MA-conversations-api-getConversationState`. [Section identities and revisions](/documentation-manifest.json). - Get full conversation state: `DOC-MA-conversations-api-getConversationState#overview` - Request: `DOC-MA-conversations-api-getConversationState#request` - Responses: `DOC-MA-conversations-api-getConversationState#responses` --- # Get a specific memory URL: https://docs.travila.ai/api/conversations/get-memory **POST** `/api/v1/llm/get-memory` Requests a memory by ID. Full project/user ownership checks are not currently enforced for these by-ID operations. They are not a supported access boundary for an untrusted end-user client. See [Memory](/managed-agents/memory-knowledge) for the current limits. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Use remembered preferences in a returning user’s conversation](/managed-agents/memory-knowledge) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for retrieving a memory record by its identifier. **memoryId** `string` **required** Memory ID to retrieve Minimum length: 1 #### conversations-getMemory-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "memoryId": "example_123" } ``` #### cookbook-managed-agents-memory-knowledge-index-03-request Guide request for Inspect the selected record before changing it. Replace example resource identifiers with your own authorized values. ```json { "memoryId": "mem_abc123" } ``` ## Responses ### 200 — Memory returned Content type: `application/json` Result of retrieving a memory record by its identifier. **memory** `any` The requested memory All of: Variant 1: A memory is a stored statement associated with a user and, when recorded, an agent or conversation and a run or session. The `appId` field is the existing public wire name for the tenant identifier. The field name remains unchanged for compatibility. `metadata` is an object whose values are strings. A search can add a `score`; the provider determines its scale. The score does not measure factual truth. `createdAt` and `updatedAt` are RFC 3339 timestamp strings and may include fractional seconds. Absent timestamps mean that no value was returned. Memory text can be incomplete, stale or incorrect. Show the text and available timestamps to the user before acting on it. Search results are a selection by relevance, not a full account of stored memory. See the [memory cookbook](/managed-agents/memory-knowledge) for review and correction tasks. Model reference: [Memory](/api/models/schema-1k63a85bkp#response). **id** `string` Unique memory identifier. **memory** `string` Stored fact text. It may be incomplete, stale or incorrect. **userId** `string` User associated with the memory. **agentId** `string` Agent or conversation associated with the memory. **appId** `string` Tenant identifier associated with the memory. **runId** `string` Associated run or session identifier. **metadata** `map[string, string]` Additional string-valued metadata attached to the memory. **score** `any` Relevance score returned by search. Its scale is provider-specific and is not a probability that the fact is correct. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **createdAt** `string(date-time)` Creation time as an RFC 3339 timestamp; absent when unavailable. **updatedAt** `string(date-time)` Last update time as an RFC 3339 timestamp; absent when unavailable. #### conversations-getMemory-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "memory": { "id": "example_123", "memory": "example", "userId": "example_123", "agentId": "example_123", "appId": "example_123", "runId": "example_123", "metadata": {}, "score": 1, "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z" } } ``` Document ID: `DOC-MA-conversations-api-getMemory`. [Section identities and revisions](/documentation-manifest.json). - Get a specific memory: `DOC-MA-conversations-api-getMemory#overview` - Request: `DOC-MA-conversations-api-getMemory#request` - Responses: `DOC-MA-conversations-api-getMemory#responses` --- # Get a single tool call by ID URL: https://docs.travila.ai/api/conversations/get-tool-call **POST** `/api/v1/llm/get-tool-call` Reads the identified tool call from the conversation's current run state, including resolved calls retained there. An empty response means the call was not found in that current run; it does not prove the call never executed. Match the call ID and inspect both status and result. If its answer window expired, the result reports `client tool timeout`. Inspect both the status and reason before deciding whether any work remains; expiration does not establish whether an action dispatched to the client took effect. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Let a customer navigate your app through chat](/managed-agents/delegation-approvals/build-agent-with-tools) · [Build an assistant that researches the web](/integrations/tools-connections) · [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps) · [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for locating a tool call within conversation history. **conversationKey** `string` **required** Identifier of the conversation thread. Minimum length: 1 **toolCallId** `string` Identifier of the tool call to retrieve. #### conversations-getToolCall-request Inspect a tool call using an ID previously returned by the conversation. ```json { "conversationKey": "example_123", "toolCallId": "tool_call_123" } ``` #### cookbook-managed-agents-delegation-approvals-using-tools-06-request Guide request for Recover the original call after a disconnect. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "support-chat-001", "toolCallId": "call_306135" } ``` ## Responses ### 200 — The tool call Content type: `application/json` Result of locating a tool call within conversation history. **messageSequence** `string(int64)` Sequence number of the conversation message containing the tool call. Pattern: ^-?\d+$ **messageId** `string` Identifier of the conversation message containing the tool call. **toolCall** `any` Tool call retrieved from the identified conversation message. All of: Variant 1: A single structured tool call emitted by the model [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat) is the client answer window. Expiry ends that wait and rejects late results; the timeout policy determines the outcome. Model reference: [ToolCall](/api/models/schema-1it6mqsqoo#response). **id** `string` Provider-supplied call id. **name** `string` Name of the tool or function being invoked. **argumentsJson** `map[string, any]` JSON object payload. **status** `any` Execution status recorded for the tool call. Execution state of a tool call, including approval waiting and terminal outcomes. The terminal outcomes are COMPLETED, FAILED, CANCELLED and TIMED\_OUT; inspect ToolCall.end\_reason for why a call ended rather than treating the reason as another status. Use a listed execution status. The end reason explains the outcome separately from the status.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_EXECUTION_STATUS_PENDING` | 0 | Canonical | The tool call is waiting to begin execution. | | `TOOL_EXECUTION_STATUS_EXECUTING` | 1 | Canonical | The tool call is currently executing. | | `TOOL_EXECUTION_STATUS_COMPLETED` | 2 | Canonical | The tool call completed successfully. This is a terminal outcome. | | `TOOL_EXECUTION_STATUS_FAILED` | 3 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. | | `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 4 | Canonical | The tool call is waiting for approval before it can execute. | | `TOOL_EXECUTION_STATUS_CANCELLED` | 5 | Canonical | The tool call was cancelled before normal completion. | | `TOOL_EXECUTION_STATUS_TIMED_OUT` | 6 | Canonical | Tool execution ended because its time limit elapsed. |
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_EXECUTION_STATUS_PENDING`, `TOOL_EXECUTION_STATUS_EXECUTING`, `TOOL_EXECUTION_STATUS_COMPLETED`, `TOOL_EXECUTION_STATUS_FAILED`, `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, `TOOL_EXECUTION_STATUS_CANCELLED`, `TOOL_EXECUTION_STATUS_TIMED_OUT` Variant 2: Type: `integer(int32)` **resultJson** `map[string, any]` Tool execution result (object). **executedAt** `string(date-time)` Time when the tool execution was recorded. **serverId** `string` Which server provides this tool (for MCP tools). **isClientTool** `boolean` True if this is a client-side tool handled by client. **description** `string` Tool description captured from the resolved tool definition when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. **parametersJsonSchema** `map[string, any]` JSON Schema describing the tool’s input arguments. **requiresApprovalAt** `string(date-time)` Deadline for an approval decision, calculated from the effective approval timeout. This is not the time the call began waiting. An approval received after the deadline is rejected. **approvedAt** `string(date-time)` Timestamp when approval decision was recorded (if approved/rejected) **approvedBy** `string` Identifier of the approver (user id, email, or actor key) **executionDuration** `string` End-to-end execution duration once terminal (includes tool server latency or client-side time) Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **endReason** `string` Why this call ended, in one short phrase — "approval rejected", "approval timeout", or the underlying error. Set only once `status` is terminal, and empty on a clean COMPLETED. Use this reason to distinguish a rejection from a failure without parsing the tool result. **clientToolDeadlineAt** `string(date-time)` Deadline by which the client must submit a result for this call, stamped when the call is dispatched to a caller. #### conversations-getToolCall-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "messageSequence": "1", "messageId": "example_123", "toolCall": { "id": "example_123", "name": "example", "argumentsJson": { "example": "value" }, "status": "TOOL_EXECUTION_STATUS_PENDING", "resultJson": { "example": "value" }, "executedAt": "2026-09-16T12:00:00Z", "serverId": "example_123", "isClientTool": true, "description": "example", "parametersJsonSchema": { "example": "value" }, "requiresApprovalAt": "2026-09-16T12:00:00Z", "approvedAt": "2026-09-16T12:00:00Z", "approvedBy": "example", "executionDuration": "1s", "endReason": "example", "clientToolDeadlineAt": "2026-09-16T12:00:00Z" } } ``` Document ID: `DOC-MA-conversations-api-getToolCall`. [Section identities and revisions](/documentation-manifest.json). - Get a single tool call by ID: `DOC-MA-conversations-api-getToolCall#overview` - Request: `DOC-MA-conversations-api-getToolCall#request` - Responses: `DOC-MA-conversations-api-getToolCall#responses` --- # List user memories URL: https://docs.travila.ai/api/conversations/list-memories **POST** `/api/v1/llm/list-memories` Returns memories in the effective user's scope. This operation has no pagination cursor or category filter. A capped response does not prove that the user has seen every stored record or provide a complete all-records traversal guarantee. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Use remembered preferences in a returning user’s conversation](/managed-agents/memory-knowledge) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for listing memory records in the caller’s scope. **agentId** `string` Filter by agent/conversation ID (optional) **limit** `string(int64)` **required** Maximum number of memories to return. Supply explicitly; omission is rejected. Pattern: ^-?\d+$ #### conversations-listMemories-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "limit": 1 } ``` #### cookbook-managed-agents-memory-knowledge-index-02-request Guide request for Step 2: Let the user review the stored records. Replace example resource identifiers with your own authorized values. ```json { "limit": 100 } ``` ## Responses ### 200 — Memories listed Content type: `application/json` Result of listing memory records in the caller’s scope. **memories** `array[memory_v1_Memory]` List of user's memories A memory is a stored statement associated with a user and, when recorded, an agent or conversation and a run or session. The `appId` field is the existing public wire name for the tenant identifier. The field name remains unchanged for compatibility. `metadata` is an object whose values are strings. A search can add a `score`; the provider determines its scale. The score does not measure factual truth. `createdAt` and `updatedAt` are RFC 3339 timestamp strings and may include fractional seconds. Absent timestamps mean that no value was returned. Memory text can be incomplete, stale or incorrect. Show the text and available timestamps to the user before acting on it. Search results are a selection by relevance, not a full account of stored memory. See the [memory cookbook](/managed-agents/memory-knowledge) for review and correction tasks. Model reference: [Memory](/api/models/schema-1k63a85bkp#response). **id** `string` Unique memory identifier. **memory** `string` Stored fact text. It may be incomplete, stale or incorrect. **userId** `string` User associated with the memory. **agentId** `string` Agent or conversation associated with the memory. **appId** `string` Tenant identifier associated with the memory. **runId** `string` Associated run or session identifier. **metadata** `map[string, string]` Additional string-valued metadata attached to the memory. **score** `any` Relevance score returned by search. Its scale is provider-specific and is not a probability that the fact is correct. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **createdAt** `string(date-time)` Creation time as an RFC 3339 timestamp; absent when unavailable. **updatedAt** `string(date-time)` Last update time as an RFC 3339 timestamp; absent when unavailable. #### conversations-listMemories-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "memories": [ { "id": "example_123", "memory": "example", "userId": "example_123", "agentId": "example_123", "appId": "example_123", "runId": "example_123", "metadata": {}, "score": 1, "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z" } ] } ``` Document ID: `DOC-MA-conversations-api-listMemories`. [Section identities and revisions](/documentation-manifest.json). - List user memories: `DOC-MA-conversations-api-listMemories#overview` - Request: `DOC-MA-conversations-api-listMemories#request` - Responses: `DOC-MA-conversations-api-listMemories#responses` --- # List pending tool approvals URL: https://docs.travila.ai/api/conversations/list-pending-approvals **POST** `/api/v1/llm/list-pending-approvals` Returns all tool calls in the active generation run that are awaiting human approval. Used when the tool execution policy requires confirmation before executing certain tools. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Approve a tool action and finish the conversation](/managed-agents/delegation-approvals/using-tools) · [Event catalog](/api/events) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for reading tool calls awaiting approval. **conversationKey** `string` **required** Identifier of the conversation thread. Minimum length: 1 #### conversations-listPendingApprovals-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "conversationKey": "example_123" } ``` #### cookbook-managed-agents-delegation-approvals-using-tools-01-request Guide request for Step 2: Show the action awaiting a decision. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "support-chat-001" } ``` ## Responses ### 200 — Pending approvals listed Content type: `application/json` Result of reading tool calls awaiting approval. **toolCalls** `array[llm_v1_common_v1_ToolCall]` Tool calls waiting for a caller approval decision. A single structured tool call emitted by the model [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat) is the client answer window. Expiry ends that wait and rejects late results; the timeout policy determines the outcome. Model reference: [ToolCall](/api/models/schema-1it6mqsqoo#response). **id** `string` Provider-supplied call id. **name** `string` Name of the tool or function being invoked. **argumentsJson** `map[string, any]` JSON object payload. **status** `any` Execution status recorded for the tool call. Execution state of a tool call, including approval waiting and terminal outcomes. The terminal outcomes are COMPLETED, FAILED, CANCELLED and TIMED\_OUT; inspect ToolCall.end\_reason for why a call ended rather than treating the reason as another status. Use a listed execution status. The end reason explains the outcome separately from the status.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_EXECUTION_STATUS_PENDING` | 0 | Canonical | The tool call is waiting to begin execution. | | `TOOL_EXECUTION_STATUS_EXECUTING` | 1 | Canonical | The tool call is currently executing. | | `TOOL_EXECUTION_STATUS_COMPLETED` | 2 | Canonical | The tool call completed successfully. This is a terminal outcome. | | `TOOL_EXECUTION_STATUS_FAILED` | 3 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. | | `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 4 | Canonical | The tool call is waiting for approval before it can execute. | | `TOOL_EXECUTION_STATUS_CANCELLED` | 5 | Canonical | The tool call was cancelled before normal completion. | | `TOOL_EXECUTION_STATUS_TIMED_OUT` | 6 | Canonical | Tool execution ended because its time limit elapsed. |
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_EXECUTION_STATUS_PENDING`, `TOOL_EXECUTION_STATUS_EXECUTING`, `TOOL_EXECUTION_STATUS_COMPLETED`, `TOOL_EXECUTION_STATUS_FAILED`, `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, `TOOL_EXECUTION_STATUS_CANCELLED`, `TOOL_EXECUTION_STATUS_TIMED_OUT` Variant 2: Type: `integer(int32)` **resultJson** `map[string, any]` Tool execution result (object). **executedAt** `string(date-time)` Time when the tool execution was recorded. **serverId** `string` Which server provides this tool (for MCP tools). **isClientTool** `boolean` True if this is a client-side tool handled by client. **description** `string` Tool description captured from the resolved tool definition when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. **parametersJsonSchema** `map[string, any]` JSON Schema describing the tool’s input arguments. **requiresApprovalAt** `string(date-time)` Deadline for an approval decision, calculated from the effective approval timeout. This is not the time the call began waiting. An approval received after the deadline is rejected. **approvedAt** `string(date-time)` Timestamp when approval decision was recorded (if approved/rejected) **approvedBy** `string` Identifier of the approver (user id, email, or actor key) **executionDuration** `string` End-to-end execution duration once terminal (includes tool server latency or client-side time) Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **endReason** `string` Why this call ended, in one short phrase — "approval rejected", "approval timeout", or the underlying error. Set only once `status` is terminal, and empty on a clean COMPLETED. Use this reason to distinguish a rejection from a failure without parsing the tool result. **clientToolDeadlineAt** `string(date-time)` Deadline by which the client must submit a result for this call, stamped when the call is dispatched to a caller. #### conversations-listPendingApprovals-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "toolCalls": [ { "id": "example_123", "name": "example", "argumentsJson": { "example": "value" }, "status": "TOOL_EXECUTION_STATUS_PENDING", "resultJson": { "example": "value" }, "executedAt": "2026-09-16T12:00:00Z", "serverId": "example_123", "isClientTool": true, "description": "example", "parametersJsonSchema": { "example": "value" }, "requiresApprovalAt": "2026-09-16T12:00:00Z", "approvedAt": "2026-09-16T12:00:00Z", "approvedBy": "example", "executionDuration": "1s", "endReason": "example", "clientToolDeadlineAt": "2026-09-16T12:00:00Z" } ] } ``` Document ID: `DOC-MA-conversations-api-listPendingApprovals`. [Section identities and revisions](/documentation-manifest.json). - List pending tool approvals: `DOC-MA-conversations-api-listPendingApprovals#overview` - Request: `DOC-MA-conversations-api-listPendingApprovals#request` - Responses: `DOC-MA-conversations-api-listPendingApprovals#responses` --- # List client-side tool calls awaiting a result URL: https://docs.travila.ai/api/conversations/list-pending-client-tools **POST** `/api/v1/llm/list-pending-client-tools` Returns the client-side tool calls the run is currently waiting on, with the message each belongs to. Use it to recover after a dropped connection, or from a caller that never holds one. On reconnect, pull with this call and then submit — do not resend the original user message, which would start a second run and interrupt the one you were waiting on. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Let a customer navigate your app through chat](/managed-agents/delegation-approvals/build-agent-with-tools) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for reading client-side tool calls awaiting execution. **conversationKey** `string` **required** Identifier of the conversation thread. Minimum length: 1 **namePrefixFilters** `array[string]` When supplied, include only pending client tools whose names match one of these prefixes. Type: `string` #### conversations-listPendingClientTools-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "conversationKey": "example_123" } ``` #### cookbook-managed-agents-delegation-approvals-using-tools-05-request Guide request for Recover the original call after a disconnect. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "support-chat-001" } ``` ## Responses ### 200 — Outstanding client-side tool calls Content type: `application/json` Result of reading client-side tool calls awaiting execution. **messageSequences** `array[string(int64)]` Inlined fields aligned by index across the three arrays. Type: `string(int64)` Pattern: ^-?\d+$ **messageIds** `array[string]` Message identifiers aligned with the returned tool calls. Type: `string` **toolCalls** `array[llm_v1_common_v1_ToolCall]` Client-side tool calls aligned with the returned message identifiers and sequences. A single structured tool call emitted by the model [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat) is the client answer window. Expiry ends that wait and rejects late results; the timeout policy determines the outcome. Model reference: [ToolCall](/api/models/schema-1it6mqsqoo#response). **id** `string` Provider-supplied call id. **name** `string` Name of the tool or function being invoked. **argumentsJson** `map[string, any]` JSON object payload. **status** `any` Execution status recorded for the tool call. Execution state of a tool call, including approval waiting and terminal outcomes. The terminal outcomes are COMPLETED, FAILED, CANCELLED and TIMED\_OUT; inspect ToolCall.end\_reason for why a call ended rather than treating the reason as another status. Use a listed execution status. The end reason explains the outcome separately from the status.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_EXECUTION_STATUS_PENDING` | 0 | Canonical | The tool call is waiting to begin execution. | | `TOOL_EXECUTION_STATUS_EXECUTING` | 1 | Canonical | The tool call is currently executing. | | `TOOL_EXECUTION_STATUS_COMPLETED` | 2 | Canonical | The tool call completed successfully. This is a terminal outcome. | | `TOOL_EXECUTION_STATUS_FAILED` | 3 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. | | `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 4 | Canonical | The tool call is waiting for approval before it can execute. | | `TOOL_EXECUTION_STATUS_CANCELLED` | 5 | Canonical | The tool call was cancelled before normal completion. | | `TOOL_EXECUTION_STATUS_TIMED_OUT` | 6 | Canonical | Tool execution ended because its time limit elapsed. |
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_EXECUTION_STATUS_PENDING`, `TOOL_EXECUTION_STATUS_EXECUTING`, `TOOL_EXECUTION_STATUS_COMPLETED`, `TOOL_EXECUTION_STATUS_FAILED`, `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, `TOOL_EXECUTION_STATUS_CANCELLED`, `TOOL_EXECUTION_STATUS_TIMED_OUT` Variant 2: Type: `integer(int32)` **resultJson** `map[string, any]` Tool execution result (object). **executedAt** `string(date-time)` Time when the tool execution was recorded. **serverId** `string` Which server provides this tool (for MCP tools). **isClientTool** `boolean` True if this is a client-side tool handled by client. **description** `string` Tool description captured from the resolved tool definition when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. **parametersJsonSchema** `map[string, any]` JSON Schema describing the tool’s input arguments. **requiresApprovalAt** `string(date-time)` Deadline for an approval decision, calculated from the effective approval timeout. This is not the time the call began waiting. An approval received after the deadline is rejected. **approvedAt** `string(date-time)` Timestamp when approval decision was recorded (if approved/rejected) **approvedBy** `string` Identifier of the approver (user id, email, or actor key) **executionDuration** `string` End-to-end execution duration once terminal (includes tool server latency or client-side time) Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **endReason** `string` Why this call ended, in one short phrase — "approval rejected", "approval timeout", or the underlying error. Set only once `status` is terminal, and empty on a clean COMPLETED. Use this reason to distinguish a rejection from a failure without parsing the tool result. **clientToolDeadlineAt** `string(date-time)` Deadline by which the client must submit a result for this call, stamped when the call is dispatched to a caller. #### conversations-listPendingClientTools-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "messageSequences": [ "1" ], "messageIds": [ "example_123" ], "toolCalls": [ { "id": "example_123", "name": "example", "argumentsJson": { "example": "value" }, "status": "TOOL_EXECUTION_STATUS_PENDING", "resultJson": { "example": "value" }, "executedAt": "2026-09-16T12:00:00Z", "serverId": "example_123", "isClientTool": true, "description": "example", "parametersJsonSchema": { "example": "value" }, "requiresApprovalAt": "2026-09-16T12:00:00Z", "approvedAt": "2026-09-16T12:00:00Z", "approvedBy": "example", "executionDuration": "1s", "endReason": "example", "clientToolDeadlineAt": "2026-09-16T12:00:00Z" } ] } ``` Document ID: `DOC-MA-conversations-api-listPendingClientTools`. [Section identities and revisions](/documentation-manifest.json). - List client-side tool calls awaiting a result: `DOC-MA-conversations-api-listPendingClientTools#overview` - Request: `DOC-MA-conversations-api-listPendingClientTools#request` - Responses: `DOC-MA-conversations-api-listPendingClientTools#responses` --- # List conversation threads URL: https://docs.travila.ai/api/conversations/list-threads **POST** `/api/v1/llm/list-threads` Returns a paginated list of conversation threads for the authenticated user, ordered by `lastMessageAt` descending, then `threadId` descending for ties. Changes to `updatedAt` alone do not change the list position. Pass `nextPageToken` as `pageToken` to continue after the last returned thread in that order. Pages read the current conversation projection; they do not share a point-in-time snapshot. Concurrent message activity can move a thread ahead of a continuation token, so a multi-page traversal can miss threads that move while it is in progress. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build a support conversation the user can return to](/managed-agents/conversations) · [Connect signed-in users to their conversations](/core-platform/identity-access/authentication) · [Build a signed-in support chat that survives reconnects](/managed-agents/conversations/build-chat-assistant) · [Complete your first support-chat turn](/managed-agents/conversations/quickstart) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for listing conversation threads visible to the caller. **limit** `string(int64)` Maximum rows per page. Zero selects the default of 50. Values greater than 200 are clamped to 200. Negative values are rejected. Pattern: ^-?\d+$ **pageToken** `string` Opaque base64 cursor returned by prior call. Empty for first page. #### conversations-listThreads-request List the authenticated user’s conversations with default paging. ```json {} ``` ## Responses ### 200 — Threads listed successfully Content type: `application/json` Result of listing conversation threads visible to the caller. **threads** `array[llm_v1_services_gateway_v1_ThreadSummary]` Conversation summaries returned for this page. An absent JSON list means this page is empty. Conversation summary returned by thread listing and detail operations. Model reference: [ThreadSummary](/api/models/schema-p16s9mefht#response). **threadId** `string` Identifier of the conversation thread. **userId** `string` Identifier of the user associated with the conversation thread. **title** `string` Display title of the conversation thread. **tags** `array[string]` Labels associated with the conversation thread. Type: `string` **status** `any` Lifecycle status recorded for the conversation thread. Lifecycle condition of a stored conversation: active or archived. This is separate from the execution status of an individual generation run.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONVERSATION_STATUS_ACTIVE` | 0 | Canonical | The conversation is in its active lifecycle state. | | `CONVERSATION_STATUS_ARCHIVED` | 1 | Canonical | The conversation has been archived; this is a stored lifecycle condition, not a generation outcome. |
Exactly one of: Variant 1: Type: `string` Enum: `CONVERSATION_STATUS_ACTIVE`, `CONVERSATION_STATUS_ARCHIVED` Variant 2: Type: `integer(int32)` **messageCount** `string(int64)` Number of messages recorded in the thread summary. Pattern: ^-?\d+$ **lastMessagePreview** `string` Text preview of the most recently projected message. **lastMessageAt** `string(date-time)` Timestamp of the most recently projected message. **createdAt** `string(date-time)` Timestamp when the conversation thread was created. **updatedAt** `string(date-time)` Timestamp when the conversation thread summary was last updated. **externalId** `string` Caller-supplied identifier associated with the conversation thread. **nextPageToken** `string` Opaque continuation token for requesting the next page. #### conversations-listThreads-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "threads": [ { "threadId": "example_123", "userId": "example_123", "title": "example", "tags": [ "example" ], "status": "CONVERSATION_STATUS_ACTIVE", "messageCount": "1", "lastMessagePreview": "example", "lastMessageAt": "2026-09-16T12:00:00Z", "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z", "externalId": "example_123" } ], "nextPageToken": "example" } ``` #### cookbook-managed-agents-conversations-build-chat-assistant-json-01-response Illustrative response for Verify credentials with your first call. Replace example resource identifiers with your own authorized values. ```json {} ``` Document ID: `DOC-MA-conversations-api-listThreads`. [Section identities and revisions](/documentation-manifest.json). - List conversation threads: `DOC-MA-conversations-api-listThreads#overview` - Request: `DOC-MA-conversations-api-listThreads#request` - Responses: `DOC-MA-conversations-api-listThreads#responses` --- # Execute an MCP tool URL: https://docs.travila.ai/api/conversations/mcp-call-tool **POST** `/api/v1/llm/mcp-call-tool` Invokes an MCP tool directly, outside a conversation flow. Use it to test a tool without starting a generation run. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Check a chat integration before customers use it](/developer-experience/local-tooling/testing) · [Build an assistant that researches the web](/integrations/tools-connections) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for executing a tool through an MCP server. **toolCall** `any` Prefer ToolCall with server\_id/name and arguments\_json (object) All of: Variant 1: A single structured tool call emitted by the model [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat) is the client answer window. Expiry ends that wait and rejects late results; the timeout policy determines the outcome. Model reference: [ToolCall](/api/models/schema-1it6mqsqoo#request). **id** `string` Provider-supplied call id. **name** `string` Name of the tool or function being invoked. **argumentsJson** `map[string, any]` JSON object payload. **status** `any` Execution status recorded for the tool call. Execution state of a tool call, including approval waiting and terminal outcomes. The terminal outcomes are COMPLETED, FAILED, CANCELLED and TIMED\_OUT; inspect ToolCall.end\_reason for why a call ended rather than treating the reason as another status. Use a listed execution status. The end reason explains the outcome separately from the status.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_EXECUTION_STATUS_PENDING` | 0 | Canonical | The tool call is waiting to begin execution. | | `TOOL_EXECUTION_STATUS_EXECUTING` | 1 | Canonical | The tool call is currently executing. | | `TOOL_EXECUTION_STATUS_COMPLETED` | 2 | Canonical | The tool call completed successfully. This is a terminal outcome. | | `TOOL_EXECUTION_STATUS_FAILED` | 3 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. | | `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 4 | Canonical | The tool call is waiting for approval before it can execute. | | `TOOL_EXECUTION_STATUS_CANCELLED` | 5 | Canonical | The tool call was cancelled before normal completion. | | `TOOL_EXECUTION_STATUS_TIMED_OUT` | 6 | Canonical | Tool execution ended because its time limit elapsed. |
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_EXECUTION_STATUS_PENDING`, `TOOL_EXECUTION_STATUS_EXECUTING`, `TOOL_EXECUTION_STATUS_COMPLETED`, `TOOL_EXECUTION_STATUS_FAILED`, `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, `TOOL_EXECUTION_STATUS_CANCELLED`, `TOOL_EXECUTION_STATUS_TIMED_OUT` Variant 2: Type: `integer(int32)` **resultJson** `map[string, any]` Tool execution result (object). **executedAt** `string(date-time)` Time when the tool execution was recorded. **serverId** `string` Which server provides this tool (for MCP tools). **isClientTool** `boolean` True if this is a client-side tool handled by client. **description** `string` Tool description captured from the resolved tool definition when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. **parametersJsonSchema** `map[string, any]` JSON Schema describing the tool’s input arguments. **requiresApprovalAt** `string(date-time)` Deadline for an approval decision, calculated from the effective approval timeout. This is not the time the call began waiting. An approval received after the deadline is rejected. **approvedAt** `string(date-time)` Timestamp when approval decision was recorded (if approved/rejected) **approvedBy** `string` Identifier of the approver (user id, email, or actor key) **executionDuration** `string` End-to-end execution duration once terminal (includes tool server latency or client-side time) Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **endReason** `string` Why this call ended, in one short phrase — "approval rejected", "approval timeout", or the underlying error. Set only once `status` is terminal, and empty on a clean COMPLETED. Use this reason to distinguish a rejection from a failure without parsing the tool result. **clientToolDeadlineAt** `string(date-time)` Deadline by which the client must submit a result for this call, stamped when the call is dispatched to a caller. **requestId** `string` Correlation identifier for the MCP tool execution request. **sessionId** `string` Optional session routing hint for the MCP operation. #### conversations-mcpCallTool-request Call a tool discovered through mcpListTools; replace the server, tool name and arguments with that tool’s schema. ```json { "toolCall": { "id": "tool_call_123", "serverId": "custom:product-tools", "name": "lookup_booking", "argumentsJson": { "booking_id": "BK-123" } } } ``` ## Responses ### 200 — Tool executed Content type: `application/json` Result of executing a tool through an MCP server. **requestId** `string` Correlation identifier for the MCP tool execution request. **toolCall** `any` Tool call with its arguments, execution state, and available result. status/result\_json/executed\_at filled All of: Variant 1: A single structured tool call emitted by the model [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat) is the client answer window. Expiry ends that wait and rejects late results; the timeout policy determines the outcome. Model reference: [ToolCall](/api/models/schema-1it6mqsqoo#response). **id** `string` Provider-supplied call id. **name** `string` Name of the tool or function being invoked. **argumentsJson** `map[string, any]` JSON object payload. **status** `any` Execution status recorded for the tool call. Execution state of a tool call, including approval waiting and terminal outcomes. The terminal outcomes are COMPLETED, FAILED, CANCELLED and TIMED\_OUT; inspect ToolCall.end\_reason for why a call ended rather than treating the reason as another status. Use a listed execution status. The end reason explains the outcome separately from the status.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_EXECUTION_STATUS_PENDING` | 0 | Canonical | The tool call is waiting to begin execution. | | `TOOL_EXECUTION_STATUS_EXECUTING` | 1 | Canonical | The tool call is currently executing. | | `TOOL_EXECUTION_STATUS_COMPLETED` | 2 | Canonical | The tool call completed successfully. This is a terminal outcome. | | `TOOL_EXECUTION_STATUS_FAILED` | 3 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. | | `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 4 | Canonical | The tool call is waiting for approval before it can execute. | | `TOOL_EXECUTION_STATUS_CANCELLED` | 5 | Canonical | The tool call was cancelled before normal completion. | | `TOOL_EXECUTION_STATUS_TIMED_OUT` | 6 | Canonical | Tool execution ended because its time limit elapsed. |
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_EXECUTION_STATUS_PENDING`, `TOOL_EXECUTION_STATUS_EXECUTING`, `TOOL_EXECUTION_STATUS_COMPLETED`, `TOOL_EXECUTION_STATUS_FAILED`, `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, `TOOL_EXECUTION_STATUS_CANCELLED`, `TOOL_EXECUTION_STATUS_TIMED_OUT` Variant 2: Type: `integer(int32)` **resultJson** `map[string, any]` Tool execution result (object). **executedAt** `string(date-time)` Time when the tool execution was recorded. **serverId** `string` Which server provides this tool (for MCP tools). **isClientTool** `boolean` True if this is a client-side tool handled by client. **description** `string` Tool description captured from the resolved tool definition when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. **parametersJsonSchema** `map[string, any]` JSON Schema describing the tool’s input arguments. **requiresApprovalAt** `string(date-time)` Deadline for an approval decision, calculated from the effective approval timeout. This is not the time the call began waiting. An approval received after the deadline is rejected. **approvedAt** `string(date-time)` Timestamp when approval decision was recorded (if approved/rejected) **approvedBy** `string` Identifier of the approver (user id, email, or actor key) **executionDuration** `string` End-to-end execution duration once terminal (includes tool server latency or client-side time) Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **endReason** `string` Why this call ended, in one short phrase — "approval rejected", "approval timeout", or the underlying error. Set only once `status` is terminal, and empty on a clean COMPLETED. Use this reason to distinguish a rejection from a failure without parsing the tool result. **clientToolDeadlineAt** `string(date-time)` Deadline by which the client must submit a result for this call, stamped when the call is dispatched to a caller. **executionTimeMs** `string(int64)` Reported duration of MCP tool execution, in milliseconds. Pattern: ^-?\d+$ #### conversations-mcpCallTool-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "requestId": "example_123", "toolCall": { "id": "example_123", "name": "example", "argumentsJson": { "example": "value" }, "status": "TOOL_EXECUTION_STATUS_PENDING", "resultJson": { "example": "value" }, "executedAt": "2026-09-16T12:00:00Z", "serverId": "example_123", "isClientTool": true, "description": "example", "parametersJsonSchema": { "example": "value" }, "requiresApprovalAt": "2026-09-16T12:00:00Z", "approvedAt": "2026-09-16T12:00:00Z", "approvedBy": "example", "executionDuration": "1s", "endReason": "example", "clientToolDeadlineAt": "2026-09-16T12:00:00Z" }, "executionTimeMs": 1 } ``` Document ID: `DOC-MA-conversations-api-mcpCallTool`. [Section identities and revisions](/documentation-manifest.json). - Execute an MCP tool: `DOC-MA-conversations-api-mcpCallTool#overview` - Request: `DOC-MA-conversations-api-mcpCallTool#request` - Responses: `DOC-MA-conversations-api-mcpCallTool#responses` --- # Get an MCP prompt template URL: https://docs.travila.ai/api/conversations/mcp-get-prompt **POST** `/api/v1/llm/mcp-get-prompt` This operation is not yet available. It currently returns an empty response without retrieving a resource or prompt. Do not treat the response as a successful lookup or rendering. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an assistant that researches the web](/integrations/tools-connections) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for retrieving an MCP prompt template by name. **serverId** `string` Identifier of the MCP server to query. **name** `string` Name of the MCP prompt template to retrieve. **sessionId** `string` Session routing hint for the MCP operation. #### conversations-mcpGetPrompt-request Illustrative request shape; the current handler returns an empty result without fetching resources or prompts. ```json { "serverId": "custom:product-tools", "name": "travel-summary" } ``` ## Responses ### 200 — Empty response; prompt retrieval is not yet available Content type: `application/json` Result of retrieving an MCP prompt template by name. **prompt** `any` Prompt template returned by the MCP server. All of: Variant 1: A prompt definition exposed by an MCP server Model reference: [PromptDefinition](/api/models/schema-ou94n9qv48#response). **name** `string` Name identifying the prompt template on the MCP server. **title** `string` Display title of the MCP prompt template. **description** `string` Description of the MCP prompt template’s purpose. **parameters** `array[llm_v1_common_v1_PromptParameter]` Parameter definitions accepted by the prompt template. A parameter used by a prompt template Model reference: [PromptParameter](/api/models/schema-ohoj3j73c1#response). **name** `string` Name used to bind a value to this prompt-template parameter. **description** `string` Explanation of the value expected for this prompt parameter. **type** `string` Free-form type hint, e.g. "string", "number" **required** `boolean` Whether the prompt parameter must be supplied by the caller. **template** `string` Template string; clients may render with parameters. #### conversations-mcpGetPrompt-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "prompt": { "name": "example", "title": "example", "description": "example", "parameters": [ { "name": "example", "description": "example", "type": "example", "required": true } ], "template": "example" } } ``` Document ID: `DOC-MA-conversations-api-mcpGetPrompt`. [Section identities and revisions](/documentation-manifest.json). - Get an MCP prompt template: `DOC-MA-conversations-api-mcpGetPrompt#overview` - Request: `DOC-MA-conversations-api-mcpGetPrompt#request` - Responses: `DOC-MA-conversations-api-mcpGetPrompt#responses` --- # Get detailed MCP server info URL: https://docs.travila.ai/api/conversations/mcp-get-server-info **POST** `/api/v1/llm/mcp-get-server-info` Returns server information for custom servers. Requests for other server kinds currently return an empty response; use tool discovery to inspect the available tools. This response does not confirm current connectivity. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for reading connection and capability information for an MCP server. **serverId** `string` Identifier of the MCP server to query. #### conversations-mcpGetServerInfo-request Inspect a registered custom MCP server; replace the example server ID. ```json { "serverId": "custom:product-tools" } ``` ## Responses ### 200 — Server info returned Content type: `application/json` Result of reading connection and capability information for an MCP server. **serverInfo** `any` Connection and capability information for the selected MCP server. All of: Variant 1: Detailed server information Model reference: [MCPServerInfo](/api/models/schema-1ipatl4liq#response). **serverId** `string` Identifier of the MCP server associated with the operation or tool. **name** `string` Display name of the MCP server. **version** `string` Version of the resource represented by this message. **capabilities** `array[string]` Capabilities reported by the MCP server. Type: `string` **metadata** `map[string, string]` Additional attributes associated with the resource. **status** `any` Current connection status reported for the MCP server. Current connection or discovery condition reported for an MCP server.
| Value | No. | Form | Meaning | |---|---|---|---| | `MCP_SERVER_CONNECTION_STATUS_CONNECTED` | 0 | Canonical | A connection to the MCP server is established. | | `MCP_SERVER_CONNECTION_STATUS_DISCONNECTED` | 1 | Canonical | There is no active connection to the MCP server. | | `MCP_SERVER_CONNECTION_STATUS_ERROR` | 2 | Canonical | A connection or discovery attempt encountered an error. | | `MCP_SERVER_CONNECTION_STATUS_DISCOVERING` | 3 | Canonical | The platform is discovering the server's available capabilities. |
Exactly one of: Variant 1: Type: `string` Enum: `MCP_SERVER_CONNECTION_STATUS_CONNECTED`, `MCP_SERVER_CONNECTION_STATUS_DISCONNECTED`, `MCP_SERVER_CONNECTION_STATUS_ERROR`, `MCP_SERVER_CONNECTION_STATUS_DISCOVERING` Variant 2: Type: `integer(int32)` **availableTools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions currently reported by the MCP server. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **kind** `any` Ownership category of the MCP server definition. Ownership and connection category of an MCP server available to the platform. INTERNAL servers use fully qualified server IDs; BUILT\_IN IDs start with `built-in:`, CUSTOM with `custom:`, and INTEGRATION with `pipedream:`. EXTERNAL identifies existing externally configured servers with unprefixed IDs. Use this category when displaying or filtering the server catalog.
| Value | No. | Form | Meaning | |---|---|---|---| | `MCP_SERVER_KIND_INTERNAL` | 0 | Canonical | See meaning below. | | `MCP_SERVER_KIND_BUILT_IN` | 1 | Canonical | See meaning below. | | `MCP_SERVER_KIND_CUSTOM` | 2 | Canonical | See meaning below. | | `MCP_SERVER_KIND_EXTERNAL` | 3 | Canonical | An existing externally configured server. New entries are not supported in this category; it does not designate a new tenant registration. | | `MCP_SERVER_KIND_INTEGRATION` | 4 | Canonical | See meaning below. | **`MCP_SERVER_KIND_INTERNAL`** A server compiled into the deployment and dispatched in-process. Compiled into the deployment and dispatched in-process. No vendor cost. **`MCP_SERVER_KIND_BUILT_IN`** A platform-owned catalog server invoked with platform-held vendor credentials. Platform-owned catalog entry, called with a platform-held vendor key and no end-user identity. Metered per call. **`MCP_SERVER_KIND_CUSTOM`** A tenant-registered server invoked with the tenant's credentials. Registered by a tenant, called with the tenant's own credential. **`MCP_SERVER_KIND_INTEGRATION`** An account-connected integration reached through Pipedream Connect. Account-bound integration reached through Pipedream Connect.
Exactly one of: Variant 1: Type: `string` Enum: `MCP_SERVER_KIND_INTERNAL`, `MCP_SERVER_KIND_BUILT_IN`, `MCP_SERVER_KIND_CUSTOM`, `MCP_SERVER_KIND_EXTERNAL`, `MCP_SERVER_KIND_INTEGRATION` Variant 2: Type: `integer(int32)` #### conversations-mcpGetServerInfo-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "serverInfo": { "serverId": "example_123", "name": "example", "version": "example", "capabilities": [ "example" ], "metadata": {}, "status": "MCP_SERVER_CONNECTION_STATUS_CONNECTED", "availableTools": [ { "name": "example", "description": "example", "serverId": "example_123", "tags": [ "example" ], "documentationUrl": "https://example.com/resource" } ], "kind": "MCP_SERVER_KIND_INTERNAL" } } ``` Document ID: `DOC-MA-conversations-api-mcpGetServerInfo`. [Section identities and revisions](/documentation-manifest.json). - Get detailed MCP server info: `DOC-MA-conversations-api-mcpGetServerInfo#overview` - Request: `DOC-MA-conversations-api-mcpGetServerInfo#request` - Responses: `DOC-MA-conversations-api-mcpGetServerInfo#responses` --- # List available MCP servers URL: https://docs.travila.ai/api/conversations/mcp-list-available-servers **POST** `/api/v1/llm/mcp-list-available-servers` Returns the discovered availability of configured MCP servers. ### Built-in catalog entries The catalog includes `built-in:tavily`. Travila supplies the vendor credential for this catalog entry; you do not need your own Tavily key. A catalog entry appearing in this list is not a setting that attaches its tools to your conversation. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Let a customer navigate your app through chat](/managed-agents/delegation-approvals/build-agent-with-tools) · [Build an assistant that researches the web](/integrations/tools-connections) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for listing MCP servers available through the gateway. **includeDisconnected** `boolean` Whether the server listing should include disconnected MCP servers. **kinds** `array[any]` Restrict the listing to these ownership classes. Empty selects every class. Ownership and connection category of an MCP server available to the platform. INTERNAL servers use fully qualified server IDs; BUILT\_IN IDs start with `built-in:`, CUSTOM with `custom:`, and INTEGRATION with `pipedream:`. EXTERNAL identifies existing externally configured servers with unprefixed IDs. Use this category when displaying or filtering the server catalog. Ownership and connection category of an MCP server available to the platform. INTERNAL servers use fully qualified server IDs; BUILT\_IN IDs start with `built-in:`, CUSTOM with `custom:`, and INTEGRATION with `pipedream:`. EXTERNAL identifies existing externally configured servers with unprefixed IDs. Use this category when displaying or filtering the server catalog.
| Value | No. | Form | Meaning | |---|---|---|---| | `MCP_SERVER_KIND_INTERNAL` | 0 | Canonical | See meaning below. | | `MCP_SERVER_KIND_BUILT_IN` | 1 | Canonical | See meaning below. | | `MCP_SERVER_KIND_CUSTOM` | 2 | Canonical | See meaning below. | | `MCP_SERVER_KIND_EXTERNAL` | 3 | Canonical | An existing externally configured server. New entries are not supported in this category; it does not designate a new tenant registration. | | `MCP_SERVER_KIND_INTEGRATION` | 4 | Canonical | See meaning below. | **`MCP_SERVER_KIND_INTERNAL`** A server compiled into the deployment and dispatched in-process. Compiled into the deployment and dispatched in-process. No vendor cost. **`MCP_SERVER_KIND_BUILT_IN`** A platform-owned catalog server invoked with platform-held vendor credentials. Platform-owned catalog entry, called with a platform-held vendor key and no end-user identity. Metered per call. **`MCP_SERVER_KIND_CUSTOM`** A tenant-registered server invoked with the tenant's credentials. Registered by a tenant, called with the tenant's own credential. **`MCP_SERVER_KIND_INTEGRATION`** An account-connected integration reached through Pipedream Connect. Account-bound integration reached through Pipedream Connect.
Exactly one of: Variant 1: Type: `string` Enum: `MCP_SERVER_KIND_INTERNAL`, `MCP_SERVER_KIND_BUILT_IN`, `MCP_SERVER_KIND_CUSTOM`, `MCP_SERVER_KIND_EXTERNAL`, `MCP_SERVER_KIND_INTEGRATION` Variant 2: Type: `integer(int32)` #### conversations-mcpListAvailableServers-request Discover servers available in the authenticated scope; no body filters are supplied. ```json {} ``` ## Responses ### 200 — Server list returned Content type: `application/json` Result of listing the MCP servers available through the gateway. **servers** `array[llm_v1_common_v1_MCPServerStatus]` Connection status of each MCP server included in the listing. Status information returned for an MCP server. Model reference: [MCPServerStatus](/api/models/schema-ou7clc4l5s#response). **serverId** `string` Identifier of the MCP server whose status is reported. **name** `string` Display name of the MCP server. **status** `any` Current connection status reported for the MCP server. Current connection or discovery condition reported for an MCP server.
| Value | No. | Form | Meaning | |---|---|---|---| | `MCP_SERVER_CONNECTION_STATUS_CONNECTED` | 0 | Canonical | A connection to the MCP server is established. | | `MCP_SERVER_CONNECTION_STATUS_DISCONNECTED` | 1 | Canonical | There is no active connection to the MCP server. | | `MCP_SERVER_CONNECTION_STATUS_ERROR` | 2 | Canonical | A connection or discovery attempt encountered an error. | | `MCP_SERVER_CONNECTION_STATUS_DISCOVERING` | 3 | Canonical | The platform is discovering the server's available capabilities. |
Exactly one of: Variant 1: Type: `string` Enum: `MCP_SERVER_CONNECTION_STATUS_CONNECTED`, `MCP_SERVER_CONNECTION_STATUS_DISCONNECTED`, `MCP_SERVER_CONNECTION_STATUS_ERROR`, `MCP_SERVER_CONNECTION_STATUS_DISCOVERING` Variant 2: Type: `integer(int32)` **toolsDiscovered** `string(int64)` Number of tool definitions found during the last discovery. Pattern: ^-?\d+$ **lastDiscoveryDuration** `string` Elapsed duration of the last MCP tool discovery. Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **lastError** `string` Most recent error reported while contacting the MCP server. **lastDiscoveryTime** `string(date-time)` Time when MCP tool discovery last ran. **kind** `any` Ownership of this server. Populated by ListAvailableServers for every source it merges. Ownership and connection category of an MCP server available to the platform. INTERNAL servers use fully qualified server IDs; BUILT\_IN IDs start with `built-in:`, CUSTOM with `custom:`, and INTEGRATION with `pipedream:`. EXTERNAL identifies existing externally configured servers with unprefixed IDs. Use this category when displaying or filtering the server catalog.
| Value | No. | Form | Meaning | |---|---|---|---| | `MCP_SERVER_KIND_INTERNAL` | 0 | Canonical | See meaning below. | | `MCP_SERVER_KIND_BUILT_IN` | 1 | Canonical | See meaning below. | | `MCP_SERVER_KIND_CUSTOM` | 2 | Canonical | See meaning below. | | `MCP_SERVER_KIND_EXTERNAL` | 3 | Canonical | An existing externally configured server. New entries are not supported in this category; it does not designate a new tenant registration. | | `MCP_SERVER_KIND_INTEGRATION` | 4 | Canonical | See meaning below. | **`MCP_SERVER_KIND_INTERNAL`** A server compiled into the deployment and dispatched in-process. Compiled into the deployment and dispatched in-process. No vendor cost. **`MCP_SERVER_KIND_BUILT_IN`** A platform-owned catalog server invoked with platform-held vendor credentials. Platform-owned catalog entry, called with a platform-held vendor key and no end-user identity. Metered per call. **`MCP_SERVER_KIND_CUSTOM`** A tenant-registered server invoked with the tenant's credentials. Registered by a tenant, called with the tenant's own credential. **`MCP_SERVER_KIND_INTEGRATION`** An account-connected integration reached through Pipedream Connect. Account-bound integration reached through Pipedream Connect.
Exactly one of: Variant 1: Type: `string` Enum: `MCP_SERVER_KIND_INTERNAL`, `MCP_SERVER_KIND_BUILT_IN`, `MCP_SERVER_KIND_CUSTOM`, `MCP_SERVER_KIND_EXTERNAL`, `MCP_SERVER_KIND_INTEGRATION` Variant 2: Type: `integer(int32)` #### conversations-mcpListAvailableServers-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "servers": [ { "serverId": "example_123", "name": "example", "status": "MCP_SERVER_CONNECTION_STATUS_CONNECTED", "toolsDiscovered": 1, "lastDiscoveryDuration": "1s", "lastError": "example", "lastDiscoveryTime": "2026-09-16T12:00:00Z", "kind": "MCP_SERVER_KIND_INTERNAL" } ] } ``` Document ID: `DOC-MA-conversations-api-mcpListAvailableServers`. [Section identities and revisions](/documentation-manifest.json). - List available MCP servers: `DOC-MA-conversations-api-mcpListAvailableServers#overview` - Request: `DOC-MA-conversations-api-mcpListAvailableServers#request` - Responses: `DOC-MA-conversations-api-mcpListAvailableServers#responses` --- # List MCP prompt templates URL: https://docs.travila.ai/api/conversations/mcp-list-prompts **POST** `/api/v1/llm/mcp-list-prompts` This operation is not yet available. It currently returns an empty response without retrieving a resource or prompt. Do not treat the response as a successful lookup or rendering. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an assistant that researches the web](/integrations/tools-connections) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for listing prompts from the selected MCP server. **serverId** `string` Identifier of the MCP server to query. **nameFilter** `string` Filter applied to the names of discovered MCP prompts. **sessionId** `string` Session routing hint for the MCP operation. #### conversations-mcpListPrompts-request Illustrative request shape; the current handler returns an empty result without fetching resources or prompts. ```json { "serverId": "custom:product-tools" } ``` ## Responses ### 200 — Empty response; prompt listing is not yet available Content type: `application/json` Result of discovering prompt templates exposed by an MCP server. **prompts** `array[llm_v1_common_v1_PromptDefinition]` Prompt templates returned by MCP discovery. A prompt definition exposed by an MCP server Model reference: [PromptDefinition](/api/models/schema-ou94n9qv48#response). **name** `string` Name identifying the prompt template on the MCP server. **title** `string` Display title of the MCP prompt template. **description** `string` Description of the MCP prompt template’s purpose. **parameters** `array[llm_v1_common_v1_PromptParameter]` Parameter definitions accepted by the prompt template. A parameter used by a prompt template Model reference: [PromptParameter](/api/models/schema-ohoj3j73c1#response). **name** `string` Name used to bind a value to this prompt-template parameter. **description** `string` Explanation of the value expected for this prompt parameter. **type** `string` Free-form type hint, e.g. "string", "number" **required** `boolean` Whether the prompt parameter must be supplied by the caller. **template** `string` Template string; clients may render with parameters. **totalCount** `string(int64)` Number of entries reported by the MCP operation. Pattern: ^-?\d+$ #### conversations-mcpListPrompts-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "prompts": [ { "name": "example", "title": "example", "description": "example", "parameters": [ { "name": "example", "description": "example", "type": "example", "required": true } ], "template": "example" } ], "totalCount": 1 } ``` Document ID: `DOC-MA-conversations-api-mcpListPrompts`. [Section identities and revisions](/documentation-manifest.json). - List MCP prompt templates: `DOC-MA-conversations-api-mcpListPrompts#overview` - Request: `DOC-MA-conversations-api-mcpListPrompts#request` - Responses: `DOC-MA-conversations-api-mcpListPrompts#responses` --- # List MCP resources URL: https://docs.travila.ai/api/conversations/mcp-list-resources **POST** `/api/v1/llm/mcp-list-resources` This operation is not yet available. It currently returns an empty response without retrieving a resource or prompt. Do not treat the response as a successful lookup or rendering. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an assistant that researches the web](/integrations/tools-connections) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for listing resources from the selected MCP server. **serverId** `string` Identifier of the MCP server to query. **uriFilter** `string` Filter applied to the URIs of discovered MCP resources. **sessionId** `string` Session routing hint for the MCP operation. #### conversations-mcpListResources-request Illustrative request shape; the current handler returns an empty result without fetching resources or prompts. ```json { "serverId": "custom:product-tools" } ``` ## Responses ### 200 — Empty response; resource listing is not yet available Content type: `application/json` Result of discovering resources exposed by an MCP server. **resources** `array[llm_v1_common_v1_Resource]` Resource descriptions returned by MCP discovery. A resource exposed by an MCP server Model reference: [Resource](/api/models/schema-pbf83hf239#response). **uri** `string` Canonical URI for the resource. **title** `string` Display title of the MCP resource. **description** `string` Description of the content available from the MCP resource. **mimeType** `string` Media type of the content exposed by the MCP resource. **content** `array[llm_v1_common_v1_ContentPart]` Optional embedded content. Content parts composing a message, using a flattened structure for JSON compatibility. The `type` identifies how the content is represented; only defined content types are accepted. Model reference: [ContentPart](/api/models/schema-1hqi9r2bhh#response). **type** `any` Kind of content carried by this message part. Discriminator identifying which content representation a message part carries.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTENT_PART_TYPE_TEXT` | 0 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_URL` | 1 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_BASE64` | 2 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_ID` | 3 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_PATH` | 4 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_URL` | 5 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_DATA_URL` | 6 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_AUDIO_BASE64` | 7 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_REASONING` | 8 | Canonical | See meaning below. | **`CONTENT_PART_TYPE_TEXT`** Plain text carried by the content part. Plain text content **`CONTENT_PART_TYPE_IMAGE_URL`** An image supplied through a remote URL. Remote image URL **`CONTENT_PART_TYPE_IMAGE_BASE64`** An image supplied as base64-encoded bytes. Base64-encoded image data **`CONTENT_PART_TYPE_FILE_ID`** A provider file identifier or internal storage identifier resolved before generation. File ID — a provider file ID (e.g., OpenAI) OR an internal storage file ID; resolved to a signed FILE\_URL just-in-time before the model-provider request **`CONTENT_PART_TYPE_FILE_PATH`** A reference to a local file path. Local file path reference **`CONTENT_PART_TYPE_FILE_URL`** A file supplied through a public or signed URL. Public or signed file URL (e.g., PDF URL or data: URL) **`CONTENT_PART_TYPE_FILE_DATA_URL`** A file embedded in a data URL, including its media type and encoded data. data\:application/pdf;base64,... or similar **`CONTENT_PART_TYPE_AUDIO_BASE64`** Base64-encoded audio; the part metadata identifies its audio format. Base64-encoded audio (metadata.format required, e.g., wav/mp3) **`CONTENT_PART_TYPE_REASONING`** A reasoning segment returned by a model provider, when available. Reasoning/thinking content from chain-of-thought models
Exactly one of: Variant 1: Type: `string` Enum: `CONTENT_PART_TYPE_TEXT`, `CONTENT_PART_TYPE_IMAGE_URL`, `CONTENT_PART_TYPE_IMAGE_BASE64`, `CONTENT_PART_TYPE_FILE_ID`, `CONTENT_PART_TYPE_FILE_PATH`, `CONTENT_PART_TYPE_FILE_URL`, `CONTENT_PART_TYPE_FILE_DATA_URL`, `CONTENT_PART_TYPE_AUDIO_BASE64`, `CONTENT_PART_TYPE_REASONING` Variant 2: Type: `integer(int32)` **content** `string` Text content, image URL, file ID, or base64-encoded data. **metadata** `map[string, string]` Additional type-specific metadata (dimensions, mime\_type, etc.). **cachePreferred** `boolean` Hint that this part is eligible for provider prompt caching. **structuredMessage** `any` Populated on TEXT parts for structured output responses. All of: Variant 1: A structured message whose JSON payload has been validated against a declared schema. Consumers can trust that json\_payload conforms to the schema identified by schema\_name. Inspect the run outcome before treating any message as complete. Current structured metadata is attached to a text content part through [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage) can be absent. Use an object at the schema root and validate the exact final response your application consumes; server validation covers only the first model choice. For integers that your JSON client cannot represent exactly, define string-valued fields in your schema instead of converting them through floating point. Model reference: [StructuredMessage](/api/models/schema-1ho1lk4ndj#response). **jsonPayload** `map[string, any]` The validated JSON payload as a Struct (preserves types) **schemaName** `string` Schema identifier (from ResponseFormat.schema\_name) **healed** `boolean` Whether response healing is reported for this structured message. Currently returned as false. **annotations** `map[string, string]` Optional annotations/metadata. **lastModified** `string(date-time)` Time when this resource was last modified. **totalCount** `string(int64)` Number of entries reported by the MCP operation. Pattern: ^-?\d+$ #### conversations-mcpListResources-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "resources": [ { "uri": "https://example.com/resource", "title": "example", "description": "example", "mimeType": "example", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Example text", "cachePreferred": true } ], "annotations": {}, "lastModified": "2026-09-16T12:00:00Z" } ], "totalCount": 1 } ``` Document ID: `DOC-MA-conversations-api-mcpListResources`. [Section identities and revisions](/documentation-manifest.json). - List MCP resources: `DOC-MA-conversations-api-mcpListResources#overview` - Request: `DOC-MA-conversations-api-mcpListResources#request` - Responses: `DOC-MA-conversations-api-mcpListResources#responses` --- # List available MCP tools URL: https://docs.travila.ai/api/conversations/mcp-list-tools **POST** `/api/v1/llm/mcp-list-tools` Returns tools discovered across the selected MCP servers. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an assistant that researches the web](/integrations/tools-connections) · [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps) · [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for discovering tools from selected MCP servers. **servers** `array[llm_v1_common_v1_MCPServerReferenceInput]` MCP servers to inspect; an empty list requests tools from all available servers. MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#request). **serverId** `string` **required** ID of pre-configured MCP server (e.g., "github", "filesystem"). Minimum length: 1 **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **sessionId** `string` Optional session routing hint for the MCP operation. #### conversations-mcpListTools-request List tools exposed by a registered custom MCP server; replace the server ID. ```json { "servers": [ { "serverId": "custom:product-tools", "enabled": true } ] } ``` #### cookbook-integrations-tools-connections-custom-mcp-servers-04-request Guide request for Inspect the names before setting filters or approvals. Replace example resource identifiers with your own authorized values. ```json { "servers": [ { "serverId": "custom:firecrawl", "enabled": true } ] } ``` ## Responses ### 200 — Tools listed Content type: `application/json` Result of discovering tools exposed by MCP servers. **tools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions returned by MCP discovery. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **totalCount** `string(int64)` Number of entries reported by the MCP operation. Pattern: ^-?\d+$ #### conversations-mcpListTools-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "tools": [ { "name": "example", "description": "example", "parametersJsonSchema": { "example": "value" }, "metadata": {}, "serverId": "example_123", "tags": [ "example" ], "documentationUrl": "https://example.com/resource", "outputJsonSchema": { "example": "value" } } ], "totalCount": 1 } ``` Document ID: `DOC-MA-conversations-api-mcpListTools`. [Section identities and revisions](/documentation-manifest.json). - List available MCP tools: `DOC-MA-conversations-api-mcpListTools#overview` - Request: `DOC-MA-conversations-api-mcpListTools#request` - Responses: `DOC-MA-conversations-api-mcpListTools#responses` --- # Read an MCP resource URL: https://docs.travila.ai/api/conversations/mcp-read-resource **POST** `/api/v1/llm/mcp-read-resource` This operation is not yet available. It currently returns an empty response without retrieving a resource or prompt. Do not treat the response as a successful lookup or rendering. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an assistant that researches the web](/integrations/tools-connections) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for reading an MCP resource by URI. **serverId** `string` Identifier of the MCP server to query. **uri** `string` URI identifying the MCP resource to read. **sessionId** `string` Session routing hint for the MCP operation. #### conversations-mcpReadResource-request Illustrative request shape; the current handler returns an empty result without fetching resources or prompts. ```json { "serverId": "custom:product-tools", "uri": "resource://bookings/BK-123" } ``` ## Responses ### 200 — Empty response; resource retrieval is not yet available Content type: `application/json` Result of reading an MCP resource by URI. **resource** `any` MCP resource with content when provided by the server. All of: Variant 1: A resource exposed by an MCP server Model reference: [Resource](/api/models/schema-pbf83hf239#response). **uri** `string` Canonical URI for the resource. **title** `string` Display title of the MCP resource. **description** `string` Description of the content available from the MCP resource. **mimeType** `string` Media type of the content exposed by the MCP resource. **content** `array[llm_v1_common_v1_ContentPart]` Optional embedded content. Content parts composing a message, using a flattened structure for JSON compatibility. The `type` identifies how the content is represented; only defined content types are accepted. Model reference: [ContentPart](/api/models/schema-1hqi9r2bhh#response). **type** `any` Kind of content carried by this message part. Discriminator identifying which content representation a message part carries.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTENT_PART_TYPE_TEXT` | 0 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_URL` | 1 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_BASE64` | 2 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_ID` | 3 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_PATH` | 4 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_URL` | 5 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_DATA_URL` | 6 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_AUDIO_BASE64` | 7 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_REASONING` | 8 | Canonical | See meaning below. | **`CONTENT_PART_TYPE_TEXT`** Plain text carried by the content part. Plain text content **`CONTENT_PART_TYPE_IMAGE_URL`** An image supplied through a remote URL. Remote image URL **`CONTENT_PART_TYPE_IMAGE_BASE64`** An image supplied as base64-encoded bytes. Base64-encoded image data **`CONTENT_PART_TYPE_FILE_ID`** A provider file identifier or internal storage identifier resolved before generation. File ID — a provider file ID (e.g., OpenAI) OR an internal storage file ID; resolved to a signed FILE\_URL just-in-time before the model-provider request **`CONTENT_PART_TYPE_FILE_PATH`** A reference to a local file path. Local file path reference **`CONTENT_PART_TYPE_FILE_URL`** A file supplied through a public or signed URL. Public or signed file URL (e.g., PDF URL or data: URL) **`CONTENT_PART_TYPE_FILE_DATA_URL`** A file embedded in a data URL, including its media type and encoded data. data\:application/pdf;base64,... or similar **`CONTENT_PART_TYPE_AUDIO_BASE64`** Base64-encoded audio; the part metadata identifies its audio format. Base64-encoded audio (metadata.format required, e.g., wav/mp3) **`CONTENT_PART_TYPE_REASONING`** A reasoning segment returned by a model provider, when available. Reasoning/thinking content from chain-of-thought models
Exactly one of: Variant 1: Type: `string` Enum: `CONTENT_PART_TYPE_TEXT`, `CONTENT_PART_TYPE_IMAGE_URL`, `CONTENT_PART_TYPE_IMAGE_BASE64`, `CONTENT_PART_TYPE_FILE_ID`, `CONTENT_PART_TYPE_FILE_PATH`, `CONTENT_PART_TYPE_FILE_URL`, `CONTENT_PART_TYPE_FILE_DATA_URL`, `CONTENT_PART_TYPE_AUDIO_BASE64`, `CONTENT_PART_TYPE_REASONING` Variant 2: Type: `integer(int32)` **content** `string` Text content, image URL, file ID, or base64-encoded data. **metadata** `map[string, string]` Additional type-specific metadata (dimensions, mime\_type, etc.). **cachePreferred** `boolean` Hint that this part is eligible for provider prompt caching. **structuredMessage** `any` Populated on TEXT parts for structured output responses. All of: Variant 1: A structured message whose JSON payload has been validated against a declared schema. Consumers can trust that json\_payload conforms to the schema identified by schema\_name. Inspect the run outcome before treating any message as complete. Current structured metadata is attached to a text content part through [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage) can be absent. Use an object at the schema root and validate the exact final response your application consumes; server validation covers only the first model choice. For integers that your JSON client cannot represent exactly, define string-valued fields in your schema instead of converting them through floating point. Model reference: [StructuredMessage](/api/models/schema-1ho1lk4ndj#response). **jsonPayload** `map[string, any]` The validated JSON payload as a Struct (preserves types) **schemaName** `string` Schema identifier (from ResponseFormat.schema\_name) **healed** `boolean` Whether response healing is reported for this structured message. Currently returned as false. **annotations** `map[string, string]` Optional annotations/metadata. **lastModified** `string(date-time)` Time when this resource was last modified. #### conversations-mcpReadResource-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "resource": { "uri": "https://example.com/resource", "title": "example", "description": "example", "mimeType": "example", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Example text", "cachePreferred": true } ], "annotations": {}, "lastModified": "2026-09-16T12:00:00Z" } } ``` Document ID: `DOC-MA-conversations-api-mcpReadResource`. [Section identities and revisions](/documentation-manifest.json). - Read an MCP resource: `DOC-MA-conversations-api-mcpReadResource#overview` - Request: `DOC-MA-conversations-api-mcpReadResource#request` - Responses: `DOC-MA-conversations-api-mcpReadResource#responses` --- # Mint a speech-to-text token (in progress) URL: https://docs.travila.ai/api/conversations/mint-stt-token **POST** `/api/v1/llm/stt-token` Mints a short-lived speech-to-text token using the configured Cartesia credential. The request fails when that credential is missing. The client uses this token to call the STT API directly so the backend key never reaches the client. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Add a spoken conversation to your app (Preview)](/managed-agents/voice-media) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Mint a short-lived Cartesia STT access token for the calling user. #### conversations-mintSttToken-request Request a speech-to-text token using the configured provider; no body fields are required. ```json {} ``` ## Responses ### 200 — STT token minted Content type: `application/json` Result of issuing a short-lived Cartesia speech-to-text access token. **token** `string` Short-lived Cartesia speech-to-text access token. **expiresInSeconds** `string(int64)` Lifetime of the issued access token, in seconds. Pattern: ^-?\d+$ #### conversations-mintSttToken-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "token": "example", "expiresInSeconds": 1 } ``` #### cookbook-managed-agents-voice-media-index-json-02-response Illustrative response for Separate recipe: dictate a draft without starting a voice agent. Replace example resource identifiers with your own authorized values. ```json { "token": "stt_eph_...", "expiresInSeconds": 600 } ``` Document ID: `DOC-MA-conversations-api-mintSttToken`. [Section identities and revisions](/documentation-manifest.json). - Mint a speech-to-text token (in progress): `DOC-MA-conversations-api-mintSttToken#overview` - Request: `DOC-MA-conversations-api-mintSttToken#request` - Responses: `DOC-MA-conversations-api-mintSttToken#responses` --- # Rate an assistant message URL: https://docs.travila.ai/api/conversations/rate-message **POST** `/api/v1/llm/rate-message` Records the caller's rating on an assistant-generated message. One entry is stored per rater per message; re-rating replaces only the caller's previous entry. Serialize re-rating and withdrawal actions and reconcile stored state: uniqueness does not guarantee ordering against a delayed request or analytics event. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Collect message feedback](/insights/evaluation/message-feedback) · [Feedback and score attribution](/api/evals/scoring) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Rate an assistant message in a thread. The rater is derived server-side from the verified request headers — never supplied by the client body. For THUMB feedback, thumb\_up supplies the choice and rating must be zero or omitted. For SCALE feedback, rating must be from 1 through 10. **conversationKey** `string` **required** Identifier of the conversation thread. Minimum length: 1 **messageSequence** `string(int64)` **required** Per-conversation sequence number of the assistant-generated message to rate. Pattern: ^-?\d+$ **kind** `any` **required** Rating representation used to interpret the thumb or scale value. Value scale used to interpret recorded feedback.
| Value | No. | Form | Meaning | |---|---|---|---| | `FEEDBACK_KIND_THUMB` | 0 | Canonical | See meaning below. | | `FEEDBACK_KIND_SCALE` | 1 | Canonical | See meaning below. | **`FEEDBACK_KIND_THUMB`** Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. binary thumbs up / down **`FEEDBACK_KIND_SCALE`** Feedback expressed as an integer rating from 1 through 10. 1-10 integer scale
Exactly one of: Variant 1: Type: `string` Enum: `FEEDBACK_KIND_THUMB`, `FEEDBACK_KIND_SCALE` Variant 2: Type: `integer(int32)` Enum: `0`, `1` **thumbUp** `boolean` Positive when true and negative when false; used for THUMB feedback. **rating** `string(int64)` Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent. Pattern: ^-?\d+$ **reason** `string` Optional explanation for the rating. Maximum length: 1000 #### conversations-rateMessage-request Give an existing assistant message a positive thumb rating; replace its sequence number. ```json { "conversationKey": "example_123", "messageSequence": "1", "kind": "FEEDBACK_KIND_THUMB", "thumbUp": true } ``` #### cookbook-insights-evaluation-message-feedback-01-request Guide request for Save the user’s judgment beside the reply. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "support-chat-001", "messageSequence": 8, "kind": "FEEDBACK_KIND_THUMB", "thumbUp": true } ``` #### cookbook-insights-evaluation-message-feedback-json-02-request Guide request for Variant: use a 1–10 scale instead of thumbs. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "support-chat-001", "messageSequence": 8, "kind": "FEEDBACK_KIND_SCALE", "rating": 9, "reason": "Answered the question and cited the policy." } ``` ## Responses ### 200 — Rating recorded Content type: `application/json` Result of recording the caller’s rating on a conversation message. **ratedMessage** `any` The rated message with the full (all-rater) feedback list applied All of: Variant 1: Chat message At least one of content or tool\_calls must contain an entry; both lists may be nonempty. role must select a listed message role. Requiredness and allowed values are declared separately. Model reference: [Message](/api/models/schema-1j3dcf7kvu#response). **role** `any` Role of the participant that produced the chat message. Participant role attached to a conversation message and forwarded in model context.
| Value | No. | Form | Meaning | |---|---|---|---| | `ROLE_SYSTEM` | 0 | Canonical | Instructions or context provided as a system message. | | `ROLE_USER` | 1 | Canonical | Input supplied by the user or customer application. | | `ROLE_ASSISTANT` | 2 | Canonical | Content produced by the assistant, including its tool-call requests. | | `ROLE_TOOL` | 3 | Canonical | A tool result supplied back to the assistant. |
Exactly one of: Variant 1: Type: `string` Enum: `ROLE_SYSTEM`, `ROLE_USER`, `ROLE_ASSISTANT`, `ROLE_TOOL` Variant 2: Type: `integer(int32)` **content** `array[llm_v1_common_v1_ContentPart]` Content parts composing the chat message. Content parts composing a message, using a flattened structure for JSON compatibility. The `type` identifies how the content is represented; only defined content types are accepted. Model reference: [ContentPart](/api/models/schema-1hqi9r2bhh#response). **type** `any` Kind of content carried by this message part. Discriminator identifying which content representation a message part carries.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTENT_PART_TYPE_TEXT` | 0 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_URL` | 1 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_BASE64` | 2 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_ID` | 3 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_PATH` | 4 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_URL` | 5 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_DATA_URL` | 6 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_AUDIO_BASE64` | 7 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_REASONING` | 8 | Canonical | See meaning below. | **`CONTENT_PART_TYPE_TEXT`** Plain text carried by the content part. Plain text content **`CONTENT_PART_TYPE_IMAGE_URL`** An image supplied through a remote URL. Remote image URL **`CONTENT_PART_TYPE_IMAGE_BASE64`** An image supplied as base64-encoded bytes. Base64-encoded image data **`CONTENT_PART_TYPE_FILE_ID`** A provider file identifier or internal storage identifier resolved before generation. File ID — a provider file ID (e.g., OpenAI) OR an internal storage file ID; resolved to a signed FILE\_URL just-in-time before the model-provider request **`CONTENT_PART_TYPE_FILE_PATH`** A reference to a local file path. Local file path reference **`CONTENT_PART_TYPE_FILE_URL`** A file supplied through a public or signed URL. Public or signed file URL (e.g., PDF URL or data: URL) **`CONTENT_PART_TYPE_FILE_DATA_URL`** A file embedded in a data URL, including its media type and encoded data. data\:application/pdf;base64,... or similar **`CONTENT_PART_TYPE_AUDIO_BASE64`** Base64-encoded audio; the part metadata identifies its audio format. Base64-encoded audio (metadata.format required, e.g., wav/mp3) **`CONTENT_PART_TYPE_REASONING`** A reasoning segment returned by a model provider, when available. Reasoning/thinking content from chain-of-thought models
Exactly one of: Variant 1: Type: `string` Enum: `CONTENT_PART_TYPE_TEXT`, `CONTENT_PART_TYPE_IMAGE_URL`, `CONTENT_PART_TYPE_IMAGE_BASE64`, `CONTENT_PART_TYPE_FILE_ID`, `CONTENT_PART_TYPE_FILE_PATH`, `CONTENT_PART_TYPE_FILE_URL`, `CONTENT_PART_TYPE_FILE_DATA_URL`, `CONTENT_PART_TYPE_AUDIO_BASE64`, `CONTENT_PART_TYPE_REASONING` Variant 2: Type: `integer(int32)` **content** `string` Text content, image URL, file ID, or base64-encoded data. **metadata** `map[string, string]` Additional type-specific metadata (dimensions, mime\_type, etc.). **cachePreferred** `boolean` Hint that this part is eligible for provider prompt caching. **structuredMessage** `any` Populated on TEXT parts for structured output responses. All of: Variant 1: A structured message whose JSON payload has been validated against a declared schema. Consumers can trust that json\_payload conforms to the schema identified by schema\_name. Inspect the run outcome before treating any message as complete. Current structured metadata is attached to a text content part through [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage) can be absent. Use an object at the schema root and validate the exact final response your application consumes; server validation covers only the first model choice. For integers that your JSON client cannot represent exactly, define string-valued fields in your schema instead of converting them through floating point. Model reference: [StructuredMessage](/api/models/schema-1ho1lk4ndj#response). **jsonPayload** `map[string, any]` The validated JSON payload as a Struct (preserves types) **schemaName** `string` Schema identifier (from ResponseFormat.schema\_name) **healed** `boolean` Whether response healing is reported for this structured message. Currently returned as false. **toolCalls** `array[llm_v1_common_v1_ToolCall]` Assistant-to-tool invocations. A single structured tool call emitted by the model [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat) is the client answer window. Expiry ends that wait and rejects late results; the timeout policy determines the outcome. Model reference: [ToolCall](/api/models/schema-1it6mqsqoo#response). **id** `string` Provider-supplied call id. **name** `string` Name of the tool or function being invoked. **argumentsJson** `map[string, any]` JSON object payload. **status** `any` Execution status recorded for the tool call. Execution state of a tool call, including approval waiting and terminal outcomes. The terminal outcomes are COMPLETED, FAILED, CANCELLED and TIMED\_OUT; inspect ToolCall.end\_reason for why a call ended rather than treating the reason as another status. Use a listed execution status. The end reason explains the outcome separately from the status.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_EXECUTION_STATUS_PENDING` | 0 | Canonical | The tool call is waiting to begin execution. | | `TOOL_EXECUTION_STATUS_EXECUTING` | 1 | Canonical | The tool call is currently executing. | | `TOOL_EXECUTION_STATUS_COMPLETED` | 2 | Canonical | The tool call completed successfully. This is a terminal outcome. | | `TOOL_EXECUTION_STATUS_FAILED` | 3 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. | | `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 4 | Canonical | The tool call is waiting for approval before it can execute. | | `TOOL_EXECUTION_STATUS_CANCELLED` | 5 | Canonical | The tool call was cancelled before normal completion. | | `TOOL_EXECUTION_STATUS_TIMED_OUT` | 6 | Canonical | Tool execution ended because its time limit elapsed. |
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_EXECUTION_STATUS_PENDING`, `TOOL_EXECUTION_STATUS_EXECUTING`, `TOOL_EXECUTION_STATUS_COMPLETED`, `TOOL_EXECUTION_STATUS_FAILED`, `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, `TOOL_EXECUTION_STATUS_CANCELLED`, `TOOL_EXECUTION_STATUS_TIMED_OUT` Variant 2: Type: `integer(int32)` **resultJson** `map[string, any]` Tool execution result (object). **executedAt** `string(date-time)` Time when the tool execution was recorded. **serverId** `string` Which server provides this tool (for MCP tools). **isClientTool** `boolean` True if this is a client-side tool handled by client. **description** `string` Tool description captured from the resolved tool definition when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. **parametersJsonSchema** `map[string, any]` JSON Schema describing the tool’s input arguments. **requiresApprovalAt** `string(date-time)` Deadline for an approval decision, calculated from the effective approval timeout. This is not the time the call began waiting. An approval received after the deadline is rejected. **approvedAt** `string(date-time)` Timestamp when approval decision was recorded (if approved/rejected) **approvedBy** `string` Identifier of the approver (user id, email, or actor key) **executionDuration** `string` End-to-end execution duration once terminal (includes tool server latency or client-side time) Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **endReason** `string` Why this call ended, in one short phrase — "approval rejected", "approval timeout", or the underlying error. Set only once `status` is terminal, and empty on a clean COMPLETED. Use this reason to distinguish a rejection from a failure without parsing the tool result. **clientToolDeadlineAt** `string(date-time)` Deadline by which the client must submit a result for this call, stamped when the call is dispatched to a caller. **name** `string` Name identifying the sender of the chat message. optional sender name **timestamp** `string(date-time)` Timestamp associated with the conversation message or event. **messageId** `string` Unique message identifier. **annotations** `array[llm_v1_common_v1_Annotation]` Structured annotations (e.g., standardized web search URL citations, PDF reuse tokens) Tagged provider annotation attached to generated content, such as a citation or PDF reference. Model reference: [Annotation](/api/models/schema-1i0hjer0pd#response). **kind** `any` Selected kind; determines which submessage is populated Kind of source annotation associated with generated content.
| Value | No. | Form | Meaning | |---|---|---|---| | `ANNOTATION_KIND_URL_CITATION` | 0 | Canonical | A citation to a source identified by its URL. | | `ANNOTATION_KIND_PDF` | 1 | Canonical | An annotation identifying source content in a PDF document. |
Exactly one of: Variant 1: Type: `string` Enum: `ANNOTATION_KIND_URL_CITATION`, `ANNOTATION_KIND_PDF` Variant 2: Type: `integer(int32)` **urlCitation** `any` Submessage fields (optional); populate the one matching kind All of: Variant 1: Web source and character range cited in generated message content. Model reference: [UrlCitation](/api/models/schema-1hujls61ng#response). **url** `string` URL of the cited web page. **title** `string` Title of the web page cited by this annotation. **content** `string` Optional excerpt or snippet of the cited web page. **startIndex** `string(int64)` Character index in message content. Pattern: ^-?\d+$ **endIndex** `string(int64)` Character index in message content. Pattern: ^-?\d+$ **pdf** `any` PDF annotation identifying the parsed file and available parsing output. All of: Variant 1: Provider annotation identifying a parsed PDF and reusable parsing output. Model reference: [PdfAnnotation](/api/models/schema-1hsi58i6pb#response). **filename** `string` Optional identifying information about the original file **engine** `string` PDF parsing engine used by provider (e.g., "pdf-text", "mistral-ocr", "native") **token** `string` Opaque provider token or handle allowing reuse without re-parsing **sourceUrl** `string` Optional: original source reference (public URL or data: URL) **hash** `string` Provider-supplied hash identifying the parsed file. **content** `array[llm_v1_common_v1_ContentPart]` Optional structured content returned by provider annotations (text, image URLs, etc.) Note: This can be large; include only if you need to round-trip provider annotations. Content parts composing a message, using a flattened structure for JSON compatibility. The `type` identifies how the content is represented; only defined content types are accepted. Model reference: [ContentPart](/api/models/schema-1hqi9r2bhh#response). **type** `any` Kind of content carried by this message part. Discriminator identifying which content representation a message part carries.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTENT_PART_TYPE_TEXT` | 0 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_URL` | 1 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_BASE64` | 2 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_ID` | 3 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_PATH` | 4 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_URL` | 5 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_DATA_URL` | 6 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_AUDIO_BASE64` | 7 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_REASONING` | 8 | Canonical | See meaning below. | **`CONTENT_PART_TYPE_TEXT`** Plain text carried by the content part. Plain text content **`CONTENT_PART_TYPE_IMAGE_URL`** An image supplied through a remote URL. Remote image URL **`CONTENT_PART_TYPE_IMAGE_BASE64`** An image supplied as base64-encoded bytes. Base64-encoded image data **`CONTENT_PART_TYPE_FILE_ID`** A provider file identifier or internal storage identifier resolved before generation. File ID — a provider file ID (e.g., OpenAI) OR an internal storage file ID; resolved to a signed FILE\_URL just-in-time before the model-provider request **`CONTENT_PART_TYPE_FILE_PATH`** A reference to a local file path. Local file path reference **`CONTENT_PART_TYPE_FILE_URL`** A file supplied through a public or signed URL. Public or signed file URL (e.g., PDF URL or data: URL) **`CONTENT_PART_TYPE_FILE_DATA_URL`** A file embedded in a data URL, including its media type and encoded data. data\:application/pdf;base64,... or similar **`CONTENT_PART_TYPE_AUDIO_BASE64`** Base64-encoded audio; the part metadata identifies its audio format. Base64-encoded audio (metadata.format required, e.g., wav/mp3) **`CONTENT_PART_TYPE_REASONING`** A reasoning segment returned by a model provider, when available. Reasoning/thinking content from chain-of-thought models
Exactly one of: Variant 1: Type: `string` Enum: `CONTENT_PART_TYPE_TEXT`, `CONTENT_PART_TYPE_IMAGE_URL`, `CONTENT_PART_TYPE_IMAGE_BASE64`, `CONTENT_PART_TYPE_FILE_ID`, `CONTENT_PART_TYPE_FILE_PATH`, `CONTENT_PART_TYPE_FILE_URL`, `CONTENT_PART_TYPE_FILE_DATA_URL`, `CONTENT_PART_TYPE_AUDIO_BASE64`, `CONTENT_PART_TYPE_REASONING` Variant 2: Type: `integer(int32)` **content** `string` Text content, image URL, file ID, or base64-encoded data. **metadata** `map[string, string]` Additional type-specific metadata (dimensions, mime\_type, etc.). **cachePreferred** `boolean` Hint that this part is eligible for provider prompt caching. **structuredMessage** `any` Populated on TEXT parts for structured output responses. All of: Variant 1: A structured message whose JSON payload has been validated against a declared schema. Consumers can trust that json\_payload conforms to the schema identified by schema\_name. Inspect the run outcome before treating any message as complete. Current structured metadata is attached to a text content part through [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage) can be absent. Use an object at the schema root and validate the exact final response your application consumes; server validation covers only the first model choice. For integers that your JSON client cannot represent exactly, define string-valued fields in your schema instead of converting them through floating point. Model reference: [StructuredMessage](/api/models/schema-1ho1lk4ndj#response). **jsonPayload** `map[string, any]` The validated JSON payload as a Struct (preserves types) **schemaName** `string` Schema identifier (from ResponseFormat.schema\_name) **healed** `boolean` Whether response healing is reported for this structured message. Currently returned as false. **metadata** `map[string, string]` Provider-specific extras. **sequence** `string(int64)` Monotonic, per-conversation sequence number for stable ordering (1-based) Pattern: ^-?\d+$ **generatedBy** `string` Workflow run id or generator key that produced this message (e.g., workflow run key) **usage** `any` Token usage for this generation (populated for assistant messages) All of: Variant 1: Usage accounting Model reference: [Usage](/api/models/schema-1j1vov2uoh#response). **promptTokens** `string(int64)` Prompt-token usage reported by the model provider. Pattern: ^-?\d+$ **completionTokens** `string(int64)` Completion-token usage reported by the model provider. Pattern: ^-?\d+$ **totalTokens** `string(int64)` Total token usage reported by the model provider. Pattern: ^-?\d+$ **costEstimate** `any` Estimated cost in USD. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completionTokensDetails** `any` Breakdown of completion tokens. All of: Variant 1: Breakdown of completion-token usage. Categories are measured by different upstream tokenizers and need not sum to completion\_tokens; reasoning\_tokens can exceed completion\_tokens. One category must not be derived by subtracting the others. Model reference: [CompletionTokensDetails](/api/models/schema-1i6q4qpg72#response). **reasoningTokens** `string(int64)` Tokens used for reasoning/thinking. Pattern: ^-?\d+$ **imageTokens** `string(int64)` Completion tokens emitted as image output. Pattern: ^-?\d+$ **audioTokens** `string(int64)` Completion tokens emitted as audio output. Pattern: ^-?\d+$ **promptTokensDetails** `any` Breakdown of prompt tokens (cache). All of: Variant 1: Breakdown of prompt token usage by category (input-side cache accounting) Subset semantics: cached\_tokens and cache\_write\_tokens are a breakdown *of* prompt\_tokens, so cached\_tokens + cache\_write\_tokens \<= Usage.prompt\_tokens. Ordinary (full-rate) prompt tokens = prompt\_tokens - cached\_tokens - cache\_write\_tokens. audio\_tokens / video\_tokens are modality breakdowns of prompt\_tokens (also a subset). Model reference: [PromptTokensDetails](/api/models/schema-1ivj82m55o#response). **cachedTokens** `string(int64)` Prompt tokens served from cache (cache READ). Pattern: ^-?\d+$ **cacheWriteTokens** `string(int64)` Prompt tokens written to cache this call (cache WRITE). Pattern: ^-?\d+$ **audioTokens** `string(int64)` Prompt tokens from audio input (multimodal). Pattern: ^-?\d+$ **videoTokens** `string(int64)` Prompt tokens from video input (multimodal). Pattern: ^-?\d+$ **costDetails** `any` Breakdown of upstream provider cost (BYOK routes). All of: Variant 1: Breakdown of model-provider cost. When the customer supplies the provider key, usage.cost is zero and upstream\_inference\_cost reports the provider spend, split into prompt and completion components. Model reference: [CostDetails](/api/models/schema-1ia0h761lm#response). **upstreamInferenceCost** `any` Total upstream provider cost (USD) on BYOK routes. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferencePromptCost** `any` Upstream cost attributed to prompt tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferenceCompletionCost** `any` Upstream cost attributed to completion tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **isByok** `boolean` Whether this generation used the customer's own model-provider key. **model** `string` Model that generated this message (e.g., "anthropic/claude-sonnet-4") **generationContext** `any` Dynamic context that shaped this generation (memories, search params, turn info) All of: Variant 1: Snapshot of retrieval inputs, prompt provenance, and turn position that shaped a generated message. Model reference: [GenerationContext](/api/models/schema-1im79fphmq#response). **memories** `array[llm_v1_common_v1_MemoryReference]` Memory records captured in the generation context. A memory record retrieved and included in generation context. Model reference: [MemoryReference](/api/models/schema-1ie9a4bgk5#response). **memoryId** `string` Identifier of the retrieved memory record. **score** `any` Relevance score reported by the memory provider for this match. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **memoryText** `string` Text of the retrieved memory record. **createdAt** `string(date-time)` Time when this record was created. **updatedAt** `string(date-time)` Time when this record was last updated. **relations** `array[llm_v1_common_v1_RelationReference]` Graph relationships captured in the generation context. A graph relationship retrieved and included in generation context. Model reference: [RelationReference](/api/models/schema-1ijit8ceuv#response). **source** `string` Source entity of the memory graph relationship. **relationship** `string` Relationship label connecting the source and destination entities. **destination** `string` Destination entity of the memory graph relationship. **memorySearch** `any` Memory-query parameters and counts recorded for this generation. All of: Variant 1: Parameters used to retrieve relevant memories during generation. Model reference: [MemorySearchParams](/api/models/schema-1igd5iut01#response). **query** `string` Text submitted to memory retrieval for this generation. **topK** `string(int64)` Maximum memory matches requested during generation-context retrieval. Pattern: ^-?\d+$ **threshold** `any` Minimum relevance threshold requested for the memory query. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **rerank** `boolean` Whether reranking was requested for the memory search. **resultsReturned** `string(int64)` Number of memory records returned by the search. Pattern: ^-?\d+$ **relationsReturned** `string(int64)` Number of graph relationships returned by the search. Pattern: ^-?\d+$ **turn** `any` Turn position and limit within the generation run. All of: Variant 1: Turn position within an agentic generation run Model reference: [TurnInfo](/api/models/schema-1ilcikuhu8#response). **currentTurn** `string(int64)` Current turn position within the generation run. Pattern: ^-?\d+$ **maxTurns** `string(int64)` Maximum turns configured for the generation run. Pattern: ^-?\d+$ **languagePreference** `string` Language preference associated with the generation context. **resolvedSystemPrompt** `string` System prompt selected for this generation after prompt precedence is resolved. This field is retained in the schema but is not populated; use resolved\_prompt\_hash for recorded prompt identity. **profileId** `string` Agent profile that produced this message ("" if none active). **model** `string` Model actually used for this generation. **promptSource** `any` Which precedence tier supplied the prompt. Source that supplied the effective system prompt for a generation turn. Distinguishes a client override, a profile template and the conversation default configuration for prompt attribution.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROMPT_SOURCE_CLIENT_OVERRIDE` | 0 | Canonical | See meaning below. | | `PROMPT_SOURCE_PROFILE_TEMPLATE` | 1 | Canonical | See meaning below. | | `PROMPT_SOURCE_DEFAULT_CONFIG` | 2 | Canonical | See meaning below. | **`PROMPT_SOURCE_CLIENT_OVERRIDE`** The caller supplied the prompt through the send request's generation-configuration override. SendRequest.override\_generation\_config **`PROMPT_SOURCE_PROFILE_TEMPLATE`** The prompt was rendered from the active agent profile template. active agent profile's rendered template **`PROMPT_SOURCE_DEFAULT_CONFIG`** The prompt came from the conversation or project default generation configuration. conversation/project default\_generation\_config
Exactly one of: Variant 1: Type: `string` Enum: `PROMPT_SOURCE_CLIENT_OVERRIDE`, `PROMPT_SOURCE_PROFILE_TEMPLATE`, `PROMPT_SOURCE_DEFAULT_CONFIG` Variant 2: Type: `integer(int32)` **baseConfig** `any` Generation configuration resolved at send time before per-call overrides and timeout adjustments, with system\_prompt omitted. The active profile supplies the base when selected; otherwise the conversation default does. Use prompt\_source and profile\_id for prompt attribution. The base configuration can be absent when neither source supplies one or no snapshot was captured. For a supplied per-call override, the populated top-level fields of override\_config overlay base\_config to form the effective configuration. override\_config can be absent when no override was supplied. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#response). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#response). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#response). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#response). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#response). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#response). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#response). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinition]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#response). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfig]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#response). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#response). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#response). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#response). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#response). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#response). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#response). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#response). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **overrideConfig** `any` Per-call generation configuration supplied before the override merge. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#response). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#response). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#response). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#response). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#response). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#response). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#response). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinition]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#response). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfig]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#response). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#response). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#response). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#response). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#response). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#response). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#response). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#response). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **profileVersion** `string(int64)` Immutable version of the active agent profile used to render this turn’s prompt. Absent on older turns and turns without a profile template. Pattern: ^-?\d+$ **fragmentsVersion** `string(int64)` Version of the prompt-fragment set used to render the profile prompt. Pattern: ^-?\d+$ **promptVariables** `map[string, any]` Values bound to the prompt template for this generation. **profileRenderFailed** `boolean` Whether rendering the profile prompt failed for this generation. **resolvedPromptHash** `string` SHA-256 hash, as 64 hexadecimal characters, of the resolved system prompt before the current-time instruction is appended. Identifies prompt content only, excluding model and sampling parameters. Absent on older turns without prompt capture. **resolvedUserContext** `string` The literal user-context text supplied to the model for this turn, including the available name, locale and location conditions. It is a captured prompt input, not a reconstruction from the user’s current profile. The value is computed once per turn and reused across its model calls. It can be empty when location context is unavailable, enrichment fails or the turn predates capture. **resolvedMcpServers** `array[llm_v1_common_v1_MCPServerReference]` The MCP server list used for this turn after resolving conversation settings, the active profile, and any per-turn `override_mcp_servers`. It determines both tool discovery and the allow/block rules applied by `CallTool`. A per-turn override does not change the conversation's stored MCP settings. Compare this snapshot with `settings.mcp_servers` to inspect how the turn's tool set differed. Empty on turns predating capture and on threads with no MCP servers. MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#response). **serverId** `string` ID of pre-configured MCP server (e.g., "github", "filesystem"). **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **clientContext** `any` Arbitrary client-supplied context attached by the client for this message All of: Variant 1: Opaque caller-supplied attributes attached to a conversation message. Values are strings, including values such as `"false"`. The schema allows at most 32 pairs, keys of at most 64 characters, and values of at most 1,024 characters. Keep the entire map well below 8 KiB: Travila also applies an encoded-size limit that includes field overhead and drops context that exceeds it. Short page identifiers and a few relevant values are preferable to a page dump; an oversized map is not automatically shortened. Model reference: [ClientContext](/api/models/schema-1i2sndrl93#response). **values** `map[string, string]` Arbitrary client-supplied context for this message (e.g. page, referrer, device, in-app flow). Keys/values are opaque strings. **feedback** `array[llm_v1_common_v1_MessageFeedback]` Feedback on an assistant message, with one entry per rater identified by rated\_by. A later rating by the same rater replaces their earlier entry. One user's feedback on an assistant-generated message. kind must select a listed feedback representation. Requiredness and allowed values are declared separately. Model reference: [MessageFeedback](/api/models/schema-1iroqctqt1#response). **kind** `any` Rating representation used to interpret the feedback value. Value scale used to interpret recorded feedback.
| Value | No. | Form | Meaning | |---|---|---|---| | `FEEDBACK_KIND_THUMB` | 0 | Canonical | See meaning below. | | `FEEDBACK_KIND_SCALE` | 1 | Canonical | See meaning below. | **`FEEDBACK_KIND_THUMB`** Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. binary thumbs up / down **`FEEDBACK_KIND_SCALE`** Feedback expressed as an integer rating from 1 through 10. 1-10 integer scale
Exactly one of: Variant 1: Type: `string` Enum: `FEEDBACK_KIND_THUMB`, `FEEDBACK_KIND_SCALE` Variant 2: Type: `integer(int32)` **thumbUp** `boolean` Positive when true and negative when false; used for THUMB feedback. **rating** `string(int64)` Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent. Pattern: ^-?\d+$ **reason** `string` Optional explanation for the rating. **ratedAt** `string(date-time)` Timestamp when feedback was submitted (server-set) **ratedBy** `string` Identifier of the user who submitted this feedback. Set by the server from the authenticated user identity; never client-supplied. Each user has one feedback entry per message. **sourceUserMessageId** `string` Identifier of the user message that opened this conversation turn. Generated messages in the same turn share this value; a user message carries its own message\_id. Empty on historical messages that predate turn attribution. Use this field for turn attribution rather than inferring it from message adjacency or a client-supplied message\_id. The generated\_by identifier groups messages by generation run but does not identify the user message that opened the turn. **finishReason** `string` Why the model stopped, verbatim from the provider: "stop", "tool\_calls", "length", "error". Empty for historical messages. **isUpdate** `boolean` True when this replaced the caller's previous rating on this message #### conversations-rateMessage-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "ratedMessage": { "role": "ROLE_SYSTEM", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Example text", "cachePreferred": true } ], "toolCalls": [ { "id": "example_123", "name": "example", "status": "TOOL_EXECUTION_STATUS_PENDING", "serverId": "example_123", "isClientTool": true, "description": "example", "approvedBy": "example", "endReason": "example" } ], "name": "example", "timestamp": "2026-09-16T12:00:00Z", "messageId": "example_123", "annotations": [ { "kind": "ANNOTATION_KIND_URL_CITATION" } ], "sequence": "1", "generatedBy": "example", "usage": { "promptTokens": 1, "completionTokens": 1, "totalTokens": 1, "costEstimate": 1, "isByok": true }, "model": "example", "generationContext": { "languagePreference": "en-US", "resolvedSystemPrompt": "Example text", "profileId": "example_123", "model": "example", "promptSource": "PROMPT_SOURCE_CLIENT_OVERRIDE", "profileVersion": 1, "fragmentsVersion": 1, "profileRenderFailed": true, "resolvedPromptHash": "Example text", "resolvedUserContext": "Example text" }, "clientContext": {}, "feedback": [ { "kind": "FEEDBACK_KIND_THUMB", "thumbUp": true, "reason": "example", "ratedBy": "example" } ], "sourceUserMessageId": "example_123", "finishReason": "example" }, "isUpdate": true } ``` #### cookbook-insights-evaluation-message-feedback-json-01-response Illustrative response for Save the user’s judgment beside the reply. Replace example resource identifiers with your own authorized values. ```json { "ratedMessage": { "role": "ROLE_ASSISTANT", "sequence": "8", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "…" } ], "feedback": [ { "kind": "FEEDBACK_KIND_THUMB", "thumbUp": true, "ratedAt": "2026-08-14T11:02:44Z", "ratedBy": "user_123" } ] }, "isUpdate": true } ``` Document ID: `DOC-MA-conversations-api-rateMessage`. [Section identities and revisions](/documentation-manifest.json). - Rate an assistant message: `DOC-MA-conversations-api-rateMessage#overview` - Request: `DOC-MA-conversations-api-rateMessage#request` - Responses: `DOC-MA-conversations-api-rateMessage#responses` --- # Semantic search over memories URL: https://docs.travila.ai/api/conversations/search-memories **POST** `/api/v1/llm/search-memories` Searches memories by meaning within the authenticated user's tenant scope. Results and relationships depend on the configured provider. An empty result can represent a handled provider failure and does not prove that no memories exist. Search does not provide pagination or a complete inventory. Use an authorized backend key with X-On-Behalf-Of and users\:impersonate scope, or a publishable key with a user JWT. A configured user JWT can also authenticate directly. An effective user and tenant are required; raw identity headers do not grant authority. See the [memory cookbook](/managed-agents/memory-knowledge). The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Use remembered preferences in a returning user’s conversation](/managed-agents/memory-knowledge) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for a semantic search of memories in the authenticated user’s tenant scope. Caller identity and scope come from authenticated context; internal identity context is not part of the supported public search request. **query** `string` **required** Non-empty natural-language search query. Minimum length: 1 **topK** `string(int64)` **required** Maximum results requested. Supply explicitly; omission is rejected before search. The maximum is 100 because these search results are returned directly to the caller. Memory selected for a generation turn has a separate maximum of 50. Pattern: ^-?\d+$ **threshold** `number(double)` Minimum provider relevance score. Omission and zero do not request a positive cutoff. Scores are provider-specific, not probabilities that the memory is true. Minimum: 0 Maximum: 1 **rerank** `boolean` Requests reranking when supported. Absence leaves the provider behavior unchanged; explicit false is forwarded as false. It does not guarantee relevance or correctness. #### memory-search-request Search dietary preferences ```json { "query": "dietary preferences", "topK": 10 } ``` ## Responses ### 200 — Search results returned Content type: `application/json` Relevant memory records and any graph relationships returned by the search provider. **memories** `array[memory_v1_Memory]` Matched memories ordered by relevance. An empty result does not prove that no memories exist. A memory is a stored statement associated with a user and, when recorded, an agent or conversation and a run or session. The `appId` field is the existing public wire name for the tenant identifier. The field name remains unchanged for compatibility. `metadata` is an object whose values are strings. A search can add a `score`; the provider determines its scale. The score does not measure factual truth. `createdAt` and `updatedAt` are RFC 3339 timestamp strings and may include fractional seconds. Absent timestamps mean that no value was returned. Memory text can be incomplete, stale or incorrect. Show the text and available timestamps to the user before acting on it. Search results are a selection by relevance, not a full account of stored memory. See the [memory cookbook](/managed-agents/memory-knowledge) for review and correction tasks. Model reference: [Memory](/api/models/schema-1k63a85bkp#response). **id** `string` Unique memory identifier. **memory** `string` Stored fact text. It may be incomplete, stale or incorrect. **userId** `string` User associated with the memory. **agentId** `string` Agent or conversation associated with the memory. **appId** `string` Tenant identifier associated with the memory. **runId** `string` Associated run or session identifier. **metadata** `map[string, string]` Additional string-valued metadata attached to the memory. **score** `any` Relevance score returned by search. Its scale is provider-specific and is not a probability that the fact is correct. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **createdAt** `string(date-time)` Creation time as an RFC 3339 timestamp; absent when unavailable. **updatedAt** `string(date-time)` Last update time as an RFC 3339 timestamp; absent when unavailable. **relations** `array[memory_v1_Relation]` Returned graph relationships; this list may be absent when there are no relationships. A relation is a directed edge from `source` to `destination`, labeled by `relationship`. These are entity names and an open relationship string; no fixed relationship enumeration is enforced by this contract. Relationships may be absent even when memory records are returned. They describe extracted associations, not verified facts, ownership permissions or lifecycle transitions. Model reference: [Memory relation](/api/models/schema-1k84aa8jbi#response). **source** `string` Source entity name. **relationship** `string` Open string describing the relationship. Example labels do not restrict the allowed values. **destination** `string` Destination entity name. #### memory-search-response Illustrative dietary preferences returned ```json { "memories": [ { "id": "mem_abc123", "memory": "User is vegetarian and avoids gluten", "score": 0.92, "createdAt": "2025-02-15T10:00:00Z", "updatedAt": "2025-02-15T10:00:00Z" }, { "id": "mem_def456", "memory": "User prefers meals under 500 calories", "score": 0.85, "createdAt": "2025-02-20T14:30:00Z", "updatedAt": "2025-02-20T14:30:00Z" } ] } ``` ### 400 — Invalid decoded request, including omitted topK or values outside their bounds, or missing tenant context. ### 401 — Missing or invalid authentication, or no effective user. ### 403 — Insufficient impersonation scope or required tenant membership. ### 500 — Unexpected server failure. ### 502 — Authentication upstream returned an unreadable or invalid response. ### 503 — Authentication service unavailable. ### default — Other failures may be forwarded from upstream. Error bodies vary by origin; this slice does not assert a single error envelope. Document ID: `DOC-MA-conversations-api-searchMemories`. [Section identities and revisions](/documentation-manifest.json). - Semantic search over memories: `DOC-MA-conversations-api-searchMemories#overview` - Request: `DOC-MA-conversations-api-searchMemories#request` - Responses: `DOC-MA-conversations-api-searchMemories#responses` --- # Send a message and wait for the result URL: https://docs.travila.ai/api/conversations/send-message-sync **POST** `/api/v1/llm/send-message-sync` Sends a message and waits for a bounded interval, returning generated messages inline when available. Use it when you need the assistant reply in the HTTP response, such as structured output or a classification. Inspect [`status`](/api/conversations/send-message-sync#response-field-status) even on HTTP 200: a queued message, a pause for client tools or the bounded wait ending can return before the run finishes. A transport timeout or unknown status does not authorize resending the message; reconcile the accepted run. See [Messages and run outcomes](/api/conversations/messages-and-runs) for status interpretation and recovery. Use this in a guide: [Let a customer navigate your app through chat](/managed-agents/delegation-approvals/build-agent-with-tools) · [Check a chat integration before customers use it](/developer-experience/local-tooling/testing) · [Replay datasets and runs](/insights/evaluation/datasets-and-runs) · [Turn a task description into a validated summary object](/managed-agents/model-controls/structured-output) · [Build an assistant that researches the web](/integrations/tools-connections) · [Get a customer’s reply and recover an interrupted send](/managed-agents/conversations/generation) · [Tool policy resolution and lifecycle](/api/tool-execution/policies) · [Automate recurring agent work](/core-platform/scheduling/build-scheduled-agents) · [Signed callbacks and receiver acknowledgement](/api/scheduled-jobs/callbacks) · [Show one correct chat history as updates arrive](/managed-agents/conversations/streaming/payloads) · [Messages and runs](/api/conversations/messages-and-runs) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for submitting a user message and waiting for generation output. **conversationKey** `string` **required** Identifier of the conversation thread. Minimum length: 1 **userMessage** `any` **required** Required — see the note on SendMessageRequest.user\_message. The sync path is where the defect was actually observed: it holds the connection open, waits out a real generation, and hands back messages and a COMPLETED status, so a dropped turn field looks exactly like a working call. All of: Variant 1: Chat message At least one of content or tool\_calls must contain an entry; both lists may be nonempty. role must select a listed message role. Requiredness and allowed values are declared separately. Model reference: [Message](/api/models/schema-1j3dcf7kvu#request). **role** `any` **required** Role of the participant that produced the chat message. Participant role attached to a conversation message and forwarded in model context.
| Value | No. | Form | Meaning | |---|---|---|---| | `ROLE_SYSTEM` | 0 | Canonical | Instructions or context provided as a system message. | | `ROLE_USER` | 1 | Canonical | Input supplied by the user or customer application. | | `ROLE_ASSISTANT` | 2 | Canonical | Content produced by the assistant, including its tool-call requests. | | `ROLE_TOOL` | 3 | Canonical | A tool result supplied back to the assistant. |
Exactly one of: Variant 1: Type: `string` Enum: `ROLE_SYSTEM`, `ROLE_USER`, `ROLE_ASSISTANT`, `ROLE_TOOL` Variant 2: Type: `integer(int32)` Enum: `0`, `1`, `2`, `3` **content** `array[llm_v1_common_v1_ContentPartInput]` Content parts composing the chat message. Content parts composing a message, using a flattened structure for JSON compatibility. The `type` identifies how the content is represented; only defined content types are accepted. Model reference: [ContentPart](/api/models/schema-1hqi9r2bhh#request). **type** `any` Kind of content carried by this message part. Discriminator identifying which content representation a message part carries.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTENT_PART_TYPE_TEXT` | 0 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_URL` | 1 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_BASE64` | 2 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_ID` | 3 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_PATH` | 4 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_URL` | 5 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_DATA_URL` | 6 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_AUDIO_BASE64` | 7 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_REASONING` | 8 | Canonical | See meaning below. | **`CONTENT_PART_TYPE_TEXT`** Plain text carried by the content part. Plain text content **`CONTENT_PART_TYPE_IMAGE_URL`** An image supplied through a remote URL. Remote image URL **`CONTENT_PART_TYPE_IMAGE_BASE64`** An image supplied as base64-encoded bytes. Base64-encoded image data **`CONTENT_PART_TYPE_FILE_ID`** A provider file identifier or internal storage identifier resolved before generation. File ID — a provider file ID (e.g., OpenAI) OR an internal storage file ID; resolved to a signed FILE\_URL just-in-time before the model-provider request **`CONTENT_PART_TYPE_FILE_PATH`** A reference to a local file path. Local file path reference **`CONTENT_PART_TYPE_FILE_URL`** A file supplied through a public or signed URL. Public or signed file URL (e.g., PDF URL or data: URL) **`CONTENT_PART_TYPE_FILE_DATA_URL`** A file embedded in a data URL, including its media type and encoded data. data\:application/pdf;base64,... or similar **`CONTENT_PART_TYPE_AUDIO_BASE64`** Base64-encoded audio; the part metadata identifies its audio format. Base64-encoded audio (metadata.format required, e.g., wav/mp3) **`CONTENT_PART_TYPE_REASONING`** A reasoning segment returned by a model provider, when available. Reasoning/thinking content from chain-of-thought models
Exactly one of: Variant 1: Type: `string` Enum: `CONTENT_PART_TYPE_TEXT`, `CONTENT_PART_TYPE_IMAGE_URL`, `CONTENT_PART_TYPE_IMAGE_BASE64`, `CONTENT_PART_TYPE_FILE_ID`, `CONTENT_PART_TYPE_FILE_PATH`, `CONTENT_PART_TYPE_FILE_URL`, `CONTENT_PART_TYPE_FILE_DATA_URL`, `CONTENT_PART_TYPE_AUDIO_BASE64`, `CONTENT_PART_TYPE_REASONING` Variant 2: Type: `integer(int32)` Enum: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8` **content** `string` Text content, image URL, file ID, or base64-encoded data. **metadata** `map[string, string]` Additional type-specific metadata (dimensions, mime\_type, etc.). **cachePreferred** `boolean` Hint that this part is eligible for provider prompt caching. **structuredMessage** `any` Populated on TEXT parts for structured output responses. All of: Variant 1: A structured message whose JSON payload has been validated against a declared schema. Consumers can trust that json\_payload conforms to the schema identified by schema\_name. Inspect the run outcome before treating any message as complete. Current structured metadata is attached to a text content part through [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage) can be absent. Use an object at the schema root and validate the exact final response your application consumes; server validation covers only the first model choice. For integers that your JSON client cannot represent exactly, define string-valued fields in your schema instead of converting them through floating point. Model reference: [StructuredMessage](/api/models/schema-1ho1lk4ndj#request). **jsonPayload** `map[string, any]` The validated JSON payload as a Struct (preserves types) **schemaName** `string` Schema identifier (from ResponseFormat.schema\_name) **healed** `boolean` Whether response healing is reported for this structured message. Currently returned as false. **toolCalls** `array[llm_v1_common_v1_ToolCallInput]` Assistant-to-tool invocations. A single structured tool call emitted by the model [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat) is the client answer window. Expiry ends that wait and rejects late results; the timeout policy determines the outcome. Model reference: [ToolCall](/api/models/schema-1it6mqsqoo#request). **id** `string` Provider-supplied call id. **name** `string` Name of the tool or function being invoked. **argumentsJson** `map[string, any]` JSON object payload. **status** `any` Execution status recorded for the tool call. Execution state of a tool call, including approval waiting and terminal outcomes. The terminal outcomes are COMPLETED, FAILED, CANCELLED and TIMED\_OUT; inspect ToolCall.end\_reason for why a call ended rather than treating the reason as another status. Use a listed execution status. The end reason explains the outcome separately from the status.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_EXECUTION_STATUS_PENDING` | 0 | Canonical | The tool call is waiting to begin execution. | | `TOOL_EXECUTION_STATUS_EXECUTING` | 1 | Canonical | The tool call is currently executing. | | `TOOL_EXECUTION_STATUS_COMPLETED` | 2 | Canonical | The tool call completed successfully. This is a terminal outcome. | | `TOOL_EXECUTION_STATUS_FAILED` | 3 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. | | `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 4 | Canonical | The tool call is waiting for approval before it can execute. | | `TOOL_EXECUTION_STATUS_CANCELLED` | 5 | Canonical | The tool call was cancelled before normal completion. | | `TOOL_EXECUTION_STATUS_TIMED_OUT` | 6 | Canonical | Tool execution ended because its time limit elapsed. |
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_EXECUTION_STATUS_PENDING`, `TOOL_EXECUTION_STATUS_EXECUTING`, `TOOL_EXECUTION_STATUS_COMPLETED`, `TOOL_EXECUTION_STATUS_FAILED`, `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, `TOOL_EXECUTION_STATUS_CANCELLED`, `TOOL_EXECUTION_STATUS_TIMED_OUT` Variant 2: Type: `integer(int32)` **resultJson** `map[string, any]` Tool execution result (object). **executedAt** `string(date-time)` Time when the tool execution was recorded. **serverId** `string` Which server provides this tool (for MCP tools). **isClientTool** `boolean` True if this is a client-side tool handled by client. **description** `string` Tool description captured from the resolved tool definition when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. **parametersJsonSchema** `map[string, any]` JSON Schema describing the tool’s input arguments. **requiresApprovalAt** `string(date-time)` Deadline for an approval decision, calculated from the effective approval timeout. This is not the time the call began waiting. An approval received after the deadline is rejected. **approvedAt** `string(date-time)` Timestamp when approval decision was recorded (if approved/rejected) **approvedBy** `string` Identifier of the approver (user id, email, or actor key) **executionDuration** `string` End-to-end execution duration once terminal (includes tool server latency or client-side time) Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **endReason** `string` Why this call ended, in one short phrase — "approval rejected", "approval timeout", or the underlying error. Set only once `status` is terminal, and empty on a clean COMPLETED. Use this reason to distinguish a rejection from a failure without parsing the tool result. **clientToolDeadlineAt** `string(date-time)` Deadline by which the client must submit a result for this call, stamped when the call is dispatched to a caller. **name** `string` Name identifying the sender of the chat message. optional sender name **timestamp** `string(date-time)` Timestamp associated with the conversation message or event. **messageId** `string` Unique message identifier. **annotations** `array[llm_v1_common_v1_AnnotationInput]` Structured annotations (e.g., standardized web search URL citations, PDF reuse tokens) Tagged provider annotation attached to generated content, such as a citation or PDF reference. Model reference: [Annotation](/api/models/schema-1i0hjer0pd#request). **kind** `any` Selected kind; determines which submessage is populated Kind of source annotation associated with generated content.
| Value | No. | Form | Meaning | |---|---|---|---| | `ANNOTATION_KIND_URL_CITATION` | 0 | Canonical | A citation to a source identified by its URL. | | `ANNOTATION_KIND_PDF` | 1 | Canonical | An annotation identifying source content in a PDF document. |
Exactly one of: Variant 1: Type: `string` Enum: `ANNOTATION_KIND_URL_CITATION`, `ANNOTATION_KIND_PDF` Variant 2: Type: `integer(int32)` **urlCitation** `any` Submessage fields (optional); populate the one matching kind All of: Variant 1: Web source and character range cited in generated message content. Model reference: [UrlCitation](/api/models/schema-1hujls61ng#request). **url** `string` URL of the cited web page. **title** `string` Title of the web page cited by this annotation. **content** `string` Optional excerpt or snippet of the cited web page. **startIndex** `string(int64)` Character index in message content. Pattern: ^-?\d+$ **endIndex** `string(int64)` Character index in message content. Pattern: ^-?\d+$ **pdf** `any` PDF annotation identifying the parsed file and available parsing output. All of: Variant 1: Provider annotation identifying a parsed PDF and reusable parsing output. Model reference: [PdfAnnotation](/api/models/schema-1hsi58i6pb#request). **filename** `string` Optional identifying information about the original file **engine** `string` PDF parsing engine used by provider (e.g., "pdf-text", "mistral-ocr", "native") **token** `string` Opaque provider token or handle allowing reuse without re-parsing **sourceUrl** `string` Optional: original source reference (public URL or data: URL) **hash** `string` Provider-supplied hash identifying the parsed file. **content** `array[llm_v1_common_v1_ContentPartInput]` Optional structured content returned by provider annotations (text, image URLs, etc.) Note: This can be large; include only if you need to round-trip provider annotations. Content parts composing a message, using a flattened structure for JSON compatibility. The `type` identifies how the content is represented; only defined content types are accepted. Model reference: [ContentPart](/api/models/schema-1hqi9r2bhh#request). **type** `any` Kind of content carried by this message part. Discriminator identifying which content representation a message part carries.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTENT_PART_TYPE_TEXT` | 0 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_URL` | 1 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_BASE64` | 2 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_ID` | 3 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_PATH` | 4 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_URL` | 5 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_DATA_URL` | 6 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_AUDIO_BASE64` | 7 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_REASONING` | 8 | Canonical | See meaning below. | **`CONTENT_PART_TYPE_TEXT`** Plain text carried by the content part. Plain text content **`CONTENT_PART_TYPE_IMAGE_URL`** An image supplied through a remote URL. Remote image URL **`CONTENT_PART_TYPE_IMAGE_BASE64`** An image supplied as base64-encoded bytes. Base64-encoded image data **`CONTENT_PART_TYPE_FILE_ID`** A provider file identifier or internal storage identifier resolved before generation. File ID — a provider file ID (e.g., OpenAI) OR an internal storage file ID; resolved to a signed FILE\_URL just-in-time before the model-provider request **`CONTENT_PART_TYPE_FILE_PATH`** A reference to a local file path. Local file path reference **`CONTENT_PART_TYPE_FILE_URL`** A file supplied through a public or signed URL. Public or signed file URL (e.g., PDF URL or data: URL) **`CONTENT_PART_TYPE_FILE_DATA_URL`** A file embedded in a data URL, including its media type and encoded data. data\:application/pdf;base64,... or similar **`CONTENT_PART_TYPE_AUDIO_BASE64`** Base64-encoded audio; the part metadata identifies its audio format. Base64-encoded audio (metadata.format required, e.g., wav/mp3) **`CONTENT_PART_TYPE_REASONING`** A reasoning segment returned by a model provider, when available. Reasoning/thinking content from chain-of-thought models
Exactly one of: Variant 1: Type: `string` Enum: `CONTENT_PART_TYPE_TEXT`, `CONTENT_PART_TYPE_IMAGE_URL`, `CONTENT_PART_TYPE_IMAGE_BASE64`, `CONTENT_PART_TYPE_FILE_ID`, `CONTENT_PART_TYPE_FILE_PATH`, `CONTENT_PART_TYPE_FILE_URL`, `CONTENT_PART_TYPE_FILE_DATA_URL`, `CONTENT_PART_TYPE_AUDIO_BASE64`, `CONTENT_PART_TYPE_REASONING` Variant 2: Type: `integer(int32)` Enum: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8` **content** `string` Text content, image URL, file ID, or base64-encoded data. **metadata** `map[string, string]` Additional type-specific metadata (dimensions, mime\_type, etc.). **cachePreferred** `boolean` Hint that this part is eligible for provider prompt caching. **structuredMessage** `any` Populated on TEXT parts for structured output responses. All of: Variant 1: A structured message whose JSON payload has been validated against a declared schema. Consumers can trust that json\_payload conforms to the schema identified by schema\_name. Inspect the run outcome before treating any message as complete. Current structured metadata is attached to a text content part through [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage) can be absent. Use an object at the schema root and validate the exact final response your application consumes; server validation covers only the first model choice. For integers that your JSON client cannot represent exactly, define string-valued fields in your schema instead of converting them through floating point. Model reference: [StructuredMessage](/api/models/schema-1ho1lk4ndj#request). **jsonPayload** `map[string, any]` The validated JSON payload as a Struct (preserves types) **schemaName** `string` Schema identifier (from ResponseFormat.schema\_name) **healed** `boolean` Whether response healing is reported for this structured message. Currently returned as false. **metadata** `map[string, string]` Provider-specific extras. **sequence** `string(int64)` Monotonic, per-conversation sequence number for stable ordering (1-based) Pattern: ^-?\d+$ **generatedBy** `string` Workflow run id or generator key that produced this message (e.g., workflow run key) **usage** `any` Token usage for this generation (populated for assistant messages) All of: Variant 1: Usage accounting Model reference: [Usage](/api/models/schema-1j1vov2uoh#request). **promptTokens** `string(int64)` Prompt-token usage reported by the model provider. Pattern: ^-?\d+$ **completionTokens** `string(int64)` Completion-token usage reported by the model provider. Pattern: ^-?\d+$ **totalTokens** `string(int64)` Total token usage reported by the model provider. Pattern: ^-?\d+$ **costEstimate** `any` Estimated cost in USD. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completionTokensDetails** `any` Breakdown of completion tokens. All of: Variant 1: Breakdown of completion-token usage. Categories are measured by different upstream tokenizers and need not sum to completion\_tokens; reasoning\_tokens can exceed completion\_tokens. One category must not be derived by subtracting the others. Model reference: [CompletionTokensDetails](/api/models/schema-1i6q4qpg72#request). **reasoningTokens** `string(int64)` Tokens used for reasoning/thinking. Pattern: ^-?\d+$ **imageTokens** `string(int64)` Completion tokens emitted as image output. Pattern: ^-?\d+$ **audioTokens** `string(int64)` Completion tokens emitted as audio output. Pattern: ^-?\d+$ **promptTokensDetails** `any` Breakdown of prompt tokens (cache). All of: Variant 1: Breakdown of prompt token usage by category (input-side cache accounting) Subset semantics: cached\_tokens and cache\_write\_tokens are a breakdown *of* prompt\_tokens, so cached\_tokens + cache\_write\_tokens \<= Usage.prompt\_tokens. Ordinary (full-rate) prompt tokens = prompt\_tokens - cached\_tokens - cache\_write\_tokens. audio\_tokens / video\_tokens are modality breakdowns of prompt\_tokens (also a subset). Model reference: [PromptTokensDetails](/api/models/schema-1ivj82m55o#request). **cachedTokens** `string(int64)` Prompt tokens served from cache (cache READ). Pattern: ^-?\d+$ **cacheWriteTokens** `string(int64)` Prompt tokens written to cache this call (cache WRITE). Pattern: ^-?\d+$ **audioTokens** `string(int64)` Prompt tokens from audio input (multimodal). Pattern: ^-?\d+$ **videoTokens** `string(int64)` Prompt tokens from video input (multimodal). Pattern: ^-?\d+$ **costDetails** `any` Breakdown of upstream provider cost (BYOK routes). All of: Variant 1: Breakdown of model-provider cost. When the customer supplies the provider key, usage.cost is zero and upstream\_inference\_cost reports the provider spend, split into prompt and completion components. Model reference: [CostDetails](/api/models/schema-1ia0h761lm#request). **upstreamInferenceCost** `any` Total upstream provider cost (USD) on BYOK routes. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferencePromptCost** `any` Upstream cost attributed to prompt tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferenceCompletionCost** `any` Upstream cost attributed to completion tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **isByok** `boolean` Whether this generation used the customer's own model-provider key. **model** `string` Model that generated this message (e.g., "anthropic/claude-sonnet-4") **generationContext** `any` Dynamic context that shaped this generation (memories, search params, turn info) All of: Variant 1: Snapshot of retrieval inputs, prompt provenance, and turn position that shaped a generated message. Model reference: [GenerationContext](/api/models/schema-1im79fphmq#request). **memories** `array[llm_v1_common_v1_MemoryReferenceInput]` Memory records captured in the generation context. A memory record retrieved and included in generation context. Model reference: [MemoryReference](/api/models/schema-1ie9a4bgk5#request). **memoryId** `string` Identifier of the retrieved memory record. **score** `any` Relevance score reported by the memory provider for this match. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **memoryText** `string` Text of the retrieved memory record. **createdAt** `string(date-time)` Time when this record was created. **updatedAt** `string(date-time)` Time when this record was last updated. **relations** `array[llm_v1_common_v1_RelationReferenceInput]` Graph relationships captured in the generation context. A graph relationship retrieved and included in generation context. Model reference: [RelationReference](/api/models/schema-1ijit8ceuv#request). **source** `string` Source entity of the memory graph relationship. **relationship** `string` Relationship label connecting the source and destination entities. **destination** `string` Destination entity of the memory graph relationship. **memorySearch** `any` Memory-query parameters and counts recorded for this generation. All of: Variant 1: Parameters used to retrieve relevant memories during generation. Model reference: [MemorySearchParams](/api/models/schema-1igd5iut01#request). **query** `string` Text submitted to memory retrieval for this generation. **topK** `string(int64)` Maximum memory matches requested during generation-context retrieval. Pattern: ^-?\d+$ **threshold** `any` Minimum relevance threshold requested for the memory query. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **rerank** `boolean` Whether reranking was requested for the memory search. **resultsReturned** `string(int64)` Number of memory records returned by the search. Pattern: ^-?\d+$ **relationsReturned** `string(int64)` Number of graph relationships returned by the search. Pattern: ^-?\d+$ **turn** `any` Turn position and limit within the generation run. All of: Variant 1: Turn position within an agentic generation run Model reference: [TurnInfo](/api/models/schema-1ilcikuhu8#request). **currentTurn** `string(int64)` Current turn position within the generation run. Pattern: ^-?\d+$ **maxTurns** `string(int64)` Maximum turns configured for the generation run. Pattern: ^-?\d+$ **languagePreference** `string` Language preference associated with the generation context. **resolvedSystemPrompt** `string` System prompt selected for this generation after prompt precedence is resolved. This field is retained in the schema but is not populated; use resolved\_prompt\_hash for recorded prompt identity. **profileId** `string` Agent profile that produced this message ("" if none active). **model** `string` Model actually used for this generation. **promptSource** `any` Which precedence tier supplied the prompt. Source that supplied the effective system prompt for a generation turn. Distinguishes a client override, a profile template and the conversation default configuration for prompt attribution.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROMPT_SOURCE_CLIENT_OVERRIDE` | 0 | Canonical | See meaning below. | | `PROMPT_SOURCE_PROFILE_TEMPLATE` | 1 | Canonical | See meaning below. | | `PROMPT_SOURCE_DEFAULT_CONFIG` | 2 | Canonical | See meaning below. | **`PROMPT_SOURCE_CLIENT_OVERRIDE`** The caller supplied the prompt through the send request's generation-configuration override. SendRequest.override\_generation\_config **`PROMPT_SOURCE_PROFILE_TEMPLATE`** The prompt was rendered from the active agent profile template. active agent profile's rendered template **`PROMPT_SOURCE_DEFAULT_CONFIG`** The prompt came from the conversation or project default generation configuration. conversation/project default\_generation\_config
Exactly one of: Variant 1: Type: `string` Enum: `PROMPT_SOURCE_CLIENT_OVERRIDE`, `PROMPT_SOURCE_PROFILE_TEMPLATE`, `PROMPT_SOURCE_DEFAULT_CONFIG` Variant 2: Type: `integer(int32)` **baseConfig** `any` Generation configuration resolved at send time before per-call overrides and timeout adjustments, with system\_prompt omitted. The active profile supplies the base when selected; otherwise the conversation default does. Use prompt\_source and profile\_id for prompt attribution. The base configuration can be absent when neither source supplies one or no snapshot was captured. For a supplied per-call override, the populated top-level fields of override\_config overlay base\_config to form the effective configuration. override\_config can be absent when no override was supplied. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#request). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#request). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#request). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#request). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#request). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#request). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinitionInput]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#request). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinitionInput]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRuleInput]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#request). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#request). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#request). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRuleInput]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#request). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#request). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfigInput]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#request). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#request). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#request). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#request). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) Minimum length: 2 Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$ **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#request). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" Maximum length: 50 **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" Enum: ``, `friendly`, `iso8601`, `date_only` Maximum length: 50 **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#request). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` **required** Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" Enum: `minimal`, `standard`, `verbose` **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#request). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#request). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **overrideConfig** `any` Per-call generation configuration supplied before the override merge. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#request). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#request). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#request). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#request). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#request). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#request). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinitionInput]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#request). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinitionInput]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRuleInput]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#request). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#request). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#request). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRuleInput]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#request). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#request). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfigInput]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#request). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#request). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#request). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#request). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) Minimum length: 2 Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$ **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#request). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" Maximum length: 50 **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" Enum: ``, `friendly`, `iso8601`, `date_only` Maximum length: 50 **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#request). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` **required** Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" Enum: `minimal`, `standard`, `verbose` **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#request). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#request). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **profileVersion** `string(int64)` Immutable version of the active agent profile used to render this turn’s prompt. Absent on older turns and turns without a profile template. Pattern: ^-?\d+$ **fragmentsVersion** `string(int64)` Version of the prompt-fragment set used to render the profile prompt. Pattern: ^-?\d+$ **promptVariables** `map[string, any]` Values bound to the prompt template for this generation. **profileRenderFailed** `boolean` Whether rendering the profile prompt failed for this generation. **resolvedPromptHash** `string` SHA-256 hash, as 64 hexadecimal characters, of the resolved system prompt before the current-time instruction is appended. Identifies prompt content only, excluding model and sampling parameters. Absent on older turns without prompt capture. **resolvedUserContext** `string` The literal user-context text supplied to the model for this turn, including the available name, locale and location conditions. It is a captured prompt input, not a reconstruction from the user’s current profile. The value is computed once per turn and reused across its model calls. It can be empty when location context is unavailable, enrichment fails or the turn predates capture. **resolvedMcpServers** `array[llm_v1_common_v1_MCPServerReferenceInput]` The MCP server list used for this turn after resolving conversation settings, the active profile, and any per-turn `override_mcp_servers`. It determines both tool discovery and the allow/block rules applied by `CallTool`. A per-turn override does not change the conversation's stored MCP settings. Compare this snapshot with `settings.mcp_servers` to inspect how the turn's tool set differed. Empty on turns predating capture and on threads with no MCP servers. MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#request). **serverId** `string` **required** ID of pre-configured MCP server (e.g., "github", "filesystem"). Minimum length: 1 **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **clientContext** `any` Arbitrary client-supplied context attached by the client for this message All of: Variant 1: Opaque caller-supplied attributes attached to a conversation message. Values are strings, including values such as `"false"`. The schema allows at most 32 pairs, keys of at most 64 characters, and values of at most 1,024 characters. Keep the entire map well below 8 KiB: Travila also applies an encoded-size limit that includes field overhead and drops context that exceeds it. Short page identifiers and a few relevant values are preferable to a page dump; an oversized map is not automatically shortened. Model reference: [ClientContext](/api/models/schema-1i2sndrl93#request). **values** `map[string, string]` Arbitrary client-supplied context for this message (e.g. page, referrer, device, in-app flow). Keys/values are opaque strings. Maximum properties: 32 **feedback** `array[llm_v1_common_v1_MessageFeedbackInput]` Feedback on an assistant message, with one entry per rater identified by rated\_by. A later rating by the same rater replaces their earlier entry. One user's feedback on an assistant-generated message. kind must select a listed feedback representation. Requiredness and allowed values are declared separately. Model reference: [MessageFeedback](/api/models/schema-1iroqctqt1#request). **kind** `any` **required** Rating representation used to interpret the feedback value. Value scale used to interpret recorded feedback.
| Value | No. | Form | Meaning | |---|---|---|---| | `FEEDBACK_KIND_THUMB` | 0 | Canonical | See meaning below. | | `FEEDBACK_KIND_SCALE` | 1 | Canonical | See meaning below. | **`FEEDBACK_KIND_THUMB`** Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. binary thumbs up / down **`FEEDBACK_KIND_SCALE`** Feedback expressed as an integer rating from 1 through 10. 1-10 integer scale
Exactly one of: Variant 1: Type: `string` Enum: `FEEDBACK_KIND_THUMB`, `FEEDBACK_KIND_SCALE` Variant 2: Type: `integer(int32)` Enum: `0`, `1` **thumbUp** `boolean` Positive when true and negative when false; used for THUMB feedback. **rating** `string(int64)` Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent. Pattern: ^-?\d+$ **reason** `string` Optional explanation for the rating. Maximum length: 1000 **ratedAt** `string(date-time)` Timestamp when feedback was submitted (server-set) **ratedBy** `string` Identifier of the user who submitted this feedback. Set by the server from the authenticated user identity; never client-supplied. Each user has one feedback entry per message. **sourceUserMessageId** `string` Identifier of the user message that opened this conversation turn. Generated messages in the same turn share this value; a user message carries its own message\_id. Empty on historical messages that predate turn attribution. Use this field for turn attribution rather than inferring it from message adjacency or a client-supplied message\_id. The generated\_by identifier groups messages by generation run but does not identify the user message that opened the turn. **finishReason** `string` Why the model stopped, verbatim from the provider: "stop", "tool\_calls", "length", "error". Empty for historical messages. **overrideGenerationConfig** `any` Per-call configuration overrides applied to the active profile’s configuration, or otherwise the conversation default. Supplied scalar values, including zero, empty or false, replace the base value; omitted values inherit. Empty repeated or map values inherit. Use clear\_tools to clear inherited tools and clear\_client\_tools to clear inherited client tools. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#request). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#request). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#request). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#request). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#request). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#request). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinitionInput]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#request). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinitionInput]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRuleInput]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#request). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#request). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#request). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRuleInput]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#request). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#request). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfigInput]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#request). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#request). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#request). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#request). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) Minimum length: 2 Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$ **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#request). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" Maximum length: 50 **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" Enum: ``, `friendly`, `iso8601`, `date_only` Maximum length: 50 **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#request). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` **required** Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" Enum: `minimal`, `standard`, `verbose` **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#request). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#request). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **setActiveProfileId** `string` Set the active agent profile for this and subsequent conversation turns. **setActiveProfileVersion** `string(int64)` Version of the active agent profile forwarded with this turn. Pattern: ^-?\d+$ **overrideMcpServers** `array[llm_v1_common_v1_MCPServerReferenceInput]` MCP servers for this turn only. A nonempty list replaces the active profile’s or conversation’s list for tool discovery and execution; an empty list inherits the resolved configuration. MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#request). **serverId** `string` **required** ID of pre-configured MCP server (e.g., "github", "filesystem"). Minimum length: 1 **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **experiment** `any` Dataset-run attribution for a scripted evaluation turn. Leave unset for ordinary conversation traffic. All of: Variant 1: Dataset-run attribution attached when a scripted evaluation turn is sent. Supported on SendMessageRequest and SendMessageSyncRequest; ordinary conversation traffic leaves it unset. The attribution must accompany the turn so its observations can be associated with the dataset run; a separate post-run link does not supply this attribution. The dataset is required when experiment context is supplied. This attribution is separate from client\_context, which is included in model prompt context. Do not place evaluation attribution in prompt context. dataset\_item\_id is optional: a run can be scored from its traces without assigning each turn to a dataset item. profile\_revision\_hash supplies a profile revision fingerprint for comparison and attribution. Model reference: [ExperimentContext](/api/models/schema-1icbr3lltu#request). **datasetId** `string` **required** Identifier of the dataset to which this run belongs. Required whenever experiment context is supplied. Minimum length: 1 **runName** `string` **required** Names the run. Repeating a run\_name for the same dataset appends to that run rather than starting a new one, because the derived experiment id is deterministic — the same property that lets a retried turn land in the run it belongs to. Minimum length: 1 **datasetItemId** `string` Which dataset item this turn exercises. Optional: a run can be scored on its traces alone, and a harness that does not model items per-turn can leave it empty. **description** `string` Free-text description displayed with the dataset run. **metadataJson** `string` Additional run metadata serialized as a JSON object string and carried through unchanged. **profileRevisionHash** `string` Profile revision fingerprint attached to the dataset run for comparison and attribution. #### conversations-sendMessageSync-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "conversationKey": "example_123", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Hello" } ] } } ``` #### cookbook-core-platform-scheduling-build-scheduled-agents-01-request Guide request for Step 3: Drive an agent turn from the callback. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Generate the daily briefing." } ] } } ``` #### cookbook-developer-experience-local-tooling-testing-01-request Guide request for Verify that an in-app action returns control to the conversation. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Navigate to my profile." } ] } } ``` #### cookbook-insights-evaluation-datasets-and-runs-05-request Guide request for 4. Run both configurations and retain their outcomes. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "What is the return window?" } ] }, "experiment": { "datasetId": "ds_771", "runName": "nightly-2026-08-14", "datasetItemId": "di_001", "profileRevisionHash": "a1b2c3…" } } ``` #### cookbook-managed-agents-conversations-generation-03-request Guide request for Separate recipe: wait for a backend summary in the response. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Summarize this thread as JSON." } ] } } ``` #### cookbook-managed-agents-delegation-approvals-using-tools-03-request Guide request for Step 1: Receive the complete navigation call. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "support-chat-001", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Navigate to my profile." } ] } } ``` ## Responses ### 200 — Run status returned; generation may still be active or waiting Content type: `application/json` Result of submitting a user message and waiting for generation output. **runId** `string` Identifier of the generation run associated with the operation. **interruptedPriorRun** `boolean` Whether submitting this turn interrupted a preceding generation run. **messages** `array[llm_v1_common_v1_Message]` Conversation messages returned by the generation segment. Chat message At least one of content or tool\_calls must contain an entry; both lists may be nonempty. role must select a listed message role. Requiredness and allowed values are declared separately. Model reference: [Message](/api/models/schema-1j3dcf7kvu#response). **role** `any` Role of the participant that produced the chat message. Participant role attached to a conversation message and forwarded in model context.
| Value | No. | Form | Meaning | |---|---|---|---| | `ROLE_SYSTEM` | 0 | Canonical | Instructions or context provided as a system message. | | `ROLE_USER` | 1 | Canonical | Input supplied by the user or customer application. | | `ROLE_ASSISTANT` | 2 | Canonical | Content produced by the assistant, including its tool-call requests. | | `ROLE_TOOL` | 3 | Canonical | A tool result supplied back to the assistant. |
Exactly one of: Variant 1: Type: `string` Enum: `ROLE_SYSTEM`, `ROLE_USER`, `ROLE_ASSISTANT`, `ROLE_TOOL` Variant 2: Type: `integer(int32)` **content** `array[llm_v1_common_v1_ContentPart]` Content parts composing the chat message. Content parts composing a message, using a flattened structure for JSON compatibility. The `type` identifies how the content is represented; only defined content types are accepted. Model reference: [ContentPart](/api/models/schema-1hqi9r2bhh#response). **type** `any` Kind of content carried by this message part. Discriminator identifying which content representation a message part carries.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTENT_PART_TYPE_TEXT` | 0 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_URL` | 1 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_BASE64` | 2 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_ID` | 3 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_PATH` | 4 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_URL` | 5 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_DATA_URL` | 6 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_AUDIO_BASE64` | 7 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_REASONING` | 8 | Canonical | See meaning below. | **`CONTENT_PART_TYPE_TEXT`** Plain text carried by the content part. Plain text content **`CONTENT_PART_TYPE_IMAGE_URL`** An image supplied through a remote URL. Remote image URL **`CONTENT_PART_TYPE_IMAGE_BASE64`** An image supplied as base64-encoded bytes. Base64-encoded image data **`CONTENT_PART_TYPE_FILE_ID`** A provider file identifier or internal storage identifier resolved before generation. File ID — a provider file ID (e.g., OpenAI) OR an internal storage file ID; resolved to a signed FILE\_URL just-in-time before the model-provider request **`CONTENT_PART_TYPE_FILE_PATH`** A reference to a local file path. Local file path reference **`CONTENT_PART_TYPE_FILE_URL`** A file supplied through a public or signed URL. Public or signed file URL (e.g., PDF URL or data: URL) **`CONTENT_PART_TYPE_FILE_DATA_URL`** A file embedded in a data URL, including its media type and encoded data. data\:application/pdf;base64,... or similar **`CONTENT_PART_TYPE_AUDIO_BASE64`** Base64-encoded audio; the part metadata identifies its audio format. Base64-encoded audio (metadata.format required, e.g., wav/mp3) **`CONTENT_PART_TYPE_REASONING`** A reasoning segment returned by a model provider, when available. Reasoning/thinking content from chain-of-thought models
Exactly one of: Variant 1: Type: `string` Enum: `CONTENT_PART_TYPE_TEXT`, `CONTENT_PART_TYPE_IMAGE_URL`, `CONTENT_PART_TYPE_IMAGE_BASE64`, `CONTENT_PART_TYPE_FILE_ID`, `CONTENT_PART_TYPE_FILE_PATH`, `CONTENT_PART_TYPE_FILE_URL`, `CONTENT_PART_TYPE_FILE_DATA_URL`, `CONTENT_PART_TYPE_AUDIO_BASE64`, `CONTENT_PART_TYPE_REASONING` Variant 2: Type: `integer(int32)` **content** `string` Text content, image URL, file ID, or base64-encoded data. **metadata** `map[string, string]` Additional type-specific metadata (dimensions, mime\_type, etc.). **cachePreferred** `boolean` Hint that this part is eligible for provider prompt caching. **structuredMessage** `any` Populated on TEXT parts for structured output responses. All of: Variant 1: A structured message whose JSON payload has been validated against a declared schema. Consumers can trust that json\_payload conforms to the schema identified by schema\_name. Inspect the run outcome before treating any message as complete. Current structured metadata is attached to a text content part through [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage) can be absent. Use an object at the schema root and validate the exact final response your application consumes; server validation covers only the first model choice. For integers that your JSON client cannot represent exactly, define string-valued fields in your schema instead of converting them through floating point. Model reference: [StructuredMessage](/api/models/schema-1ho1lk4ndj#response). **jsonPayload** `map[string, any]` The validated JSON payload as a Struct (preserves types) **schemaName** `string` Schema identifier (from ResponseFormat.schema\_name) **healed** `boolean` Whether response healing is reported for this structured message. Currently returned as false. **toolCalls** `array[llm_v1_common_v1_ToolCall]` Assistant-to-tool invocations. A single structured tool call emitted by the model [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat) is the client answer window. Expiry ends that wait and rejects late results; the timeout policy determines the outcome. Model reference: [ToolCall](/api/models/schema-1it6mqsqoo#response). **id** `string` Provider-supplied call id. **name** `string` Name of the tool or function being invoked. **argumentsJson** `map[string, any]` JSON object payload. **status** `any` Execution status recorded for the tool call. Execution state of a tool call, including approval waiting and terminal outcomes. The terminal outcomes are COMPLETED, FAILED, CANCELLED and TIMED\_OUT; inspect ToolCall.end\_reason for why a call ended rather than treating the reason as another status. Use a listed execution status. The end reason explains the outcome separately from the status.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_EXECUTION_STATUS_PENDING` | 0 | Canonical | The tool call is waiting to begin execution. | | `TOOL_EXECUTION_STATUS_EXECUTING` | 1 | Canonical | The tool call is currently executing. | | `TOOL_EXECUTION_STATUS_COMPLETED` | 2 | Canonical | The tool call completed successfully. This is a terminal outcome. | | `TOOL_EXECUTION_STATUS_FAILED` | 3 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. | | `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 4 | Canonical | The tool call is waiting for approval before it can execute. | | `TOOL_EXECUTION_STATUS_CANCELLED` | 5 | Canonical | The tool call was cancelled before normal completion. | | `TOOL_EXECUTION_STATUS_TIMED_OUT` | 6 | Canonical | Tool execution ended because its time limit elapsed. |
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_EXECUTION_STATUS_PENDING`, `TOOL_EXECUTION_STATUS_EXECUTING`, `TOOL_EXECUTION_STATUS_COMPLETED`, `TOOL_EXECUTION_STATUS_FAILED`, `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, `TOOL_EXECUTION_STATUS_CANCELLED`, `TOOL_EXECUTION_STATUS_TIMED_OUT` Variant 2: Type: `integer(int32)` **resultJson** `map[string, any]` Tool execution result (object). **executedAt** `string(date-time)` Time when the tool execution was recorded. **serverId** `string` Which server provides this tool (for MCP tools). **isClientTool** `boolean` True if this is a client-side tool handled by client. **description** `string` Tool description captured from the resolved tool definition when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. **parametersJsonSchema** `map[string, any]` JSON Schema describing the tool’s input arguments. **requiresApprovalAt** `string(date-time)` Deadline for an approval decision, calculated from the effective approval timeout. This is not the time the call began waiting. An approval received after the deadline is rejected. **approvedAt** `string(date-time)` Timestamp when approval decision was recorded (if approved/rejected) **approvedBy** `string` Identifier of the approver (user id, email, or actor key) **executionDuration** `string` End-to-end execution duration once terminal (includes tool server latency or client-side time) Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **endReason** `string` Why this call ended, in one short phrase — "approval rejected", "approval timeout", or the underlying error. Set only once `status` is terminal, and empty on a clean COMPLETED. Use this reason to distinguish a rejection from a failure without parsing the tool result. **clientToolDeadlineAt** `string(date-time)` Deadline by which the client must submit a result for this call, stamped when the call is dispatched to a caller. **name** `string` Name identifying the sender of the chat message. optional sender name **timestamp** `string(date-time)` Timestamp associated with the conversation message or event. **messageId** `string` Unique message identifier. **annotations** `array[llm_v1_common_v1_Annotation]` Structured annotations (e.g., standardized web search URL citations, PDF reuse tokens) Tagged provider annotation attached to generated content, such as a citation or PDF reference. Model reference: [Annotation](/api/models/schema-1i0hjer0pd#response). **kind** `any` Selected kind; determines which submessage is populated Kind of source annotation associated with generated content.
| Value | No. | Form | Meaning | |---|---|---|---| | `ANNOTATION_KIND_URL_CITATION` | 0 | Canonical | A citation to a source identified by its URL. | | `ANNOTATION_KIND_PDF` | 1 | Canonical | An annotation identifying source content in a PDF document. |
Exactly one of: Variant 1: Type: `string` Enum: `ANNOTATION_KIND_URL_CITATION`, `ANNOTATION_KIND_PDF` Variant 2: Type: `integer(int32)` **urlCitation** `any` Submessage fields (optional); populate the one matching kind All of: Variant 1: Web source and character range cited in generated message content. Model reference: [UrlCitation](/api/models/schema-1hujls61ng#response). **url** `string` URL of the cited web page. **title** `string` Title of the web page cited by this annotation. **content** `string` Optional excerpt or snippet of the cited web page. **startIndex** `string(int64)` Character index in message content. Pattern: ^-?\d+$ **endIndex** `string(int64)` Character index in message content. Pattern: ^-?\d+$ **pdf** `any` PDF annotation identifying the parsed file and available parsing output. All of: Variant 1: Provider annotation identifying a parsed PDF and reusable parsing output. Model reference: [PdfAnnotation](/api/models/schema-1hsi58i6pb#response). **filename** `string` Optional identifying information about the original file **engine** `string` PDF parsing engine used by provider (e.g., "pdf-text", "mistral-ocr", "native") **token** `string` Opaque provider token or handle allowing reuse without re-parsing **sourceUrl** `string` Optional: original source reference (public URL or data: URL) **hash** `string` Provider-supplied hash identifying the parsed file. **content** `array[llm_v1_common_v1_ContentPart]` Optional structured content returned by provider annotations (text, image URLs, etc.) Note: This can be large; include only if you need to round-trip provider annotations. Content parts composing a message, using a flattened structure for JSON compatibility. The `type` identifies how the content is represented; only defined content types are accepted. Model reference: [ContentPart](/api/models/schema-1hqi9r2bhh#response). **type** `any` Kind of content carried by this message part. Discriminator identifying which content representation a message part carries.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTENT_PART_TYPE_TEXT` | 0 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_URL` | 1 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_BASE64` | 2 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_ID` | 3 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_PATH` | 4 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_URL` | 5 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_DATA_URL` | 6 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_AUDIO_BASE64` | 7 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_REASONING` | 8 | Canonical | See meaning below. | **`CONTENT_PART_TYPE_TEXT`** Plain text carried by the content part. Plain text content **`CONTENT_PART_TYPE_IMAGE_URL`** An image supplied through a remote URL. Remote image URL **`CONTENT_PART_TYPE_IMAGE_BASE64`** An image supplied as base64-encoded bytes. Base64-encoded image data **`CONTENT_PART_TYPE_FILE_ID`** A provider file identifier or internal storage identifier resolved before generation. File ID — a provider file ID (e.g., OpenAI) OR an internal storage file ID; resolved to a signed FILE\_URL just-in-time before the model-provider request **`CONTENT_PART_TYPE_FILE_PATH`** A reference to a local file path. Local file path reference **`CONTENT_PART_TYPE_FILE_URL`** A file supplied through a public or signed URL. Public or signed file URL (e.g., PDF URL or data: URL) **`CONTENT_PART_TYPE_FILE_DATA_URL`** A file embedded in a data URL, including its media type and encoded data. data\:application/pdf;base64,... or similar **`CONTENT_PART_TYPE_AUDIO_BASE64`** Base64-encoded audio; the part metadata identifies its audio format. Base64-encoded audio (metadata.format required, e.g., wav/mp3) **`CONTENT_PART_TYPE_REASONING`** A reasoning segment returned by a model provider, when available. Reasoning/thinking content from chain-of-thought models
Exactly one of: Variant 1: Type: `string` Enum: `CONTENT_PART_TYPE_TEXT`, `CONTENT_PART_TYPE_IMAGE_URL`, `CONTENT_PART_TYPE_IMAGE_BASE64`, `CONTENT_PART_TYPE_FILE_ID`, `CONTENT_PART_TYPE_FILE_PATH`, `CONTENT_PART_TYPE_FILE_URL`, `CONTENT_PART_TYPE_FILE_DATA_URL`, `CONTENT_PART_TYPE_AUDIO_BASE64`, `CONTENT_PART_TYPE_REASONING` Variant 2: Type: `integer(int32)` **content** `string` Text content, image URL, file ID, or base64-encoded data. **metadata** `map[string, string]` Additional type-specific metadata (dimensions, mime\_type, etc.). **cachePreferred** `boolean` Hint that this part is eligible for provider prompt caching. **structuredMessage** `any` Populated on TEXT parts for structured output responses. All of: Variant 1: A structured message whose JSON payload has been validated against a declared schema. Consumers can trust that json\_payload conforms to the schema identified by schema\_name. Inspect the run outcome before treating any message as complete. Current structured metadata is attached to a text content part through [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage) can be absent. Use an object at the schema root and validate the exact final response your application consumes; server validation covers only the first model choice. For integers that your JSON client cannot represent exactly, define string-valued fields in your schema instead of converting them through floating point. Model reference: [StructuredMessage](/api/models/schema-1ho1lk4ndj#response). **jsonPayload** `map[string, any]` The validated JSON payload as a Struct (preserves types) **schemaName** `string` Schema identifier (from ResponseFormat.schema\_name) **healed** `boolean` Whether response healing is reported for this structured message. Currently returned as false. **metadata** `map[string, string]` Provider-specific extras. **sequence** `string(int64)` Monotonic, per-conversation sequence number for stable ordering (1-based) Pattern: ^-?\d+$ **generatedBy** `string` Workflow run id or generator key that produced this message (e.g., workflow run key) **usage** `any` Token usage for this generation (populated for assistant messages) All of: Variant 1: Usage accounting Model reference: [Usage](/api/models/schema-1j1vov2uoh#response). **promptTokens** `string(int64)` Prompt-token usage reported by the model provider. Pattern: ^-?\d+$ **completionTokens** `string(int64)` Completion-token usage reported by the model provider. Pattern: ^-?\d+$ **totalTokens** `string(int64)` Total token usage reported by the model provider. Pattern: ^-?\d+$ **costEstimate** `any` Estimated cost in USD. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completionTokensDetails** `any` Breakdown of completion tokens. All of: Variant 1: Breakdown of completion-token usage. Categories are measured by different upstream tokenizers and need not sum to completion\_tokens; reasoning\_tokens can exceed completion\_tokens. One category must not be derived by subtracting the others. Model reference: [CompletionTokensDetails](/api/models/schema-1i6q4qpg72#response). **reasoningTokens** `string(int64)` Tokens used for reasoning/thinking. Pattern: ^-?\d+$ **imageTokens** `string(int64)` Completion tokens emitted as image output. Pattern: ^-?\d+$ **audioTokens** `string(int64)` Completion tokens emitted as audio output. Pattern: ^-?\d+$ **promptTokensDetails** `any` Breakdown of prompt tokens (cache). All of: Variant 1: Breakdown of prompt token usage by category (input-side cache accounting) Subset semantics: cached\_tokens and cache\_write\_tokens are a breakdown *of* prompt\_tokens, so cached\_tokens + cache\_write\_tokens \<= Usage.prompt\_tokens. Ordinary (full-rate) prompt tokens = prompt\_tokens - cached\_tokens - cache\_write\_tokens. audio\_tokens / video\_tokens are modality breakdowns of prompt\_tokens (also a subset). Model reference: [PromptTokensDetails](/api/models/schema-1ivj82m55o#response). **cachedTokens** `string(int64)` Prompt tokens served from cache (cache READ). Pattern: ^-?\d+$ **cacheWriteTokens** `string(int64)` Prompt tokens written to cache this call (cache WRITE). Pattern: ^-?\d+$ **audioTokens** `string(int64)` Prompt tokens from audio input (multimodal). Pattern: ^-?\d+$ **videoTokens** `string(int64)` Prompt tokens from video input (multimodal). Pattern: ^-?\d+$ **costDetails** `any` Breakdown of upstream provider cost (BYOK routes). All of: Variant 1: Breakdown of model-provider cost. When the customer supplies the provider key, usage.cost is zero and upstream\_inference\_cost reports the provider spend, split into prompt and completion components. Model reference: [CostDetails](/api/models/schema-1ia0h761lm#response). **upstreamInferenceCost** `any` Total upstream provider cost (USD) on BYOK routes. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferencePromptCost** `any` Upstream cost attributed to prompt tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferenceCompletionCost** `any` Upstream cost attributed to completion tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **isByok** `boolean` Whether this generation used the customer's own model-provider key. **model** `string` Model that generated this message (e.g., "anthropic/claude-sonnet-4") **generationContext** `any` Dynamic context that shaped this generation (memories, search params, turn info) All of: Variant 1: Snapshot of retrieval inputs, prompt provenance, and turn position that shaped a generated message. Model reference: [GenerationContext](/api/models/schema-1im79fphmq#response). **memories** `array[llm_v1_common_v1_MemoryReference]` Memory records captured in the generation context. A memory record retrieved and included in generation context. Model reference: [MemoryReference](/api/models/schema-1ie9a4bgk5#response). **memoryId** `string` Identifier of the retrieved memory record. **score** `any` Relevance score reported by the memory provider for this match. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **memoryText** `string` Text of the retrieved memory record. **createdAt** `string(date-time)` Time when this record was created. **updatedAt** `string(date-time)` Time when this record was last updated. **relations** `array[llm_v1_common_v1_RelationReference]` Graph relationships captured in the generation context. A graph relationship retrieved and included in generation context. Model reference: [RelationReference](/api/models/schema-1ijit8ceuv#response). **source** `string` Source entity of the memory graph relationship. **relationship** `string` Relationship label connecting the source and destination entities. **destination** `string` Destination entity of the memory graph relationship. **memorySearch** `any` Memory-query parameters and counts recorded for this generation. All of: Variant 1: Parameters used to retrieve relevant memories during generation. Model reference: [MemorySearchParams](/api/models/schema-1igd5iut01#response). **query** `string` Text submitted to memory retrieval for this generation. **topK** `string(int64)` Maximum memory matches requested during generation-context retrieval. Pattern: ^-?\d+$ **threshold** `any` Minimum relevance threshold requested for the memory query. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **rerank** `boolean` Whether reranking was requested for the memory search. **resultsReturned** `string(int64)` Number of memory records returned by the search. Pattern: ^-?\d+$ **relationsReturned** `string(int64)` Number of graph relationships returned by the search. Pattern: ^-?\d+$ **turn** `any` Turn position and limit within the generation run. All of: Variant 1: Turn position within an agentic generation run Model reference: [TurnInfo](/api/models/schema-1ilcikuhu8#response). **currentTurn** `string(int64)` Current turn position within the generation run. Pattern: ^-?\d+$ **maxTurns** `string(int64)` Maximum turns configured for the generation run. Pattern: ^-?\d+$ **languagePreference** `string` Language preference associated with the generation context. **resolvedSystemPrompt** `string` System prompt selected for this generation after prompt precedence is resolved. This field is retained in the schema but is not populated; use resolved\_prompt\_hash for recorded prompt identity. **profileId** `string` Agent profile that produced this message ("" if none active). **model** `string` Model actually used for this generation. **promptSource** `any` Which precedence tier supplied the prompt. Source that supplied the effective system prompt for a generation turn. Distinguishes a client override, a profile template and the conversation default configuration for prompt attribution.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROMPT_SOURCE_CLIENT_OVERRIDE` | 0 | Canonical | See meaning below. | | `PROMPT_SOURCE_PROFILE_TEMPLATE` | 1 | Canonical | See meaning below. | | `PROMPT_SOURCE_DEFAULT_CONFIG` | 2 | Canonical | See meaning below. | **`PROMPT_SOURCE_CLIENT_OVERRIDE`** The caller supplied the prompt through the send request's generation-configuration override. SendRequest.override\_generation\_config **`PROMPT_SOURCE_PROFILE_TEMPLATE`** The prompt was rendered from the active agent profile template. active agent profile's rendered template **`PROMPT_SOURCE_DEFAULT_CONFIG`** The prompt came from the conversation or project default generation configuration. conversation/project default\_generation\_config
Exactly one of: Variant 1: Type: `string` Enum: `PROMPT_SOURCE_CLIENT_OVERRIDE`, `PROMPT_SOURCE_PROFILE_TEMPLATE`, `PROMPT_SOURCE_DEFAULT_CONFIG` Variant 2: Type: `integer(int32)` **baseConfig** `any` Generation configuration resolved at send time before per-call overrides and timeout adjustments, with system\_prompt omitted. The active profile supplies the base when selected; otherwise the conversation default does. Use prompt\_source and profile\_id for prompt attribution. The base configuration can be absent when neither source supplies one or no snapshot was captured. For a supplied per-call override, the populated top-level fields of override\_config overlay base\_config to form the effective configuration. override\_config can be absent when no override was supplied. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#response). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#response). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#response). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#response). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#response). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#response). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#response). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinition]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#response). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfig]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#response). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#response). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#response). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#response). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#response). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#response). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#response). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#response). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **overrideConfig** `any` Per-call generation configuration supplied before the override merge. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#response). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#response). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#response). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#response). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#response). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#response). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#response). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinition]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#response). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfig]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#response). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#response). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#response). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#response). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#response). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#response). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#response). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#response). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **profileVersion** `string(int64)` Immutable version of the active agent profile used to render this turn’s prompt. Absent on older turns and turns without a profile template. Pattern: ^-?\d+$ **fragmentsVersion** `string(int64)` Version of the prompt-fragment set used to render the profile prompt. Pattern: ^-?\d+$ **promptVariables** `map[string, any]` Values bound to the prompt template for this generation. **profileRenderFailed** `boolean` Whether rendering the profile prompt failed for this generation. **resolvedPromptHash** `string` SHA-256 hash, as 64 hexadecimal characters, of the resolved system prompt before the current-time instruction is appended. Identifies prompt content only, excluding model and sampling parameters. Absent on older turns without prompt capture. **resolvedUserContext** `string` The literal user-context text supplied to the model for this turn, including the available name, locale and location conditions. It is a captured prompt input, not a reconstruction from the user’s current profile. The value is computed once per turn and reused across its model calls. It can be empty when location context is unavailable, enrichment fails or the turn predates capture. **resolvedMcpServers** `array[llm_v1_common_v1_MCPServerReference]` The MCP server list used for this turn after resolving conversation settings, the active profile, and any per-turn `override_mcp_servers`. It determines both tool discovery and the allow/block rules applied by `CallTool`. A per-turn override does not change the conversation's stored MCP settings. Compare this snapshot with `settings.mcp_servers` to inspect how the turn's tool set differed. Empty on turns predating capture and on threads with no MCP servers. MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#response). **serverId** `string` ID of pre-configured MCP server (e.g., "github", "filesystem"). **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **clientContext** `any` Arbitrary client-supplied context attached by the client for this message All of: Variant 1: Opaque caller-supplied attributes attached to a conversation message. Values are strings, including values such as `"false"`. The schema allows at most 32 pairs, keys of at most 64 characters, and values of at most 1,024 characters. Keep the entire map well below 8 KiB: Travila also applies an encoded-size limit that includes field overhead and drops context that exceeds it. Short page identifiers and a few relevant values are preferable to a page dump; an oversized map is not automatically shortened. Model reference: [ClientContext](/api/models/schema-1i2sndrl93#response). **values** `map[string, string]` Arbitrary client-supplied context for this message (e.g. page, referrer, device, in-app flow). Keys/values are opaque strings. **feedback** `array[llm_v1_common_v1_MessageFeedback]` Feedback on an assistant message, with one entry per rater identified by rated\_by. A later rating by the same rater replaces their earlier entry. One user's feedback on an assistant-generated message. kind must select a listed feedback representation. Requiredness and allowed values are declared separately. Model reference: [MessageFeedback](/api/models/schema-1iroqctqt1#response). **kind** `any` Rating representation used to interpret the feedback value. Value scale used to interpret recorded feedback.
| Value | No. | Form | Meaning | |---|---|---|---| | `FEEDBACK_KIND_THUMB` | 0 | Canonical | See meaning below. | | `FEEDBACK_KIND_SCALE` | 1 | Canonical | See meaning below. | **`FEEDBACK_KIND_THUMB`** Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. binary thumbs up / down **`FEEDBACK_KIND_SCALE`** Feedback expressed as an integer rating from 1 through 10. 1-10 integer scale
Exactly one of: Variant 1: Type: `string` Enum: `FEEDBACK_KIND_THUMB`, `FEEDBACK_KIND_SCALE` Variant 2: Type: `integer(int32)` **thumbUp** `boolean` Positive when true and negative when false; used for THUMB feedback. **rating** `string(int64)` Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent. Pattern: ^-?\d+$ **reason** `string` Optional explanation for the rating. **ratedAt** `string(date-time)` Timestamp when feedback was submitted (server-set) **ratedBy** `string` Identifier of the user who submitted this feedback. Set by the server from the authenticated user identity; never client-supplied. Each user has one feedback entry per message. **sourceUserMessageId** `string` Identifier of the user message that opened this conversation turn. Generated messages in the same turn share this value; a user message carries its own message\_id. Empty on historical messages that predate turn attribution. Use this field for turn attribution rather than inferring it from message adjacency or a client-supplied message\_id. The generated\_by identifier groups messages by generation run but does not identify the user message that opened the turn. **finishReason** `string` Why the model stopped, verbatim from the provider: "stop", "tool\_calls", "length", "error". Empty for historical messages. **status** `any` Generation status reported when the synchronous wait returns. Execution state of an agent generation run, separate from the reason a terminal run ended. The terminal states are COMPLETED, FAILED, CANCELLED and TIMED\_OUT. Treat every other or unrecognized value as non-terminal. Reasons such as rejected, malformed or discarded belong in the reason field rather than in this status.
| Value | No. | Form | Meaning | |---|---|---|---| | `AGENT_STATUS_ACTIVE` | 0 | Canonical | The run is active and has not yet reached a more specific execution phase or terminal outcome. | | `AGENT_STATUS_GENERATING` | 1 | Canonical | The run is generating a model response. | | `AGENT_STATUS_EXECUTING_TOOLS` | 2 | Canonical | The run is executing server-side tools. | | `AGENT_STATUS_COMPLETED` | 3 | Canonical | The run finished successfully. | | `AGENT_STATUS_FAILED` | 4 | Canonical | The run ended with a failure; inspect its error or end reason. | | `AGENT_STATUS_QUEUED` | 5 | Canonical | See meaning below. | | `AGENT_STATUS_AWAITING_CLIENT_TOOLS` | 6 | Canonical | The run is waiting for the caller to execute client-side tools and submit their results. This is a non-terminal phase. EXECUTING\_TOOLS instead means the server is running an MCP tool. | | `AGENT_STATUS_CANCELLED` | 7 | Canonical | See meaning below. | | `AGENT_STATUS_TIMED_OUT` | 8 | Canonical | See meaning below. | **`AGENT_STATUS_QUEUED`** The incoming message is queued behind an ongoing run under the queue interruption policy. Message was queued due to QUEUE interrupt policy **`AGENT_STATUS_CANCELLED`** The run ended because a client or its invocation cancelled it. Terminal: stopped by a client cancel or a cancelled invocation **`AGENT_STATUS_TIMED_OUT`** The run ended because a run-level time limit elapsed. Terminal: a run-level bound elapsed
Exactly one of: Variant 1: Type: `string` Enum: `AGENT_STATUS_ACTIVE`, `AGENT_STATUS_GENERATING`, `AGENT_STATUS_EXECUTING_TOOLS`, `AGENT_STATUS_COMPLETED`, `AGENT_STATUS_FAILED`, `AGENT_STATUS_QUEUED`, `AGENT_STATUS_AWAITING_CLIENT_TOOLS`, `AGENT_STATUS_CANCELLED`, `AGENT_STATUS_TIMED_OUT` Variant 2: Type: `integer(int32)` **aggregateUsage** `any` Aggregated model usage reported for the generation run. All of: Variant 1: Usage accounting Model reference: [Usage](/api/models/schema-1j1vov2uoh#response). **promptTokens** `string(int64)` Prompt-token usage reported by the model provider. Pattern: ^-?\d+$ **completionTokens** `string(int64)` Completion-token usage reported by the model provider. Pattern: ^-?\d+$ **totalTokens** `string(int64)` Total token usage reported by the model provider. Pattern: ^-?\d+$ **costEstimate** `any` Estimated cost in USD. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completionTokensDetails** `any` Breakdown of completion tokens. All of: Variant 1: Breakdown of completion-token usage. Categories are measured by different upstream tokenizers and need not sum to completion\_tokens; reasoning\_tokens can exceed completion\_tokens. One category must not be derived by subtracting the others. Model reference: [CompletionTokensDetails](/api/models/schema-1i6q4qpg72#response). **reasoningTokens** `string(int64)` Tokens used for reasoning/thinking. Pattern: ^-?\d+$ **imageTokens** `string(int64)` Completion tokens emitted as image output. Pattern: ^-?\d+$ **audioTokens** `string(int64)` Completion tokens emitted as audio output. Pattern: ^-?\d+$ **promptTokensDetails** `any` Breakdown of prompt tokens (cache). All of: Variant 1: Breakdown of prompt token usage by category (input-side cache accounting) Subset semantics: cached\_tokens and cache\_write\_tokens are a breakdown *of* prompt\_tokens, so cached\_tokens + cache\_write\_tokens \<= Usage.prompt\_tokens. Ordinary (full-rate) prompt tokens = prompt\_tokens - cached\_tokens - cache\_write\_tokens. audio\_tokens / video\_tokens are modality breakdowns of prompt\_tokens (also a subset). Model reference: [PromptTokensDetails](/api/models/schema-1ivj82m55o#response). **cachedTokens** `string(int64)` Prompt tokens served from cache (cache READ). Pattern: ^-?\d+$ **cacheWriteTokens** `string(int64)` Prompt tokens written to cache this call (cache WRITE). Pattern: ^-?\d+$ **audioTokens** `string(int64)` Prompt tokens from audio input (multimodal). Pattern: ^-?\d+$ **videoTokens** `string(int64)` Prompt tokens from video input (multimodal). Pattern: ^-?\d+$ **costDetails** `any` Breakdown of upstream provider cost (BYOK routes). All of: Variant 1: Breakdown of model-provider cost. When the customer supplies the provider key, usage.cost is zero and upstream\_inference\_cost reports the provider spend, split into prompt and completion components. Model reference: [CostDetails](/api/models/schema-1ia0h761lm#response). **upstreamInferenceCost** `any` Total upstream provider cost (USD) on BYOK routes. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferencePromptCost** `any` Upstream cost attributed to prompt tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferenceCompletionCost** `any` Upstream cost attributed to completion tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **isByok** `boolean` Whether this generation used the customer's own model-provider key. **error** `any` Structured error for partial success scenarios (some messages generated before failure). Full failures propagate as TerminalError → HTTP error status + RpcError JSON body. All of: Variant 1: Error payload containing an API-defined error code, a message and structured details. Interpret `code` using the ErrorCode enumeration published with this API; numeric equivalence with `google.rpc.Status` is not implied. Model reference: [RpcError](/api/models/schema-1fajlacjs0#response). **code** `any` Machine-readable error code. Clients switch on this field. API-defined categories describing why a request or operation failed. Use the published symbolic name and accompanying error details. These numeric assignments are not interchangeable with `google.rpc.Code`.
| Value | No. | Form | Meaning | |---|---|---|---| | `ERROR_CODE_CANCELLED` | 0 | Canonical | See meaning below. | | `ERROR_CODE_UNKNOWN` | 1 | Canonical | See meaning below. | | `ERROR_CODE_INVALID_ARGUMENT` | 2 | Canonical | See meaning below. | | `ERROR_CODE_DEADLINE_EXCEEDED` | 3 | Canonical | See meaning below. | | `ERROR_CODE_NOT_FOUND` | 4 | Canonical | See meaning below. | | `ERROR_CODE_ALREADY_EXISTS` | 5 | Canonical | See meaning below. | | `ERROR_CODE_PERMISSION_DENIED` | 6 | Canonical | See meaning below. | | `ERROR_CODE_RESOURCE_EXHAUSTED` | 7 | Canonical | See meaning below. | | `ERROR_CODE_FAILED_PRECONDITION` | 8 | Canonical | See meaning below. | | `ERROR_CODE_ABORTED` | 9 | Canonical | See meaning below. | | `ERROR_CODE_OUT_OF_RANGE` | 10 | Canonical | See meaning below. | | `ERROR_CODE_UNIMPLEMENTED` | 11 | Canonical | See meaning below. | | `ERROR_CODE_INTERNAL` | 12 | Canonical | See meaning below. | | `ERROR_CODE_UNAVAILABLE` | 13 | Canonical | See meaning below. | | `ERROR_CODE_DATA_LOSS` | 14 | Canonical | See meaning below. | | `ERROR_CODE_UNAUTHENTICATED` | 15 | Canonical | See meaning below. | | `ERROR_CODE_MODEL_INVALID` | 16 | Canonical | See meaning below. | | `ERROR_CODE_MODEL_UNAVAILABLE` | 17 | Canonical | See meaning below. | | `ERROR_CODE_MODERATION_FLAGGED` | 18 | Canonical | See meaning below. | | `ERROR_CODE_GENERATION_FAILED` | 19 | Canonical | See meaning below. | | `ERROR_CODE_TOOL_EXECUTION_FAILED` | 20 | Canonical | See meaning below. | | `ERROR_CODE_UPSTREAM_PROVIDER` | 21 | Canonical | See meaning below. | | `ERROR_CODE_VALIDATION_EXHAUSTED` | 22 | Canonical | See meaning below. | | `ERROR_CODE_PAYMENT_REQUIRED` | 23 | Canonical | See meaning below. | **`ERROR_CODE_CANCELLED`** The caller cancelled the operation before it completed. Canonical error categories. 499 — Cancelled by caller **`ERROR_CODE_UNKNOWN`** The operation failed without a more specific error classification. 500 — Unknown error **`ERROR_CODE_INVALID_ARGUMENT`** The request contains an invalid argument or field value. 400 — Bad input, invalid field values **`ERROR_CODE_DEADLINE_EXCEEDED`** The operation did not complete before its deadline. 504 — Operation timed out **`ERROR_CODE_NOT_FOUND`** The requested resource does not exist or could not be found. 404 — Resource does not exist **`ERROR_CODE_ALREADY_EXISTS`** The requested creation conflicts with a resource that already exists. 409 — Resource already exists **`ERROR_CODE_PERMISSION_DENIED`** The authenticated caller is not permitted to perform the operation. 403 — Caller lacks permission **`ERROR_CODE_RESOURCE_EXHAUSTED`** A quota, rate limit or other capacity limit prevented the operation. 429 — Rate limited or quota exceeded **`ERROR_CODE_FAILED_PRECONDITION`** The operation requires a system or resource state that is not currently satisfied. 400 — System not in required state **`ERROR_CODE_ABORTED`** The operation was aborted, for example by a concurrent modification conflict. 409 — Concurrent conflict, retry may succeed **`ERROR_CODE_OUT_OF_RANGE`** An argument is outside the range supported by this operation. 400 — Value outside valid range **`ERROR_CODE_UNIMPLEMENTED`** The requested operation is not implemented. 501 — Not implemented **`ERROR_CODE_INTERNAL`** An internal failure prevented the operation from completing. 500 — Internal error **`ERROR_CODE_UNAVAILABLE`** The service or a required dependency is temporarily unavailable. 503 — Service temporarily unavailable **`ERROR_CODE_DATA_LOSS`** The operation encountered unrecoverable loss or corruption of data. 500 — Unrecoverable data loss **`ERROR_CODE_UNAUTHENTICATED`** Authentication credentials are missing or invalid. 401 — Missing or invalid credentials **`ERROR_CODE_MODEL_INVALID`** The requested model identifier is absent from the model catalog. Domain-specific error categories. 400 — Model ID not found in catalog **`ERROR_CODE_MODEL_UNAVAILABLE`** The model exists, but no provider is currently available to serve it. 503 — Model exists but all providers are down **`ERROR_CODE_MODERATION_FLAGGED`** Content moderation flagged the submitted content. 403 — Input flagged by content moderation **`ERROR_CODE_GENERATION_FAILED`** Model generation failed after its configured attempts. 500 — LLM generation failed after retries **`ERROR_CODE_TOOL_EXECUTION_FAILED`** Execution of a requested tool failed. 500 — MCP tool call failed **`ERROR_CODE_UPSTREAM_PROVIDER`** An upstream model provider returned an error. 503 — Upstream provider returned error **`ERROR_CODE_VALIDATION_EXHAUSTED`** Structured-output validation still failed after the configured attempts. 500 — Structured output validation failed after all retries **`ERROR_CODE_PAYMENT_REQUIRED`** The account lacks the credits required for the operation. 402 — Insufficient credits
Exactly one of: Variant 1: Type: `string` Enum: `ERROR_CODE_CANCELLED`, `ERROR_CODE_UNKNOWN`, `ERROR_CODE_INVALID_ARGUMENT`, `ERROR_CODE_DEADLINE_EXCEEDED`, `ERROR_CODE_NOT_FOUND`, `ERROR_CODE_ALREADY_EXISTS`, `ERROR_CODE_PERMISSION_DENIED`, `ERROR_CODE_RESOURCE_EXHAUSTED`, `ERROR_CODE_FAILED_PRECONDITION`, `ERROR_CODE_ABORTED`, `ERROR_CODE_OUT_OF_RANGE`, `ERROR_CODE_UNIMPLEMENTED`, `ERROR_CODE_INTERNAL`, `ERROR_CODE_UNAVAILABLE`, `ERROR_CODE_DATA_LOSS`, `ERROR_CODE_UNAUTHENTICATED`, `ERROR_CODE_MODEL_INVALID`, `ERROR_CODE_MODEL_UNAVAILABLE`, `ERROR_CODE_MODERATION_FLAGGED`, `ERROR_CODE_GENERATION_FAILED`, `ERROR_CODE_TOOL_EXECUTION_FAILED`, `ERROR_CODE_UPSTREAM_PROVIDER`, `ERROR_CODE_VALIDATION_EXHAUSTED`, `ERROR_CODE_PAYMENT_REQUIRED` Variant 2: Type: `integer(int32)` **message** `string` Human-readable error description. Intended for developers, not end users. Must not be parsed programmatically — use code and details instead. **isTerminal** `boolean` Whether this error is classified as terminal (non-retryable). A terminal error should not trigger automatic retries of the failed operation. A nonterminal error may reflect a transient condition that can resolve on retry. **details** `any` Structured error details. At most one of each detail type. All of: Variant 1: Typed error details container. Concrete fields instead of Any for type safety across languages. At most one of each detail type. Model reference: [ErrorDetails](/api/models/schema-1f7d7kh0s1#response). **errorInfo** `any` Identifies the error for machine consumption. Required on all errors by this error contract. All of: Variant 1: Machine-readable error identification (per AIP-193, every error must include this). Model reference: [ErrorInfo](/api/models/schema-1es9uii84j#response). **reason** `string` Stable machine-readable reason string (e.g., "MODEL\_NOT\_FOUND", "RATE\_LIMITED", "MODERATION\_FLAGGED"). Unique within the domain. Clients may switch on this field. **domain** `string` Machine-readable namespace identifying the origin of the error. **metadata** `map[string, string]` Arbitrary key-value metadata. If the message field mentions a specific value (model name, field path, etc.), it MUST also appear here. **retryInfo** `any` Retry guidance for transient errors. All of: Variant 1: Retry guidance for transient errors. Model reference: [RetryInfo](/api/models/schema-1f439vae2d#response). **retryDelayMs** `string(int64)` Suggested minimum delay before retrying, in milliseconds. Pattern: ^-?\d+$ **fieldViolations** `array[common_v1_FieldViolation]` Field-level validation failures. A single field-level validation violation. Model reference: [FieldViolation](/api/models/schema-1eu5noj3g1#response). **field** `string` Dot-separated path to the field (e.g., "generation\_config.model"). **description** `string` Human-readable description of the violation. **upstreamError** `any` Upstream provider error context. All of: Variant 1: Context from an upstream provider error, including the provider name when reported. Model reference: [UpstreamError](/api/models/schema-1f66rlcp5a#response). **provider** `string` Name of the upstream provider that reported the error. **statusCode** `string(int64)` HTTP status code returned by the provider. Pattern: ^-?\d+$ **rawBody** `string` Raw error body from the provider, truncated to 512 bytes. **modelError** `any` Model-specific error context. All of: Variant 1: Model-specific error context. Model reference: [ModelError](/api/models/schema-1f2939tg20#response). **modelId** `string` The model ID that caused the error. **reason** `string` Why the model failed (e.g., "invalid", "unavailable", "moderation\_flagged"). **alternativesTried** `array[string]` Alternative models that were tried or could be tried. Type: `string` **helpLinks** `array[common_v1_HelpLink]` Help links for error resolution. A help link for error resolution. Model reference: [HelpLink](/api/models/schema-1f0qdi91b8#response). **url** `string` URL to documentation or resolution guide. **description** `string` Description of what the link provides. **pendingClientTools** `array[llm_v1_common_v1_ToolCall]` Tool calls dispatched for execution by the client. A single structured tool call emitted by the model [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat) is the client answer window. Expiry ends that wait and rejects late results; the timeout policy determines the outcome. Model reference: [ToolCall](/api/models/schema-1it6mqsqoo#response). **id** `string` Provider-supplied call id. **name** `string` Name of the tool or function being invoked. **argumentsJson** `map[string, any]` JSON object payload. **status** `any` Execution status recorded for the tool call. Execution state of a tool call, including approval waiting and terminal outcomes. The terminal outcomes are COMPLETED, FAILED, CANCELLED and TIMED\_OUT; inspect ToolCall.end\_reason for why a call ended rather than treating the reason as another status. Use a listed execution status. The end reason explains the outcome separately from the status.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_EXECUTION_STATUS_PENDING` | 0 | Canonical | The tool call is waiting to begin execution. | | `TOOL_EXECUTION_STATUS_EXECUTING` | 1 | Canonical | The tool call is currently executing. | | `TOOL_EXECUTION_STATUS_COMPLETED` | 2 | Canonical | The tool call completed successfully. This is a terminal outcome. | | `TOOL_EXECUTION_STATUS_FAILED` | 3 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. | | `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 4 | Canonical | The tool call is waiting for approval before it can execute. | | `TOOL_EXECUTION_STATUS_CANCELLED` | 5 | Canonical | The tool call was cancelled before normal completion. | | `TOOL_EXECUTION_STATUS_TIMED_OUT` | 6 | Canonical | Tool execution ended because its time limit elapsed. |
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_EXECUTION_STATUS_PENDING`, `TOOL_EXECUTION_STATUS_EXECUTING`, `TOOL_EXECUTION_STATUS_COMPLETED`, `TOOL_EXECUTION_STATUS_FAILED`, `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, `TOOL_EXECUTION_STATUS_CANCELLED`, `TOOL_EXECUTION_STATUS_TIMED_OUT` Variant 2: Type: `integer(int32)` **resultJson** `map[string, any]` Tool execution result (object). **executedAt** `string(date-time)` Time when the tool execution was recorded. **serverId** `string` Which server provides this tool (for MCP tools). **isClientTool** `boolean` True if this is a client-side tool handled by client. **description** `string` Tool description captured from the resolved tool definition when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. **parametersJsonSchema** `map[string, any]` JSON Schema describing the tool’s input arguments. **requiresApprovalAt** `string(date-time)` Deadline for an approval decision, calculated from the effective approval timeout. This is not the time the call began waiting. An approval received after the deadline is rejected. **approvedAt** `string(date-time)` Timestamp when approval decision was recorded (if approved/rejected) **approvedBy** `string` Identifier of the approver (user id, email, or actor key) **executionDuration** `string` End-to-end execution duration once terminal (includes tool server latency or client-side time) Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **endReason** `string` Why this call ended, in one short phrase — "approval rejected", "approval timeout", or the underlying error. Set only once `status` is terminal, and empty on a clean COMPLETED. Use this reason to distinguish a rejection from a failure without parsing the tool result. **clientToolDeadlineAt** `string(date-time)` Deadline by which the client must submit a result for this call, stamped when the call is dispatched to a caller. **clientToolCursor** `string(int64)` Latest client-tool dispatch sequence represented by this response. Pattern: ^-?\d+$ #### conversations-sendMessageSync-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "runId": "example_123", "interruptedPriorRun": true, "messages": [ { "role": "ROLE_SYSTEM", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Example text", "cachePreferred": true } ], "toolCalls": [ { "id": "example_123", "name": "example", "status": "TOOL_EXECUTION_STATUS_PENDING", "serverId": "example_123", "isClientTool": true, "description": "example", "approvedBy": "example", "endReason": "example" } ], "name": "example", "timestamp": "2026-09-16T12:00:00Z", "messageId": "example_123", "annotations": [ { "kind": "ANNOTATION_KIND_URL_CITATION" } ], "sequence": "1", "generatedBy": "example", "usage": { "promptTokens": 1, "completionTokens": 1, "totalTokens": 1, "costEstimate": 1, "isByok": true }, "model": "example", "generationContext": { "languagePreference": "en-US", "resolvedSystemPrompt": "Example text", "profileId": "example_123", "model": "example", "promptSource": "PROMPT_SOURCE_CLIENT_OVERRIDE", "profileVersion": 1, "fragmentsVersion": 1, "profileRenderFailed": true, "resolvedPromptHash": "Example text", "resolvedUserContext": "Example text" }, "clientContext": {}, "feedback": [ { "kind": "FEEDBACK_KIND_THUMB", "thumbUp": true, "reason": "example", "ratedBy": "example" } ], "sourceUserMessageId": "example_123", "finishReason": "example" } ], "status": "AGENT_STATUS_ACTIVE", "aggregateUsage": { "promptTokens": 1, "completionTokens": 1, "totalTokens": 1, "costEstimate": 1, "completionTokensDetails": { "reasoningTokens": 1, "imageTokens": 1, "audioTokens": 1 }, "promptTokensDetails": { "cachedTokens": 1, "cacheWriteTokens": 1, "audioTokens": 1, "videoTokens": 1 }, "costDetails": { "upstreamInferenceCost": 1, "upstreamInferencePromptCost": 1, "upstreamInferenceCompletionCost": 1 }, "isByok": true }, "error": { "code": "ERROR_CODE_CANCELLED", "message": "example", "isTerminal": true, "details": {} }, "pendingClientTools": [ { "id": "example_123", "name": "example", "argumentsJson": { "example": "value" }, "status": "TOOL_EXECUTION_STATUS_PENDING", "resultJson": { "example": "value" }, "executedAt": "2026-09-16T12:00:00Z", "serverId": "example_123", "isClientTool": true, "description": "example", "parametersJsonSchema": { "example": "value" }, "requiresApprovalAt": "2026-09-16T12:00:00Z", "approvedAt": "2026-09-16T12:00:00Z", "approvedBy": "example", "executionDuration": "1s", "endReason": "example", "clientToolDeadlineAt": "2026-09-16T12:00:00Z" } ], "clientToolCursor": 1 } ``` #### cookbook-core-platform-scheduling-build-scheduled-agents-json-02-response Illustrative response for Step 3: Drive an agent turn from the callback. Replace example resource identifiers with your own authorized values. ```json { "runId": "9d4c2e1f-...", "status": "AGENT_STATUS_COMPLETED", "messages": [ { "role": "ROLE_ASSISTANT", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Here is your daily briefing…" } ], "generatedBy": "9d4c2e1f-..." } ], "aggregateUsage": { "promptTokens": 412, "completionTokens": 88, "totalTokens": 500 } } ``` #### cookbook-managed-agents-conversations-generation-json-04-response Illustrative response for Separate recipe: wait for a backend summary in the response. Replace example resource identifiers with your own authorized values. ```json { "runId": "9d4c...", "status": "AGENT_STATUS_COMPLETED", "messages": [ { "role": "ROLE_ASSISTANT", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "…" } ], "generatedBy": "9d4c..." } ], "aggregateUsage": { "promptTokens": 412, "completionTokens": 88, "totalTokens": 500 } } ``` #### cookbook-managed-agents-conversations-generation-json-05-response Illustrative response for Recover a summary that failed or returned no explanation. Replace example resource identifiers with your own authorized values. ```json { "runId": "9d4c...", "status": "AGENT_STATUS_FAILED" } ``` #### cookbook-managed-agents-delegation-approvals-build-agent-with-tools-json-02-response Illustrative response for Step 2: Ask to open the profile and retain the pending call. Replace example resource identifiers with your own authorized values. ```json { "runId": "64403669-5989-4ec3-ad9c-d84223f9679f", "status": "AGENT_STATUS_AWAITING_CLIENT_TOOLS", "clientToolCursor": 1, "pendingClientTools": [ { "id": "call_abc123", "name": "navigate_to", "argumentsJson": { "screen": "/profile" }, "isClientTool": true, "clientToolDeadlineAt": "2026-08-10T10:04:11Z" } ] } ``` #### cookbook-managed-agents-delegation-approvals-using-tools-json-02-response Illustrative response for Step 1: Receive the complete navigation call. Replace example resource identifiers with your own authorized values. ```json { "runId": "cf9f08e7-4486-41e1-bac1-b9428d1aeb85", "status": "AGENT_STATUS_AWAITING_CLIENT_TOOLS", "clientToolCursor": 1, "pendingClientTools": [ { "id": "call_306135", "name": "navigate_to", "argumentsJson": { "screen": "/profile" }, "isClientTool": true, "clientToolDeadlineAt": "2026-09-02T06:43:24.304Z" } ] } ``` Document ID: `DOC-MA-conversations-api-sendMessageSync`. [Section identities and revisions](/documentation-manifest.json). - Send a message and wait for the result: `DOC-MA-conversations-api-sendMessageSync#overview` - Request: `DOC-MA-conversations-api-sendMessageSync#request` - Responses: `DOC-MA-conversations-api-sendMessageSync#responses` --- # Send a message to a conversation URL: https://docs.travila.ai/api/conversations/send-message **POST** `/api/v1/llm/send-message` Sends a user message to the specified conversation thread. This appends the message to history and starts a generation workflow run. If a run is already in progress, behavior depends on the conversation's interrupt policy. See [Messages and run outcomes](/api/conversations/messages-and-runs) for status interpretation and recovery. Use this in a guide: [API Reference](/api) · [Build a support conversation the user can return to](/managed-agents/conversations) · [Let a customer navigate your app through chat](/managed-agents/delegation-approvals/build-agent-with-tools) · [Approve a tool action and finish the conversation](/managed-agents/delegation-approvals/using-tools) · [Build a reusable assistant profile](/managed-agents/profiles-prompts) · [Recover when no model can serve the request](/managed-agents/model-controls/errors) · [Build a research, bulk-summary or structured-summary flow](/managed-agents/model-controls/examples) · [Route an image question to a capable model](/managed-agents/model-controls/filtering) · [Keep a model on the providers you choose](/managed-agents/model-controls/provider-pinning) · [Add an optional reasoning panel to a chat reply](/managed-agents/model-controls/reasoning) · [Configuration precedence and plugins](/api/model-controls/configuration) · [Model routing and selection](/api/model-controls/routing) · [Control access with scopes](/core-platform/identity-access/scopes-permissions) · [Build an assistant that researches the web](/integrations/tools-connections) · [MCP server selection](/api/tools/selection) · [Summarize a customer’s uploaded report](/managed-agents/conversations/attachments) · [Build a signed-in support chat that survives reconnects](/managed-agents/conversations/build-chat-assistant) · [Explain the setting the customer is looking at](/managed-agents/conversations/client-context) · [Configure a support conversation that stays predictable](/managed-agents/conversations/configuration) · [Get a customer’s reply and recover an interrupted send](/managed-agents/conversations/generation) · [Complete your first support-chat turn](/managed-agents/conversations/quickstart) · [Restore a chat after the connection drops](/managed-agents/conversations/streaming/subscribing) · [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers) · [Messages and runs](/api/conversations/messages-and-runs) · [Profile selection and prompt versions](/api/agent-profiles/selection-and-versioning) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Conversation operations Input for starting an asynchronous generation from a user message. **conversationKey** `string` **required** Identifier of the conversation thread. Minimum length: 1 **userMessage** `any` **required** User message that starts the conversation turn. Required; its role is expected to be ROLE\_USER. All of: Variant 1: Chat message At least one of content or tool\_calls must contain an entry; both lists may be nonempty. role must select a listed message role. Requiredness and allowed values are declared separately. Model reference: [Message](/api/models/schema-1j3dcf7kvu#request). **role** `any` **required** Role of the participant that produced the chat message. Participant role attached to a conversation message and forwarded in model context.
| Value | No. | Form | Meaning | |---|---|---|---| | `ROLE_SYSTEM` | 0 | Canonical | Instructions or context provided as a system message. | | `ROLE_USER` | 1 | Canonical | Input supplied by the user or customer application. | | `ROLE_ASSISTANT` | 2 | Canonical | Content produced by the assistant, including its tool-call requests. | | `ROLE_TOOL` | 3 | Canonical | A tool result supplied back to the assistant. |
Exactly one of: Variant 1: Type: `string` Enum: `ROLE_SYSTEM`, `ROLE_USER`, `ROLE_ASSISTANT`, `ROLE_TOOL` Variant 2: Type: `integer(int32)` Enum: `0`, `1`, `2`, `3` **content** `array[llm_v1_common_v1_ContentPartInput]` Content parts composing the chat message. Content parts composing a message, using a flattened structure for JSON compatibility. The `type` identifies how the content is represented; only defined content types are accepted. Model reference: [ContentPart](/api/models/schema-1hqi9r2bhh#request). **type** `any` Kind of content carried by this message part. Discriminator identifying which content representation a message part carries.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTENT_PART_TYPE_TEXT` | 0 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_URL` | 1 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_BASE64` | 2 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_ID` | 3 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_PATH` | 4 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_URL` | 5 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_DATA_URL` | 6 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_AUDIO_BASE64` | 7 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_REASONING` | 8 | Canonical | See meaning below. | **`CONTENT_PART_TYPE_TEXT`** Plain text carried by the content part. Plain text content **`CONTENT_PART_TYPE_IMAGE_URL`** An image supplied through a remote URL. Remote image URL **`CONTENT_PART_TYPE_IMAGE_BASE64`** An image supplied as base64-encoded bytes. Base64-encoded image data **`CONTENT_PART_TYPE_FILE_ID`** A provider file identifier or internal storage identifier resolved before generation. File ID — a provider file ID (e.g., OpenAI) OR an internal storage file ID; resolved to a signed FILE\_URL just-in-time before the model-provider request **`CONTENT_PART_TYPE_FILE_PATH`** A reference to a local file path. Local file path reference **`CONTENT_PART_TYPE_FILE_URL`** A file supplied through a public or signed URL. Public or signed file URL (e.g., PDF URL or data: URL) **`CONTENT_PART_TYPE_FILE_DATA_URL`** A file embedded in a data URL, including its media type and encoded data. data\:application/pdf;base64,... or similar **`CONTENT_PART_TYPE_AUDIO_BASE64`** Base64-encoded audio; the part metadata identifies its audio format. Base64-encoded audio (metadata.format required, e.g., wav/mp3) **`CONTENT_PART_TYPE_REASONING`** A reasoning segment returned by a model provider, when available. Reasoning/thinking content from chain-of-thought models
Exactly one of: Variant 1: Type: `string` Enum: `CONTENT_PART_TYPE_TEXT`, `CONTENT_PART_TYPE_IMAGE_URL`, `CONTENT_PART_TYPE_IMAGE_BASE64`, `CONTENT_PART_TYPE_FILE_ID`, `CONTENT_PART_TYPE_FILE_PATH`, `CONTENT_PART_TYPE_FILE_URL`, `CONTENT_PART_TYPE_FILE_DATA_URL`, `CONTENT_PART_TYPE_AUDIO_BASE64`, `CONTENT_PART_TYPE_REASONING` Variant 2: Type: `integer(int32)` Enum: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8` **content** `string` Text content, image URL, file ID, or base64-encoded data. **metadata** `map[string, string]` Additional type-specific metadata (dimensions, mime\_type, etc.). **cachePreferred** `boolean` Hint that this part is eligible for provider prompt caching. **structuredMessage** `any` Populated on TEXT parts for structured output responses. All of: Variant 1: A structured message whose JSON payload has been validated against a declared schema. Consumers can trust that json\_payload conforms to the schema identified by schema\_name. Inspect the run outcome before treating any message as complete. Current structured metadata is attached to a text content part through [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage) can be absent. Use an object at the schema root and validate the exact final response your application consumes; server validation covers only the first model choice. For integers that your JSON client cannot represent exactly, define string-valued fields in your schema instead of converting them through floating point. Model reference: [StructuredMessage](/api/models/schema-1ho1lk4ndj#request). **jsonPayload** `map[string, any]` The validated JSON payload as a Struct (preserves types) **schemaName** `string` Schema identifier (from ResponseFormat.schema\_name) **healed** `boolean` Whether response healing is reported for this structured message. Currently returned as false. **toolCalls** `array[llm_v1_common_v1_ToolCallInput]` Assistant-to-tool invocations. A single structured tool call emitted by the model [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat) is the client answer window. Expiry ends that wait and rejects late results; the timeout policy determines the outcome. Model reference: [ToolCall](/api/models/schema-1it6mqsqoo#request). **id** `string` Provider-supplied call id. **name** `string` Name of the tool or function being invoked. **argumentsJson** `map[string, any]` JSON object payload. **status** `any` Execution status recorded for the tool call. Execution state of a tool call, including approval waiting and terminal outcomes. The terminal outcomes are COMPLETED, FAILED, CANCELLED and TIMED\_OUT; inspect ToolCall.end\_reason for why a call ended rather than treating the reason as another status. Use a listed execution status. The end reason explains the outcome separately from the status.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_EXECUTION_STATUS_PENDING` | 0 | Canonical | The tool call is waiting to begin execution. | | `TOOL_EXECUTION_STATUS_EXECUTING` | 1 | Canonical | The tool call is currently executing. | | `TOOL_EXECUTION_STATUS_COMPLETED` | 2 | Canonical | The tool call completed successfully. This is a terminal outcome. | | `TOOL_EXECUTION_STATUS_FAILED` | 3 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. | | `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 4 | Canonical | The tool call is waiting for approval before it can execute. | | `TOOL_EXECUTION_STATUS_CANCELLED` | 5 | Canonical | The tool call was cancelled before normal completion. | | `TOOL_EXECUTION_STATUS_TIMED_OUT` | 6 | Canonical | Tool execution ended because its time limit elapsed. |
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_EXECUTION_STATUS_PENDING`, `TOOL_EXECUTION_STATUS_EXECUTING`, `TOOL_EXECUTION_STATUS_COMPLETED`, `TOOL_EXECUTION_STATUS_FAILED`, `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, `TOOL_EXECUTION_STATUS_CANCELLED`, `TOOL_EXECUTION_STATUS_TIMED_OUT` Variant 2: Type: `integer(int32)` **resultJson** `map[string, any]` Tool execution result (object). **executedAt** `string(date-time)` Time when the tool execution was recorded. **serverId** `string` Which server provides this tool (for MCP tools). **isClientTool** `boolean` True if this is a client-side tool handled by client. **description** `string` Tool description captured from the resolved tool definition when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. **parametersJsonSchema** `map[string, any]` JSON Schema describing the tool’s input arguments. **requiresApprovalAt** `string(date-time)` Deadline for an approval decision, calculated from the effective approval timeout. This is not the time the call began waiting. An approval received after the deadline is rejected. **approvedAt** `string(date-time)` Timestamp when approval decision was recorded (if approved/rejected) **approvedBy** `string` Identifier of the approver (user id, email, or actor key) **executionDuration** `string` End-to-end execution duration once terminal (includes tool server latency or client-side time) Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **endReason** `string` Why this call ended, in one short phrase — "approval rejected", "approval timeout", or the underlying error. Set only once `status` is terminal, and empty on a clean COMPLETED. Use this reason to distinguish a rejection from a failure without parsing the tool result. **clientToolDeadlineAt** `string(date-time)` Deadline by which the client must submit a result for this call, stamped when the call is dispatched to a caller. **name** `string` Name identifying the sender of the chat message. optional sender name **timestamp** `string(date-time)` Timestamp associated with the conversation message or event. **messageId** `string` Unique message identifier. **annotations** `array[llm_v1_common_v1_AnnotationInput]` Structured annotations (e.g., standardized web search URL citations, PDF reuse tokens) Tagged provider annotation attached to generated content, such as a citation or PDF reference. Model reference: [Annotation](/api/models/schema-1i0hjer0pd#request). **kind** `any` Selected kind; determines which submessage is populated Kind of source annotation associated with generated content.
| Value | No. | Form | Meaning | |---|---|---|---| | `ANNOTATION_KIND_URL_CITATION` | 0 | Canonical | A citation to a source identified by its URL. | | `ANNOTATION_KIND_PDF` | 1 | Canonical | An annotation identifying source content in a PDF document. |
Exactly one of: Variant 1: Type: `string` Enum: `ANNOTATION_KIND_URL_CITATION`, `ANNOTATION_KIND_PDF` Variant 2: Type: `integer(int32)` **urlCitation** `any` Submessage fields (optional); populate the one matching kind All of: Variant 1: Web source and character range cited in generated message content. Model reference: [UrlCitation](/api/models/schema-1hujls61ng#request). **url** `string` URL of the cited web page. **title** `string` Title of the web page cited by this annotation. **content** `string` Optional excerpt or snippet of the cited web page. **startIndex** `string(int64)` Character index in message content. Pattern: ^-?\d+$ **endIndex** `string(int64)` Character index in message content. Pattern: ^-?\d+$ **pdf** `any` PDF annotation identifying the parsed file and available parsing output. All of: Variant 1: Provider annotation identifying a parsed PDF and reusable parsing output. Model reference: [PdfAnnotation](/api/models/schema-1hsi58i6pb#request). **filename** `string` Optional identifying information about the original file **engine** `string` PDF parsing engine used by provider (e.g., "pdf-text", "mistral-ocr", "native") **token** `string` Opaque provider token or handle allowing reuse without re-parsing **sourceUrl** `string` Optional: original source reference (public URL or data: URL) **hash** `string` Provider-supplied hash identifying the parsed file. **content** `array[llm_v1_common_v1_ContentPartInput]` Optional structured content returned by provider annotations (text, image URLs, etc.) Note: This can be large; include only if you need to round-trip provider annotations. Content parts composing a message, using a flattened structure for JSON compatibility. The `type` identifies how the content is represented; only defined content types are accepted. Model reference: [ContentPart](/api/models/schema-1hqi9r2bhh#request). **type** `any` Kind of content carried by this message part. Discriminator identifying which content representation a message part carries.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTENT_PART_TYPE_TEXT` | 0 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_URL` | 1 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_BASE64` | 2 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_ID` | 3 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_PATH` | 4 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_URL` | 5 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_DATA_URL` | 6 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_AUDIO_BASE64` | 7 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_REASONING` | 8 | Canonical | See meaning below. | **`CONTENT_PART_TYPE_TEXT`** Plain text carried by the content part. Plain text content **`CONTENT_PART_TYPE_IMAGE_URL`** An image supplied through a remote URL. Remote image URL **`CONTENT_PART_TYPE_IMAGE_BASE64`** An image supplied as base64-encoded bytes. Base64-encoded image data **`CONTENT_PART_TYPE_FILE_ID`** A provider file identifier or internal storage identifier resolved before generation. File ID — a provider file ID (e.g., OpenAI) OR an internal storage file ID; resolved to a signed FILE\_URL just-in-time before the model-provider request **`CONTENT_PART_TYPE_FILE_PATH`** A reference to a local file path. Local file path reference **`CONTENT_PART_TYPE_FILE_URL`** A file supplied through a public or signed URL. Public or signed file URL (e.g., PDF URL or data: URL) **`CONTENT_PART_TYPE_FILE_DATA_URL`** A file embedded in a data URL, including its media type and encoded data. data\:application/pdf;base64,... or similar **`CONTENT_PART_TYPE_AUDIO_BASE64`** Base64-encoded audio; the part metadata identifies its audio format. Base64-encoded audio (metadata.format required, e.g., wav/mp3) **`CONTENT_PART_TYPE_REASONING`** A reasoning segment returned by a model provider, when available. Reasoning/thinking content from chain-of-thought models
Exactly one of: Variant 1: Type: `string` Enum: `CONTENT_PART_TYPE_TEXT`, `CONTENT_PART_TYPE_IMAGE_URL`, `CONTENT_PART_TYPE_IMAGE_BASE64`, `CONTENT_PART_TYPE_FILE_ID`, `CONTENT_PART_TYPE_FILE_PATH`, `CONTENT_PART_TYPE_FILE_URL`, `CONTENT_PART_TYPE_FILE_DATA_URL`, `CONTENT_PART_TYPE_AUDIO_BASE64`, `CONTENT_PART_TYPE_REASONING` Variant 2: Type: `integer(int32)` Enum: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8` **content** `string` Text content, image URL, file ID, or base64-encoded data. **metadata** `map[string, string]` Additional type-specific metadata (dimensions, mime\_type, etc.). **cachePreferred** `boolean` Hint that this part is eligible for provider prompt caching. **structuredMessage** `any` Populated on TEXT parts for structured output responses. All of: Variant 1: A structured message whose JSON payload has been validated against a declared schema. Consumers can trust that json\_payload conforms to the schema identified by schema\_name. Inspect the run outcome before treating any message as complete. Current structured metadata is attached to a text content part through [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage) can be absent. Use an object at the schema root and validate the exact final response your application consumes; server validation covers only the first model choice. For integers that your JSON client cannot represent exactly, define string-valued fields in your schema instead of converting them through floating point. Model reference: [StructuredMessage](/api/models/schema-1ho1lk4ndj#request). **jsonPayload** `map[string, any]` The validated JSON payload as a Struct (preserves types) **schemaName** `string` Schema identifier (from ResponseFormat.schema\_name) **healed** `boolean` Whether response healing is reported for this structured message. Currently returned as false. **metadata** `map[string, string]` Provider-specific extras. **sequence** `string(int64)` Monotonic, per-conversation sequence number for stable ordering (1-based) Pattern: ^-?\d+$ **generatedBy** `string` Workflow run id or generator key that produced this message (e.g., workflow run key) **usage** `any` Token usage for this generation (populated for assistant messages) All of: Variant 1: Usage accounting Model reference: [Usage](/api/models/schema-1j1vov2uoh#request). **promptTokens** `string(int64)` Prompt-token usage reported by the model provider. Pattern: ^-?\d+$ **completionTokens** `string(int64)` Completion-token usage reported by the model provider. Pattern: ^-?\d+$ **totalTokens** `string(int64)` Total token usage reported by the model provider. Pattern: ^-?\d+$ **costEstimate** `any` Estimated cost in USD. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completionTokensDetails** `any` Breakdown of completion tokens. All of: Variant 1: Breakdown of completion-token usage. Categories are measured by different upstream tokenizers and need not sum to completion\_tokens; reasoning\_tokens can exceed completion\_tokens. One category must not be derived by subtracting the others. Model reference: [CompletionTokensDetails](/api/models/schema-1i6q4qpg72#request). **reasoningTokens** `string(int64)` Tokens used for reasoning/thinking. Pattern: ^-?\d+$ **imageTokens** `string(int64)` Completion tokens emitted as image output. Pattern: ^-?\d+$ **audioTokens** `string(int64)` Completion tokens emitted as audio output. Pattern: ^-?\d+$ **promptTokensDetails** `any` Breakdown of prompt tokens (cache). All of: Variant 1: Breakdown of prompt token usage by category (input-side cache accounting) Subset semantics: cached\_tokens and cache\_write\_tokens are a breakdown *of* prompt\_tokens, so cached\_tokens + cache\_write\_tokens \<= Usage.prompt\_tokens. Ordinary (full-rate) prompt tokens = prompt\_tokens - cached\_tokens - cache\_write\_tokens. audio\_tokens / video\_tokens are modality breakdowns of prompt\_tokens (also a subset). Model reference: [PromptTokensDetails](/api/models/schema-1ivj82m55o#request). **cachedTokens** `string(int64)` Prompt tokens served from cache (cache READ). Pattern: ^-?\d+$ **cacheWriteTokens** `string(int64)` Prompt tokens written to cache this call (cache WRITE). Pattern: ^-?\d+$ **audioTokens** `string(int64)` Prompt tokens from audio input (multimodal). Pattern: ^-?\d+$ **videoTokens** `string(int64)` Prompt tokens from video input (multimodal). Pattern: ^-?\d+$ **costDetails** `any` Breakdown of upstream provider cost (BYOK routes). All of: Variant 1: Breakdown of model-provider cost. When the customer supplies the provider key, usage.cost is zero and upstream\_inference\_cost reports the provider spend, split into prompt and completion components. Model reference: [CostDetails](/api/models/schema-1ia0h761lm#request). **upstreamInferenceCost** `any` Total upstream provider cost (USD) on BYOK routes. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferencePromptCost** `any` Upstream cost attributed to prompt tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferenceCompletionCost** `any` Upstream cost attributed to completion tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **isByok** `boolean` Whether this generation used the customer's own model-provider key. **model** `string` Model that generated this message (e.g., "anthropic/claude-sonnet-4") **generationContext** `any` Dynamic context that shaped this generation (memories, search params, turn info) All of: Variant 1: Snapshot of retrieval inputs, prompt provenance, and turn position that shaped a generated message. Model reference: [GenerationContext](/api/models/schema-1im79fphmq#request). **memories** `array[llm_v1_common_v1_MemoryReferenceInput]` Memory records captured in the generation context. A memory record retrieved and included in generation context. Model reference: [MemoryReference](/api/models/schema-1ie9a4bgk5#request). **memoryId** `string` Identifier of the retrieved memory record. **score** `any` Relevance score reported by the memory provider for this match. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **memoryText** `string` Text of the retrieved memory record. **createdAt** `string(date-time)` Time when this record was created. **updatedAt** `string(date-time)` Time when this record was last updated. **relations** `array[llm_v1_common_v1_RelationReferenceInput]` Graph relationships captured in the generation context. A graph relationship retrieved and included in generation context. Model reference: [RelationReference](/api/models/schema-1ijit8ceuv#request). **source** `string` Source entity of the memory graph relationship. **relationship** `string` Relationship label connecting the source and destination entities. **destination** `string` Destination entity of the memory graph relationship. **memorySearch** `any` Memory-query parameters and counts recorded for this generation. All of: Variant 1: Parameters used to retrieve relevant memories during generation. Model reference: [MemorySearchParams](/api/models/schema-1igd5iut01#request). **query** `string` Text submitted to memory retrieval for this generation. **topK** `string(int64)` Maximum memory matches requested during generation-context retrieval. Pattern: ^-?\d+$ **threshold** `any` Minimum relevance threshold requested for the memory query. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **rerank** `boolean` Whether reranking was requested for the memory search. **resultsReturned** `string(int64)` Number of memory records returned by the search. Pattern: ^-?\d+$ **relationsReturned** `string(int64)` Number of graph relationships returned by the search. Pattern: ^-?\d+$ **turn** `any` Turn position and limit within the generation run. All of: Variant 1: Turn position within an agentic generation run Model reference: [TurnInfo](/api/models/schema-1ilcikuhu8#request). **currentTurn** `string(int64)` Current turn position within the generation run. Pattern: ^-?\d+$ **maxTurns** `string(int64)` Maximum turns configured for the generation run. Pattern: ^-?\d+$ **languagePreference** `string` Language preference associated with the generation context. **resolvedSystemPrompt** `string` System prompt selected for this generation after prompt precedence is resolved. This field is retained in the schema but is not populated; use resolved\_prompt\_hash for recorded prompt identity. **profileId** `string` Agent profile that produced this message ("" if none active). **model** `string` Model actually used for this generation. **promptSource** `any` Which precedence tier supplied the prompt. Source that supplied the effective system prompt for a generation turn. Distinguishes a client override, a profile template and the conversation default configuration for prompt attribution.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROMPT_SOURCE_CLIENT_OVERRIDE` | 0 | Canonical | See meaning below. | | `PROMPT_SOURCE_PROFILE_TEMPLATE` | 1 | Canonical | See meaning below. | | `PROMPT_SOURCE_DEFAULT_CONFIG` | 2 | Canonical | See meaning below. | **`PROMPT_SOURCE_CLIENT_OVERRIDE`** The caller supplied the prompt through the send request's generation-configuration override. SendRequest.override\_generation\_config **`PROMPT_SOURCE_PROFILE_TEMPLATE`** The prompt was rendered from the active agent profile template. active agent profile's rendered template **`PROMPT_SOURCE_DEFAULT_CONFIG`** The prompt came from the conversation or project default generation configuration. conversation/project default\_generation\_config
Exactly one of: Variant 1: Type: `string` Enum: `PROMPT_SOURCE_CLIENT_OVERRIDE`, `PROMPT_SOURCE_PROFILE_TEMPLATE`, `PROMPT_SOURCE_DEFAULT_CONFIG` Variant 2: Type: `integer(int32)` **baseConfig** `any` Generation configuration resolved at send time before per-call overrides and timeout adjustments, with system\_prompt omitted. The active profile supplies the base when selected; otherwise the conversation default does. Use prompt\_source and profile\_id for prompt attribution. The base configuration can be absent when neither source supplies one or no snapshot was captured. For a supplied per-call override, the populated top-level fields of override\_config overlay base\_config to form the effective configuration. override\_config can be absent when no override was supplied. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#request). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#request). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#request). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#request). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#request). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#request). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinitionInput]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#request). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinitionInput]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRuleInput]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#request). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#request). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#request). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRuleInput]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#request). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#request). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfigInput]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#request). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#request). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#request). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#request). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) Minimum length: 2 Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$ **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#request). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" Maximum length: 50 **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" Enum: ``, `friendly`, `iso8601`, `date_only` Maximum length: 50 **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#request). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` **required** Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" Enum: `minimal`, `standard`, `verbose` **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#request). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#request). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **overrideConfig** `any` Per-call generation configuration supplied before the override merge. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#request). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#request). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#request). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#request). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#request). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#request). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinitionInput]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#request). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinitionInput]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRuleInput]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#request). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#request). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#request). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRuleInput]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#request). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#request). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfigInput]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#request). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#request). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#request). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#request). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) Minimum length: 2 Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$ **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#request). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" Maximum length: 50 **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" Enum: ``, `friendly`, `iso8601`, `date_only` Maximum length: 50 **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#request). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` **required** Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" Enum: `minimal`, `standard`, `verbose` **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#request). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#request). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **profileVersion** `string(int64)` Immutable version of the active agent profile used to render this turn’s prompt. Absent on older turns and turns without a profile template. Pattern: ^-?\d+$ **fragmentsVersion** `string(int64)` Version of the prompt-fragment set used to render the profile prompt. Pattern: ^-?\d+$ **promptVariables** `map[string, any]` Values bound to the prompt template for this generation. **profileRenderFailed** `boolean` Whether rendering the profile prompt failed for this generation. **resolvedPromptHash** `string` SHA-256 hash, as 64 hexadecimal characters, of the resolved system prompt before the current-time instruction is appended. Identifies prompt content only, excluding model and sampling parameters. Absent on older turns without prompt capture. **resolvedUserContext** `string` The literal user-context text supplied to the model for this turn, including the available name, locale and location conditions. It is a captured prompt input, not a reconstruction from the user’s current profile. The value is computed once per turn and reused across its model calls. It can be empty when location context is unavailable, enrichment fails or the turn predates capture. **resolvedMcpServers** `array[llm_v1_common_v1_MCPServerReferenceInput]` The MCP server list used for this turn after resolving conversation settings, the active profile, and any per-turn `override_mcp_servers`. It determines both tool discovery and the allow/block rules applied by `CallTool`. A per-turn override does not change the conversation's stored MCP settings. Compare this snapshot with `settings.mcp_servers` to inspect how the turn's tool set differed. Empty on turns predating capture and on threads with no MCP servers. MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#request). **serverId** `string` **required** ID of pre-configured MCP server (e.g., "github", "filesystem"). Minimum length: 1 **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **clientContext** `any` Arbitrary client-supplied context attached by the client for this message All of: Variant 1: Opaque caller-supplied attributes attached to a conversation message. Values are strings, including values such as `"false"`. The schema allows at most 32 pairs, keys of at most 64 characters, and values of at most 1,024 characters. Keep the entire map well below 8 KiB: Travila also applies an encoded-size limit that includes field overhead and drops context that exceeds it. Short page identifiers and a few relevant values are preferable to a page dump; an oversized map is not automatically shortened. Model reference: [ClientContext](/api/models/schema-1i2sndrl93#request). **values** `map[string, string]` Arbitrary client-supplied context for this message (e.g. page, referrer, device, in-app flow). Keys/values are opaque strings. Maximum properties: 32 **feedback** `array[llm_v1_common_v1_MessageFeedbackInput]` Feedback on an assistant message, with one entry per rater identified by rated\_by. A later rating by the same rater replaces their earlier entry. One user's feedback on an assistant-generated message. kind must select a listed feedback representation. Requiredness and allowed values are declared separately. Model reference: [MessageFeedback](/api/models/schema-1iroqctqt1#request). **kind** `any` **required** Rating representation used to interpret the feedback value. Value scale used to interpret recorded feedback.
| Value | No. | Form | Meaning | |---|---|---|---| | `FEEDBACK_KIND_THUMB` | 0 | Canonical | See meaning below. | | `FEEDBACK_KIND_SCALE` | 1 | Canonical | See meaning below. | **`FEEDBACK_KIND_THUMB`** Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. binary thumbs up / down **`FEEDBACK_KIND_SCALE`** Feedback expressed as an integer rating from 1 through 10. 1-10 integer scale
Exactly one of: Variant 1: Type: `string` Enum: `FEEDBACK_KIND_THUMB`, `FEEDBACK_KIND_SCALE` Variant 2: Type: `integer(int32)` Enum: `0`, `1` **thumbUp** `boolean` Positive when true and negative when false; used for THUMB feedback. **rating** `string(int64)` Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent. Pattern: ^-?\d+$ **reason** `string` Optional explanation for the rating. Maximum length: 1000 **ratedAt** `string(date-time)` Timestamp when feedback was submitted (server-set) **ratedBy** `string` Identifier of the user who submitted this feedback. Set by the server from the authenticated user identity; never client-supplied. Each user has one feedback entry per message. **sourceUserMessageId** `string` Identifier of the user message that opened this conversation turn. Generated messages in the same turn share this value; a user message carries its own message\_id. Empty on historical messages that predate turn attribution. Use this field for turn attribution rather than inferring it from message adjacency or a client-supplied message\_id. The generated\_by identifier groups messages by generation run but does not identify the user message that opened the turn. **finishReason** `string` Why the model stopped, verbatim from the provider: "stop", "tool\_calls", "length", "error". Empty for historical messages. **overrideGenerationConfig** `any` Per-call configuration overrides applied to the active profile’s configuration, or otherwise the conversation default. Supplied scalar values, including zero, empty or false, replace the base value; omitted values inherit. Empty repeated or map values inherit. Use clear\_tools to clear inherited tools and clear\_client\_tools to clear inherited client tools. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#request). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#request). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#request). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#request). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#request). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#request). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinitionInput]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#request). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinitionInput]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRuleInput]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#request). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#request). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#request). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRuleInput]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#request). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#request). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfigInput]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#request). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#request). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#request). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#request). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) Minimum length: 2 Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$ **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#request). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" Maximum length: 50 **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" Enum: ``, `friendly`, `iso8601`, `date_only` Maximum length: 50 **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#request). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` **required** Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" Enum: `minimal`, `standard`, `verbose` **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#request). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#request). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **setActiveProfileId** `string` Set the active agent profile for this and subsequent conversation turns. **setActiveProfileVersion** `string(int64)` Version of the active agent profile forwarded with this turn. Pattern: ^-?\d+$ **overrideMcpServers** `array[llm_v1_common_v1_MCPServerReferenceInput]` MCP servers for this turn only. A nonempty list replaces the active profile’s or conversation’s list for tool discovery and execution; an empty list inherits the resolved configuration. MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#request). **serverId** `string` **required** ID of pre-configured MCP server (e.g., "github", "filesystem"). Minimum length: 1 **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **experiment** `any` Dataset-run attribution for a scripted evaluation turn. Leave unset for ordinary conversation traffic. An asynchronous caller must wait for the generation run to finish before scoring its result. All of: Variant 1: Dataset-run attribution attached when a scripted evaluation turn is sent. Supported on SendMessageRequest and SendMessageSyncRequest; ordinary conversation traffic leaves it unset. The attribution must accompany the turn so its observations can be associated with the dataset run; a separate post-run link does not supply this attribution. The dataset is required when experiment context is supplied. This attribution is separate from client\_context, which is included in model prompt context. Do not place evaluation attribution in prompt context. dataset\_item\_id is optional: a run can be scored from its traces without assigning each turn to a dataset item. profile\_revision\_hash supplies a profile revision fingerprint for comparison and attribution. Model reference: [ExperimentContext](/api/models/schema-1icbr3lltu#request). **datasetId** `string` **required** Identifier of the dataset to which this run belongs. Required whenever experiment context is supplied. Minimum length: 1 **runName** `string` **required** Names the run. Repeating a run\_name for the same dataset appends to that run rather than starting a new one, because the derived experiment id is deterministic — the same property that lets a retried turn land in the run it belongs to. Minimum length: 1 **datasetItemId** `string` Which dataset item this turn exercises. Optional: a run can be scored on its traces alone, and a harness that does not model items per-turn can leave it empty. **description** `string` Free-text description displayed with the dataset run. **metadataJson** `string` Additional run metadata serialized as a JSON object string and carried through unchanged. **profileRevisionHash** `string` Profile revision fingerprint attached to the dataset run for comparison and attribution. #### conversations-sendMessage-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "conversationKey": "example_123", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Hello" } ] } } ``` #### cookbook-core-platform-identity-access-scopes-permissions-01-request Guide request for The `users:impersonate` scope and `X-On-Behalf-Of`. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "conv_abc", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Hello" } ] } } ``` #### cookbook-integrations-tools-connections-custom-mcp-servers-05-request Guide request for 4. Ask about the page in a conversation. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "support-chat-001", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Read https://www.firecrawl.dev/pricing and summarize the pricing options. Link to the source." } ] }, "overrideMcpServers": [ { "serverId": "custom:firecrawl", "enabled": true } ] } ``` #### cookbook-managed-agents-conversations-build-chat-assistant-03-request Guide request for Send the message. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "What can you help me with?" } ] } } ``` #### cookbook-managed-agents-conversations-generation-01-request Guide request for Step 1: Send once and read the same conversation. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Hello, what can you help me with?" } ] } } ``` #### cookbook-managed-agents-conversations-index-02-request Guide request for Step 2: Send the customer’s first question. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "support-chat-001", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "How do I reset my password?" } ] } } ``` #### cookbook-managed-agents-model-controls-examples-02-request Guide request for Recipe: summarize support notes with a catalog price filter. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "bulk-task-001", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Summarize this support note: The customer reset their password and can now sign in." } ] }, "overrideGenerationConfig": { "models": [ "google/gemini-3.6-flash:nitro", "google/gemini-3.1-flash-lite", "google/gemini-3-flash-preview" ], "modelRoutingFilter": { "maxPromptCost": 0.000005, "maxCompletionCost": 0.00002 } } } ``` #### cookbook-managed-agents-model-controls-examples-03-request Guide request for Recipe: return a task summary after tool-assisted work. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Summarize the task we just discussed." } ] }, "overrideGenerationConfig": { "models": [ "google/gemini-3.6-flash:nitro", "anthropic/claude-sonnet-4.6:nitro" ], "responseFormat": { "jsonSchema": { "type": "object", "properties": { "summary": { "type": "string" } }, "required": [ "summary" ], "additionalProperties": false }, "schemaName": "task_summary", "validate": true }, "modelRoutingFilter": { "requiredParameters": [ "tools", "response_format" ] } } } ``` #### cookbook-managed-agents-model-controls-filtering-01-request Guide request for Step 1: send the image with its required capability. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "research-001", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_IMAGE_BASE64", "content": "" }, { "type": "CONTENT_PART_TYPE_TEXT", "content": "What is in this image?" } ] }, "overrideGenerationConfig": { "models": [ "google/gemini-3.6-flash:nitro", "anthropic/claude-sonnet-4.6:nitro", "anthropic/claude-sonnet-5" ], "modelRoutingFilter": { "requiredInputModalities": [ "image" ] } } } ``` #### cookbook-managed-agents-conversations-configuration-json-02-request Guide request for Variant: reuse the same assistant setup across conversations. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "thread_abc", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "..." } ] }, "setActiveProfileId": "profile_escalation" } ``` ## Responses ### 200 — Message accepted and generation initiated Content type: `application/json` Result of starting an asynchronous generation from a user message. **runId** `string` Identifier of the generation run associated with the operation. **interruptedPriorRun** `boolean` Whether submitting this turn interrupted a preceding generation run. #### conversations-sendMessage-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "runId": "example_123", "interruptedPriorRun": true } ``` #### cookbook-managed-agents-conversations-build-chat-assistant-json-03-response Illustrative response for Send the message. Replace example resource identifiers with your own authorized values. ```json { "runId": "64403669-5989-4ec3-ad9c-d84223f9679f" } ``` Document ID: `DOC-MA-conversations-api-sendMessage`. [Section identities and revisions](/documentation-manifest.json). - Send a message to a conversation: `DOC-MA-conversations-api-sendMessage#overview` - Request: `DOC-MA-conversations-api-sendMessage#request` - Responses: `DOC-MA-conversations-api-sendMessage#responses` --- # Submit client-side tool results and wait for the next segment URL: https://docs.travila.ai/api/conversations/submit-client-tool-results-sync **POST** `/api/v1/llm/submit-client-tool-results-sync` Submits client-side tool results and waits until the run arms another client-tool batch or finishes. This continues the loop started by `send-message-sync`. While the conversation still identifies a run, workflow validation rejects unmatched calls with `400` and already-resolved calls with `410`. If no active run is recorded, this call can return success immediately without applying any results. Reconcile stored run and tool state before treating HTTP success as confirmation that the results were applied. Echo the `clientToolCursor` from the response that armed the calls. A stale cursor re-delivers a batch rather than skipping one. When another batch arrives, execute it and submit again with its new cursor until the run reaches a terminal outcome. Reconcile an unknown status with a bounded wait; do not assume success. An empty `results` array returns `400`: submitting nothing resolves nothing. Use `list-pending-client-tools` to inspect pending work or recover after a dropped connection. Do not resend the original user message, which would start another run. Use `submit-client-tool-results` when you do not want to hold the connection. See [Messages and run outcomes](/api/conversations/messages-and-runs) for status interpretation and recovery. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Let a customer navigate your app through chat](/managed-agents/delegation-approvals/build-agent-with-tools) · [Check a chat integration before customers use it](/developer-experience/local-tooling/testing) · [Get a customer’s reply and recover an interrupted send](/managed-agents/conversations/generation) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for returning client-side tool results and waiting for the next generation segment. **conversationKey** `string` **required** Identifier of the conversation thread. Minimum length: 1 **results** `array[llm_v1_common_v1_ClientToolResult]` Execution results for tools that ran on the client. Result submitted by the caller for a client-side tool call. Both tool\_call\_id and tool\_name must identify the same pending call. When submission reaches workflow validation, either missing value causes a 400 response. Copy the call's id and name into these result fields, rather than submitting the pending ToolCall unchanged. Fields marked optional in the wire shape may still be required for a valid workflow submission. Both `tool_call_id` and `tool_name` must identify the same pending call; workflow validation rejects either missing value. Model reference: [ClientToolResult](/api/models/schema-1i4kndhs46#request). **toolCallId** `string` Required call identifier, copied from the pending ToolCall.id. **toolName** `string` Required tool name, copied from the pending ToolCall.name. **resultJson** `map[string, any]` Structured output for a matched pending call. A nonempty object records COMPLETED; an empty or omitted object records FAILED, including when the client could not complete the action. **error** `any` Supplied error detail. The current result handler does not consume this field; the presence of a nonempty result\_json alone determines whether the tool is recorded as completed. All of: Variant 1: Error payload containing an API-defined error code, a message and structured details. Interpret `code` using the ErrorCode enumeration published with this API; numeric equivalence with `google.rpc.Status` is not implied. Model reference: [RpcError](/api/models/schema-1fajlacjs0#request). **code** `any` Machine-readable error code. Clients switch on this field. API-defined categories describing why a request or operation failed. Use the published symbolic name and accompanying error details. These numeric assignments are not interchangeable with `google.rpc.Code`.
| Value | No. | Form | Meaning | |---|---|---|---| | `ERROR_CODE_CANCELLED` | 0 | Canonical | See meaning below. | | `ERROR_CODE_UNKNOWN` | 1 | Canonical | See meaning below. | | `ERROR_CODE_INVALID_ARGUMENT` | 2 | Canonical | See meaning below. | | `ERROR_CODE_DEADLINE_EXCEEDED` | 3 | Canonical | See meaning below. | | `ERROR_CODE_NOT_FOUND` | 4 | Canonical | See meaning below. | | `ERROR_CODE_ALREADY_EXISTS` | 5 | Canonical | See meaning below. | | `ERROR_CODE_PERMISSION_DENIED` | 6 | Canonical | See meaning below. | | `ERROR_CODE_RESOURCE_EXHAUSTED` | 7 | Canonical | See meaning below. | | `ERROR_CODE_FAILED_PRECONDITION` | 8 | Canonical | See meaning below. | | `ERROR_CODE_ABORTED` | 9 | Canonical | See meaning below. | | `ERROR_CODE_OUT_OF_RANGE` | 10 | Canonical | See meaning below. | | `ERROR_CODE_UNIMPLEMENTED` | 11 | Canonical | See meaning below. | | `ERROR_CODE_INTERNAL` | 12 | Canonical | See meaning below. | | `ERROR_CODE_UNAVAILABLE` | 13 | Canonical | See meaning below. | | `ERROR_CODE_DATA_LOSS` | 14 | Canonical | See meaning below. | | `ERROR_CODE_UNAUTHENTICATED` | 15 | Canonical | See meaning below. | | `ERROR_CODE_MODEL_INVALID` | 16 | Canonical | See meaning below. | | `ERROR_CODE_MODEL_UNAVAILABLE` | 17 | Canonical | See meaning below. | | `ERROR_CODE_MODERATION_FLAGGED` | 18 | Canonical | See meaning below. | | `ERROR_CODE_GENERATION_FAILED` | 19 | Canonical | See meaning below. | | `ERROR_CODE_TOOL_EXECUTION_FAILED` | 20 | Canonical | See meaning below. | | `ERROR_CODE_UPSTREAM_PROVIDER` | 21 | Canonical | See meaning below. | | `ERROR_CODE_VALIDATION_EXHAUSTED` | 22 | Canonical | See meaning below. | | `ERROR_CODE_PAYMENT_REQUIRED` | 23 | Canonical | See meaning below. | **`ERROR_CODE_CANCELLED`** The caller cancelled the operation before it completed. Canonical error categories. 499 — Cancelled by caller **`ERROR_CODE_UNKNOWN`** The operation failed without a more specific error classification. 500 — Unknown error **`ERROR_CODE_INVALID_ARGUMENT`** The request contains an invalid argument or field value. 400 — Bad input, invalid field values **`ERROR_CODE_DEADLINE_EXCEEDED`** The operation did not complete before its deadline. 504 — Operation timed out **`ERROR_CODE_NOT_FOUND`** The requested resource does not exist or could not be found. 404 — Resource does not exist **`ERROR_CODE_ALREADY_EXISTS`** The requested creation conflicts with a resource that already exists. 409 — Resource already exists **`ERROR_CODE_PERMISSION_DENIED`** The authenticated caller is not permitted to perform the operation. 403 — Caller lacks permission **`ERROR_CODE_RESOURCE_EXHAUSTED`** A quota, rate limit or other capacity limit prevented the operation. 429 — Rate limited or quota exceeded **`ERROR_CODE_FAILED_PRECONDITION`** The operation requires a system or resource state that is not currently satisfied. 400 — System not in required state **`ERROR_CODE_ABORTED`** The operation was aborted, for example by a concurrent modification conflict. 409 — Concurrent conflict, retry may succeed **`ERROR_CODE_OUT_OF_RANGE`** An argument is outside the range supported by this operation. 400 — Value outside valid range **`ERROR_CODE_UNIMPLEMENTED`** The requested operation is not implemented. 501 — Not implemented **`ERROR_CODE_INTERNAL`** An internal failure prevented the operation from completing. 500 — Internal error **`ERROR_CODE_UNAVAILABLE`** The service or a required dependency is temporarily unavailable. 503 — Service temporarily unavailable **`ERROR_CODE_DATA_LOSS`** The operation encountered unrecoverable loss or corruption of data. 500 — Unrecoverable data loss **`ERROR_CODE_UNAUTHENTICATED`** Authentication credentials are missing or invalid. 401 — Missing or invalid credentials **`ERROR_CODE_MODEL_INVALID`** The requested model identifier is absent from the model catalog. Domain-specific error categories. 400 — Model ID not found in catalog **`ERROR_CODE_MODEL_UNAVAILABLE`** The model exists, but no provider is currently available to serve it. 503 — Model exists but all providers are down **`ERROR_CODE_MODERATION_FLAGGED`** Content moderation flagged the submitted content. 403 — Input flagged by content moderation **`ERROR_CODE_GENERATION_FAILED`** Model generation failed after its configured attempts. 500 — LLM generation failed after retries **`ERROR_CODE_TOOL_EXECUTION_FAILED`** Execution of a requested tool failed. 500 — MCP tool call failed **`ERROR_CODE_UPSTREAM_PROVIDER`** An upstream model provider returned an error. 503 — Upstream provider returned error **`ERROR_CODE_VALIDATION_EXHAUSTED`** Structured-output validation still failed after the configured attempts. 500 — Structured output validation failed after all retries **`ERROR_CODE_PAYMENT_REQUIRED`** The account lacks the credits required for the operation. 402 — Insufficient credits
Exactly one of: Variant 1: Type: `string` Enum: `ERROR_CODE_CANCELLED`, `ERROR_CODE_UNKNOWN`, `ERROR_CODE_INVALID_ARGUMENT`, `ERROR_CODE_DEADLINE_EXCEEDED`, `ERROR_CODE_NOT_FOUND`, `ERROR_CODE_ALREADY_EXISTS`, `ERROR_CODE_PERMISSION_DENIED`, `ERROR_CODE_RESOURCE_EXHAUSTED`, `ERROR_CODE_FAILED_PRECONDITION`, `ERROR_CODE_ABORTED`, `ERROR_CODE_OUT_OF_RANGE`, `ERROR_CODE_UNIMPLEMENTED`, `ERROR_CODE_INTERNAL`, `ERROR_CODE_UNAVAILABLE`, `ERROR_CODE_DATA_LOSS`, `ERROR_CODE_UNAUTHENTICATED`, `ERROR_CODE_MODEL_INVALID`, `ERROR_CODE_MODEL_UNAVAILABLE`, `ERROR_CODE_MODERATION_FLAGGED`, `ERROR_CODE_GENERATION_FAILED`, `ERROR_CODE_TOOL_EXECUTION_FAILED`, `ERROR_CODE_UPSTREAM_PROVIDER`, `ERROR_CODE_VALIDATION_EXHAUSTED`, `ERROR_CODE_PAYMENT_REQUIRED` Variant 2: Type: `integer(int32)` **message** `string` Human-readable error description. Intended for developers, not end users. Must not be parsed programmatically — use code and details instead. **isTerminal** `boolean` Whether this error is classified as terminal (non-retryable). A terminal error should not trigger automatic retries of the failed operation. A nonterminal error may reflect a transient condition that can resolve on retry. **details** `any` Structured error details. At most one of each detail type. All of: Variant 1: Typed error details container. Concrete fields instead of Any for type safety across languages. At most one of each detail type. Model reference: [ErrorDetails](/api/models/schema-1f7d7kh0s1#request). **errorInfo** `any` Identifies the error for machine consumption. Required on all errors by this error contract. All of: Variant 1: Machine-readable error identification (per AIP-193, every error must include this). Model reference: [ErrorInfo](/api/models/schema-1es9uii84j#request). **reason** `string` Stable machine-readable reason string (e.g., "MODEL\_NOT\_FOUND", "RATE\_LIMITED", "MODERATION\_FLAGGED"). Unique within the domain. Clients may switch on this field. **domain** `string` Machine-readable namespace identifying the origin of the error. **metadata** `map[string, string]` Arbitrary key-value metadata. If the message field mentions a specific value (model name, field path, etc.), it MUST also appear here. **retryInfo** `any` Retry guidance for transient errors. All of: Variant 1: Retry guidance for transient errors. Model reference: [RetryInfo](/api/models/schema-1f439vae2d#request). **retryDelayMs** `string(int64)` Suggested minimum delay before retrying, in milliseconds. Pattern: ^-?\d+$ **fieldViolations** `array[common_v1_FieldViolationInput]` Field-level validation failures. A single field-level validation violation. Model reference: [FieldViolation](/api/models/schema-1eu5noj3g1#request). **field** `string` Dot-separated path to the field (e.g., "generation\_config.model"). **description** `string` Human-readable description of the violation. **upstreamError** `any` Upstream provider error context. All of: Variant 1: Context from an upstream provider error, including the provider name when reported. Model reference: [UpstreamError](/api/models/schema-1f66rlcp5a#request). **provider** `string` Name of the upstream provider that reported the error. **statusCode** `string(int64)` HTTP status code returned by the provider. Pattern: ^-?\d+$ **rawBody** `string` Raw error body from the provider, truncated to 512 bytes. **modelError** `any` Model-specific error context. All of: Variant 1: Model-specific error context. Model reference: [ModelError](/api/models/schema-1f2939tg20#request). **modelId** `string` The model ID that caused the error. **reason** `string` Why the model failed (e.g., "invalid", "unavailable", "moderation\_flagged"). **alternativesTried** `array[string]` Alternative models that were tried or could be tried. Type: `string` **helpLinks** `array[common_v1_HelpLinkInput]` Help links for error resolution. A help link for error resolution. Model reference: [HelpLink](/api/models/schema-1f0qdi91b8#request). **url** `string` URL to documentation or resolution guide. **description** `string` Description of what the link provides. **clientToolCursor** `string(int64)` dispatch\_seq this caller last observed — same semantics as AwaitGenerationRequest.client\_tool\_cursor. 0 on first call. Pattern: ^-?\d+$ #### conversations-submitClientToolResultsSync-request Return a result for a pending client tool call; use its actual ID, name and expected result shape. ```json { "conversationKey": "example_123", "results": [ { "toolCallId": "tool_call_123", "toolName": "lookup_booking", "resultJson": { "bookingStatus": "confirmed" } } ] } ``` #### cookbook-developer-experience-local-tooling-testing-02-request Guide request for Verify that an in-app action returns control to the conversation. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842", "clientToolCursor": 1, "results": [ { "toolCallId": "call_abc123", "toolName": "navigate_to", "resultJson": { "navigated_to": "/profile" } } ] } ``` #### cookbook-managed-agents-delegation-approvals-using-tools-04-request Guide request for Step 2: Validate, open and return the real result. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "support-chat-001", "clientToolCursor": 1, "results": [ { "toolCallId": "call_306135", "toolName": "navigate_to", "resultJson": { "navigated_to": "/profile" } } ] } ``` ## Responses ### 200 — Run status and available messages or pending client tools returned Content type: `application/json` Result of returning client-side tool results and waiting for the next generation segment. **runId** `string` Identifier of the generation run associated with the operation. **messages** `array[llm_v1_common_v1_Message]` Conversation messages returned by the generation segment. Chat message At least one of content or tool\_calls must contain an entry; both lists may be nonempty. role must select a listed message role. Requiredness and allowed values are declared separately. Model reference: [Message](/api/models/schema-1j3dcf7kvu#response). **role** `any` Role of the participant that produced the chat message. Participant role attached to a conversation message and forwarded in model context.
| Value | No. | Form | Meaning | |---|---|---|---| | `ROLE_SYSTEM` | 0 | Canonical | Instructions or context provided as a system message. | | `ROLE_USER` | 1 | Canonical | Input supplied by the user or customer application. | | `ROLE_ASSISTANT` | 2 | Canonical | Content produced by the assistant, including its tool-call requests. | | `ROLE_TOOL` | 3 | Canonical | A tool result supplied back to the assistant. |
Exactly one of: Variant 1: Type: `string` Enum: `ROLE_SYSTEM`, `ROLE_USER`, `ROLE_ASSISTANT`, `ROLE_TOOL` Variant 2: Type: `integer(int32)` **content** `array[llm_v1_common_v1_ContentPart]` Content parts composing the chat message. Content parts composing a message, using a flattened structure for JSON compatibility. The `type` identifies how the content is represented; only defined content types are accepted. Model reference: [ContentPart](/api/models/schema-1hqi9r2bhh#response). **type** `any` Kind of content carried by this message part. Discriminator identifying which content representation a message part carries.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTENT_PART_TYPE_TEXT` | 0 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_URL` | 1 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_BASE64` | 2 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_ID` | 3 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_PATH` | 4 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_URL` | 5 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_DATA_URL` | 6 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_AUDIO_BASE64` | 7 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_REASONING` | 8 | Canonical | See meaning below. | **`CONTENT_PART_TYPE_TEXT`** Plain text carried by the content part. Plain text content **`CONTENT_PART_TYPE_IMAGE_URL`** An image supplied through a remote URL. Remote image URL **`CONTENT_PART_TYPE_IMAGE_BASE64`** An image supplied as base64-encoded bytes. Base64-encoded image data **`CONTENT_PART_TYPE_FILE_ID`** A provider file identifier or internal storage identifier resolved before generation. File ID — a provider file ID (e.g., OpenAI) OR an internal storage file ID; resolved to a signed FILE\_URL just-in-time before the model-provider request **`CONTENT_PART_TYPE_FILE_PATH`** A reference to a local file path. Local file path reference **`CONTENT_PART_TYPE_FILE_URL`** A file supplied through a public or signed URL. Public or signed file URL (e.g., PDF URL or data: URL) **`CONTENT_PART_TYPE_FILE_DATA_URL`** A file embedded in a data URL, including its media type and encoded data. data\:application/pdf;base64,... or similar **`CONTENT_PART_TYPE_AUDIO_BASE64`** Base64-encoded audio; the part metadata identifies its audio format. Base64-encoded audio (metadata.format required, e.g., wav/mp3) **`CONTENT_PART_TYPE_REASONING`** A reasoning segment returned by a model provider, when available. Reasoning/thinking content from chain-of-thought models
Exactly one of: Variant 1: Type: `string` Enum: `CONTENT_PART_TYPE_TEXT`, `CONTENT_PART_TYPE_IMAGE_URL`, `CONTENT_PART_TYPE_IMAGE_BASE64`, `CONTENT_PART_TYPE_FILE_ID`, `CONTENT_PART_TYPE_FILE_PATH`, `CONTENT_PART_TYPE_FILE_URL`, `CONTENT_PART_TYPE_FILE_DATA_URL`, `CONTENT_PART_TYPE_AUDIO_BASE64`, `CONTENT_PART_TYPE_REASONING` Variant 2: Type: `integer(int32)` **content** `string` Text content, image URL, file ID, or base64-encoded data. **metadata** `map[string, string]` Additional type-specific metadata (dimensions, mime\_type, etc.). **cachePreferred** `boolean` Hint that this part is eligible for provider prompt caching. **structuredMessage** `any` Populated on TEXT parts for structured output responses. All of: Variant 1: A structured message whose JSON payload has been validated against a declared schema. Consumers can trust that json\_payload conforms to the schema identified by schema\_name. Inspect the run outcome before treating any message as complete. Current structured metadata is attached to a text content part through [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage) can be absent. Use an object at the schema root and validate the exact final response your application consumes; server validation covers only the first model choice. For integers that your JSON client cannot represent exactly, define string-valued fields in your schema instead of converting them through floating point. Model reference: [StructuredMessage](/api/models/schema-1ho1lk4ndj#response). **jsonPayload** `map[string, any]` The validated JSON payload as a Struct (preserves types) **schemaName** `string` Schema identifier (from ResponseFormat.schema\_name) **healed** `boolean` Whether response healing is reported for this structured message. Currently returned as false. **toolCalls** `array[llm_v1_common_v1_ToolCall]` Assistant-to-tool invocations. A single structured tool call emitted by the model [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat) is the client answer window. Expiry ends that wait and rejects late results; the timeout policy determines the outcome. Model reference: [ToolCall](/api/models/schema-1it6mqsqoo#response). **id** `string` Provider-supplied call id. **name** `string` Name of the tool or function being invoked. **argumentsJson** `map[string, any]` JSON object payload. **status** `any` Execution status recorded for the tool call. Execution state of a tool call, including approval waiting and terminal outcomes. The terminal outcomes are COMPLETED, FAILED, CANCELLED and TIMED\_OUT; inspect ToolCall.end\_reason for why a call ended rather than treating the reason as another status. Use a listed execution status. The end reason explains the outcome separately from the status.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_EXECUTION_STATUS_PENDING` | 0 | Canonical | The tool call is waiting to begin execution. | | `TOOL_EXECUTION_STATUS_EXECUTING` | 1 | Canonical | The tool call is currently executing. | | `TOOL_EXECUTION_STATUS_COMPLETED` | 2 | Canonical | The tool call completed successfully. This is a terminal outcome. | | `TOOL_EXECUTION_STATUS_FAILED` | 3 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. | | `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 4 | Canonical | The tool call is waiting for approval before it can execute. | | `TOOL_EXECUTION_STATUS_CANCELLED` | 5 | Canonical | The tool call was cancelled before normal completion. | | `TOOL_EXECUTION_STATUS_TIMED_OUT` | 6 | Canonical | Tool execution ended because its time limit elapsed. |
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_EXECUTION_STATUS_PENDING`, `TOOL_EXECUTION_STATUS_EXECUTING`, `TOOL_EXECUTION_STATUS_COMPLETED`, `TOOL_EXECUTION_STATUS_FAILED`, `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, `TOOL_EXECUTION_STATUS_CANCELLED`, `TOOL_EXECUTION_STATUS_TIMED_OUT` Variant 2: Type: `integer(int32)` **resultJson** `map[string, any]` Tool execution result (object). **executedAt** `string(date-time)` Time when the tool execution was recorded. **serverId** `string` Which server provides this tool (for MCP tools). **isClientTool** `boolean` True if this is a client-side tool handled by client. **description** `string` Tool description captured from the resolved tool definition when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. **parametersJsonSchema** `map[string, any]` JSON Schema describing the tool’s input arguments. **requiresApprovalAt** `string(date-time)` Deadline for an approval decision, calculated from the effective approval timeout. This is not the time the call began waiting. An approval received after the deadline is rejected. **approvedAt** `string(date-time)` Timestamp when approval decision was recorded (if approved/rejected) **approvedBy** `string` Identifier of the approver (user id, email, or actor key) **executionDuration** `string` End-to-end execution duration once terminal (includes tool server latency or client-side time) Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **endReason** `string` Why this call ended, in one short phrase — "approval rejected", "approval timeout", or the underlying error. Set only once `status` is terminal, and empty on a clean COMPLETED. Use this reason to distinguish a rejection from a failure without parsing the tool result. **clientToolDeadlineAt** `string(date-time)` Deadline by which the client must submit a result for this call, stamped when the call is dispatched to a caller. **name** `string` Name identifying the sender of the chat message. optional sender name **timestamp** `string(date-time)` Timestamp associated with the conversation message or event. **messageId** `string` Unique message identifier. **annotations** `array[llm_v1_common_v1_Annotation]` Structured annotations (e.g., standardized web search URL citations, PDF reuse tokens) Tagged provider annotation attached to generated content, such as a citation or PDF reference. Model reference: [Annotation](/api/models/schema-1i0hjer0pd#response). **kind** `any` Selected kind; determines which submessage is populated Kind of source annotation associated with generated content.
| Value | No. | Form | Meaning | |---|---|---|---| | `ANNOTATION_KIND_URL_CITATION` | 0 | Canonical | A citation to a source identified by its URL. | | `ANNOTATION_KIND_PDF` | 1 | Canonical | An annotation identifying source content in a PDF document. |
Exactly one of: Variant 1: Type: `string` Enum: `ANNOTATION_KIND_URL_CITATION`, `ANNOTATION_KIND_PDF` Variant 2: Type: `integer(int32)` **urlCitation** `any` Submessage fields (optional); populate the one matching kind All of: Variant 1: Web source and character range cited in generated message content. Model reference: [UrlCitation](/api/models/schema-1hujls61ng#response). **url** `string` URL of the cited web page. **title** `string` Title of the web page cited by this annotation. **content** `string` Optional excerpt or snippet of the cited web page. **startIndex** `string(int64)` Character index in message content. Pattern: ^-?\d+$ **endIndex** `string(int64)` Character index in message content. Pattern: ^-?\d+$ **pdf** `any` PDF annotation identifying the parsed file and available parsing output. All of: Variant 1: Provider annotation identifying a parsed PDF and reusable parsing output. Model reference: [PdfAnnotation](/api/models/schema-1hsi58i6pb#response). **filename** `string` Optional identifying information about the original file **engine** `string` PDF parsing engine used by provider (e.g., "pdf-text", "mistral-ocr", "native") **token** `string` Opaque provider token or handle allowing reuse without re-parsing **sourceUrl** `string` Optional: original source reference (public URL or data: URL) **hash** `string` Provider-supplied hash identifying the parsed file. **content** `array[llm_v1_common_v1_ContentPart]` Optional structured content returned by provider annotations (text, image URLs, etc.) Note: This can be large; include only if you need to round-trip provider annotations. Content parts composing a message, using a flattened structure for JSON compatibility. The `type` identifies how the content is represented; only defined content types are accepted. Model reference: [ContentPart](/api/models/schema-1hqi9r2bhh#response). **type** `any` Kind of content carried by this message part. Discriminator identifying which content representation a message part carries.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTENT_PART_TYPE_TEXT` | 0 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_URL` | 1 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_BASE64` | 2 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_ID` | 3 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_PATH` | 4 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_URL` | 5 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_DATA_URL` | 6 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_AUDIO_BASE64` | 7 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_REASONING` | 8 | Canonical | See meaning below. | **`CONTENT_PART_TYPE_TEXT`** Plain text carried by the content part. Plain text content **`CONTENT_PART_TYPE_IMAGE_URL`** An image supplied through a remote URL. Remote image URL **`CONTENT_PART_TYPE_IMAGE_BASE64`** An image supplied as base64-encoded bytes. Base64-encoded image data **`CONTENT_PART_TYPE_FILE_ID`** A provider file identifier or internal storage identifier resolved before generation. File ID — a provider file ID (e.g., OpenAI) OR an internal storage file ID; resolved to a signed FILE\_URL just-in-time before the model-provider request **`CONTENT_PART_TYPE_FILE_PATH`** A reference to a local file path. Local file path reference **`CONTENT_PART_TYPE_FILE_URL`** A file supplied through a public or signed URL. Public or signed file URL (e.g., PDF URL or data: URL) **`CONTENT_PART_TYPE_FILE_DATA_URL`** A file embedded in a data URL, including its media type and encoded data. data\:application/pdf;base64,... or similar **`CONTENT_PART_TYPE_AUDIO_BASE64`** Base64-encoded audio; the part metadata identifies its audio format. Base64-encoded audio (metadata.format required, e.g., wav/mp3) **`CONTENT_PART_TYPE_REASONING`** A reasoning segment returned by a model provider, when available. Reasoning/thinking content from chain-of-thought models
Exactly one of: Variant 1: Type: `string` Enum: `CONTENT_PART_TYPE_TEXT`, `CONTENT_PART_TYPE_IMAGE_URL`, `CONTENT_PART_TYPE_IMAGE_BASE64`, `CONTENT_PART_TYPE_FILE_ID`, `CONTENT_PART_TYPE_FILE_PATH`, `CONTENT_PART_TYPE_FILE_URL`, `CONTENT_PART_TYPE_FILE_DATA_URL`, `CONTENT_PART_TYPE_AUDIO_BASE64`, `CONTENT_PART_TYPE_REASONING` Variant 2: Type: `integer(int32)` **content** `string` Text content, image URL, file ID, or base64-encoded data. **metadata** `map[string, string]` Additional type-specific metadata (dimensions, mime\_type, etc.). **cachePreferred** `boolean` Hint that this part is eligible for provider prompt caching. **structuredMessage** `any` Populated on TEXT parts for structured output responses. All of: Variant 1: A structured message whose JSON payload has been validated against a declared schema. Consumers can trust that json\_payload conforms to the schema identified by schema\_name. Inspect the run outcome before treating any message as complete. Current structured metadata is attached to a text content part through [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage) can be absent. Use an object at the schema root and validate the exact final response your application consumes; server validation covers only the first model choice. For integers that your JSON client cannot represent exactly, define string-valued fields in your schema instead of converting them through floating point. Model reference: [StructuredMessage](/api/models/schema-1ho1lk4ndj#response). **jsonPayload** `map[string, any]` The validated JSON payload as a Struct (preserves types) **schemaName** `string` Schema identifier (from ResponseFormat.schema\_name) **healed** `boolean` Whether response healing is reported for this structured message. Currently returned as false. **metadata** `map[string, string]` Provider-specific extras. **sequence** `string(int64)` Monotonic, per-conversation sequence number for stable ordering (1-based) Pattern: ^-?\d+$ **generatedBy** `string` Workflow run id or generator key that produced this message (e.g., workflow run key) **usage** `any` Token usage for this generation (populated for assistant messages) All of: Variant 1: Usage accounting Model reference: [Usage](/api/models/schema-1j1vov2uoh#response). **promptTokens** `string(int64)` Prompt-token usage reported by the model provider. Pattern: ^-?\d+$ **completionTokens** `string(int64)` Completion-token usage reported by the model provider. Pattern: ^-?\d+$ **totalTokens** `string(int64)` Total token usage reported by the model provider. Pattern: ^-?\d+$ **costEstimate** `any` Estimated cost in USD. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completionTokensDetails** `any` Breakdown of completion tokens. All of: Variant 1: Breakdown of completion-token usage. Categories are measured by different upstream tokenizers and need not sum to completion\_tokens; reasoning\_tokens can exceed completion\_tokens. One category must not be derived by subtracting the others. Model reference: [CompletionTokensDetails](/api/models/schema-1i6q4qpg72#response). **reasoningTokens** `string(int64)` Tokens used for reasoning/thinking. Pattern: ^-?\d+$ **imageTokens** `string(int64)` Completion tokens emitted as image output. Pattern: ^-?\d+$ **audioTokens** `string(int64)` Completion tokens emitted as audio output. Pattern: ^-?\d+$ **promptTokensDetails** `any` Breakdown of prompt tokens (cache). All of: Variant 1: Breakdown of prompt token usage by category (input-side cache accounting) Subset semantics: cached\_tokens and cache\_write\_tokens are a breakdown *of* prompt\_tokens, so cached\_tokens + cache\_write\_tokens \<= Usage.prompt\_tokens. Ordinary (full-rate) prompt tokens = prompt\_tokens - cached\_tokens - cache\_write\_tokens. audio\_tokens / video\_tokens are modality breakdowns of prompt\_tokens (also a subset). Model reference: [PromptTokensDetails](/api/models/schema-1ivj82m55o#response). **cachedTokens** `string(int64)` Prompt tokens served from cache (cache READ). Pattern: ^-?\d+$ **cacheWriteTokens** `string(int64)` Prompt tokens written to cache this call (cache WRITE). Pattern: ^-?\d+$ **audioTokens** `string(int64)` Prompt tokens from audio input (multimodal). Pattern: ^-?\d+$ **videoTokens** `string(int64)` Prompt tokens from video input (multimodal). Pattern: ^-?\d+$ **costDetails** `any` Breakdown of upstream provider cost (BYOK routes). All of: Variant 1: Breakdown of model-provider cost. When the customer supplies the provider key, usage.cost is zero and upstream\_inference\_cost reports the provider spend, split into prompt and completion components. Model reference: [CostDetails](/api/models/schema-1ia0h761lm#response). **upstreamInferenceCost** `any` Total upstream provider cost (USD) on BYOK routes. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferencePromptCost** `any` Upstream cost attributed to prompt tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferenceCompletionCost** `any` Upstream cost attributed to completion tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **isByok** `boolean` Whether this generation used the customer's own model-provider key. **model** `string` Model that generated this message (e.g., "anthropic/claude-sonnet-4") **generationContext** `any` Dynamic context that shaped this generation (memories, search params, turn info) All of: Variant 1: Snapshot of retrieval inputs, prompt provenance, and turn position that shaped a generated message. Model reference: [GenerationContext](/api/models/schema-1im79fphmq#response). **memories** `array[llm_v1_common_v1_MemoryReference]` Memory records captured in the generation context. A memory record retrieved and included in generation context. Model reference: [MemoryReference](/api/models/schema-1ie9a4bgk5#response). **memoryId** `string` Identifier of the retrieved memory record. **score** `any` Relevance score reported by the memory provider for this match. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **memoryText** `string` Text of the retrieved memory record. **createdAt** `string(date-time)` Time when this record was created. **updatedAt** `string(date-time)` Time when this record was last updated. **relations** `array[llm_v1_common_v1_RelationReference]` Graph relationships captured in the generation context. A graph relationship retrieved and included in generation context. Model reference: [RelationReference](/api/models/schema-1ijit8ceuv#response). **source** `string` Source entity of the memory graph relationship. **relationship** `string` Relationship label connecting the source and destination entities. **destination** `string` Destination entity of the memory graph relationship. **memorySearch** `any` Memory-query parameters and counts recorded for this generation. All of: Variant 1: Parameters used to retrieve relevant memories during generation. Model reference: [MemorySearchParams](/api/models/schema-1igd5iut01#response). **query** `string` Text submitted to memory retrieval for this generation. **topK** `string(int64)` Maximum memory matches requested during generation-context retrieval. Pattern: ^-?\d+$ **threshold** `any` Minimum relevance threshold requested for the memory query. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **rerank** `boolean` Whether reranking was requested for the memory search. **resultsReturned** `string(int64)` Number of memory records returned by the search. Pattern: ^-?\d+$ **relationsReturned** `string(int64)` Number of graph relationships returned by the search. Pattern: ^-?\d+$ **turn** `any` Turn position and limit within the generation run. All of: Variant 1: Turn position within an agentic generation run Model reference: [TurnInfo](/api/models/schema-1ilcikuhu8#response). **currentTurn** `string(int64)` Current turn position within the generation run. Pattern: ^-?\d+$ **maxTurns** `string(int64)` Maximum turns configured for the generation run. Pattern: ^-?\d+$ **languagePreference** `string` Language preference associated with the generation context. **resolvedSystemPrompt** `string` System prompt selected for this generation after prompt precedence is resolved. This field is retained in the schema but is not populated; use resolved\_prompt\_hash for recorded prompt identity. **profileId** `string` Agent profile that produced this message ("" if none active). **model** `string` Model actually used for this generation. **promptSource** `any` Which precedence tier supplied the prompt. Source that supplied the effective system prompt for a generation turn. Distinguishes a client override, a profile template and the conversation default configuration for prompt attribution.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROMPT_SOURCE_CLIENT_OVERRIDE` | 0 | Canonical | See meaning below. | | `PROMPT_SOURCE_PROFILE_TEMPLATE` | 1 | Canonical | See meaning below. | | `PROMPT_SOURCE_DEFAULT_CONFIG` | 2 | Canonical | See meaning below. | **`PROMPT_SOURCE_CLIENT_OVERRIDE`** The caller supplied the prompt through the send request's generation-configuration override. SendRequest.override\_generation\_config **`PROMPT_SOURCE_PROFILE_TEMPLATE`** The prompt was rendered from the active agent profile template. active agent profile's rendered template **`PROMPT_SOURCE_DEFAULT_CONFIG`** The prompt came from the conversation or project default generation configuration. conversation/project default\_generation\_config
Exactly one of: Variant 1: Type: `string` Enum: `PROMPT_SOURCE_CLIENT_OVERRIDE`, `PROMPT_SOURCE_PROFILE_TEMPLATE`, `PROMPT_SOURCE_DEFAULT_CONFIG` Variant 2: Type: `integer(int32)` **baseConfig** `any` Generation configuration resolved at send time before per-call overrides and timeout adjustments, with system\_prompt omitted. The active profile supplies the base when selected; otherwise the conversation default does. Use prompt\_source and profile\_id for prompt attribution. The base configuration can be absent when neither source supplies one or no snapshot was captured. For a supplied per-call override, the populated top-level fields of override\_config overlay base\_config to form the effective configuration. override\_config can be absent when no override was supplied. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#response). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#response). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#response). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#response). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#response). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#response). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#response). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinition]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#response). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfig]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#response). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#response). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#response). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#response). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#response). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#response). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#response). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#response). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **overrideConfig** `any` Per-call generation configuration supplied before the override merge. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#response). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#response). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#response). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#response). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#response). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#response). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#response). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinition]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#response). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfig]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#response). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#response). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#response). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#response). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#response). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#response). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#response). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#response). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **profileVersion** `string(int64)` Immutable version of the active agent profile used to render this turn’s prompt. Absent on older turns and turns without a profile template. Pattern: ^-?\d+$ **fragmentsVersion** `string(int64)` Version of the prompt-fragment set used to render the profile prompt. Pattern: ^-?\d+$ **promptVariables** `map[string, any]` Values bound to the prompt template for this generation. **profileRenderFailed** `boolean` Whether rendering the profile prompt failed for this generation. **resolvedPromptHash** `string` SHA-256 hash, as 64 hexadecimal characters, of the resolved system prompt before the current-time instruction is appended. Identifies prompt content only, excluding model and sampling parameters. Absent on older turns without prompt capture. **resolvedUserContext** `string` The literal user-context text supplied to the model for this turn, including the available name, locale and location conditions. It is a captured prompt input, not a reconstruction from the user’s current profile. The value is computed once per turn and reused across its model calls. It can be empty when location context is unavailable, enrichment fails or the turn predates capture. **resolvedMcpServers** `array[llm_v1_common_v1_MCPServerReference]` The MCP server list used for this turn after resolving conversation settings, the active profile, and any per-turn `override_mcp_servers`. It determines both tool discovery and the allow/block rules applied by `CallTool`. A per-turn override does not change the conversation's stored MCP settings. Compare this snapshot with `settings.mcp_servers` to inspect how the turn's tool set differed. Empty on turns predating capture and on threads with no MCP servers. MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#response). **serverId** `string` ID of pre-configured MCP server (e.g., "github", "filesystem"). **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **clientContext** `any` Arbitrary client-supplied context attached by the client for this message All of: Variant 1: Opaque caller-supplied attributes attached to a conversation message. Values are strings, including values such as `"false"`. The schema allows at most 32 pairs, keys of at most 64 characters, and values of at most 1,024 characters. Keep the entire map well below 8 KiB: Travila also applies an encoded-size limit that includes field overhead and drops context that exceeds it. Short page identifiers and a few relevant values are preferable to a page dump; an oversized map is not automatically shortened. Model reference: [ClientContext](/api/models/schema-1i2sndrl93#response). **values** `map[string, string]` Arbitrary client-supplied context for this message (e.g. page, referrer, device, in-app flow). Keys/values are opaque strings. **feedback** `array[llm_v1_common_v1_MessageFeedback]` Feedback on an assistant message, with one entry per rater identified by rated\_by. A later rating by the same rater replaces their earlier entry. One user's feedback on an assistant-generated message. kind must select a listed feedback representation. Requiredness and allowed values are declared separately. Model reference: [MessageFeedback](/api/models/schema-1iroqctqt1#response). **kind** `any` Rating representation used to interpret the feedback value. Value scale used to interpret recorded feedback.
| Value | No. | Form | Meaning | |---|---|---|---| | `FEEDBACK_KIND_THUMB` | 0 | Canonical | See meaning below. | | `FEEDBACK_KIND_SCALE` | 1 | Canonical | See meaning below. | **`FEEDBACK_KIND_THUMB`** Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. binary thumbs up / down **`FEEDBACK_KIND_SCALE`** Feedback expressed as an integer rating from 1 through 10. 1-10 integer scale
Exactly one of: Variant 1: Type: `string` Enum: `FEEDBACK_KIND_THUMB`, `FEEDBACK_KIND_SCALE` Variant 2: Type: `integer(int32)` **thumbUp** `boolean` Positive when true and negative when false; used for THUMB feedback. **rating** `string(int64)` Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent. Pattern: ^-?\d+$ **reason** `string` Optional explanation for the rating. **ratedAt** `string(date-time)` Timestamp when feedback was submitted (server-set) **ratedBy** `string` Identifier of the user who submitted this feedback. Set by the server from the authenticated user identity; never client-supplied. Each user has one feedback entry per message. **sourceUserMessageId** `string` Identifier of the user message that opened this conversation turn. Generated messages in the same turn share this value; a user message carries its own message\_id. Empty on historical messages that predate turn attribution. Use this field for turn attribution rather than inferring it from message adjacency or a client-supplied message\_id. The generated\_by identifier groups messages by generation run but does not identify the user message that opened the turn. **finishReason** `string` Why the model stopped, verbatim from the provider: "stop", "tool\_calls", "length", "error". Empty for historical messages. **status** `any` Generation status reported for the next segment after tool results are submitted. Execution state of an agent generation run, separate from the reason a terminal run ended. The terminal states are COMPLETED, FAILED, CANCELLED and TIMED\_OUT. Treat every other or unrecognized value as non-terminal. Reasons such as rejected, malformed or discarded belong in the reason field rather than in this status.
| Value | No. | Form | Meaning | |---|---|---|---| | `AGENT_STATUS_ACTIVE` | 0 | Canonical | The run is active and has not yet reached a more specific execution phase or terminal outcome. | | `AGENT_STATUS_GENERATING` | 1 | Canonical | The run is generating a model response. | | `AGENT_STATUS_EXECUTING_TOOLS` | 2 | Canonical | The run is executing server-side tools. | | `AGENT_STATUS_COMPLETED` | 3 | Canonical | The run finished successfully. | | `AGENT_STATUS_FAILED` | 4 | Canonical | The run ended with a failure; inspect its error or end reason. | | `AGENT_STATUS_QUEUED` | 5 | Canonical | See meaning below. | | `AGENT_STATUS_AWAITING_CLIENT_TOOLS` | 6 | Canonical | The run is waiting for the caller to execute client-side tools and submit their results. This is a non-terminal phase. EXECUTING\_TOOLS instead means the server is running an MCP tool. | | `AGENT_STATUS_CANCELLED` | 7 | Canonical | See meaning below. | | `AGENT_STATUS_TIMED_OUT` | 8 | Canonical | See meaning below. | **`AGENT_STATUS_QUEUED`** The incoming message is queued behind an ongoing run under the queue interruption policy. Message was queued due to QUEUE interrupt policy **`AGENT_STATUS_CANCELLED`** The run ended because a client or its invocation cancelled it. Terminal: stopped by a client cancel or a cancelled invocation **`AGENT_STATUS_TIMED_OUT`** The run ended because a run-level time limit elapsed. Terminal: a run-level bound elapsed
Exactly one of: Variant 1: Type: `string` Enum: `AGENT_STATUS_ACTIVE`, `AGENT_STATUS_GENERATING`, `AGENT_STATUS_EXECUTING_TOOLS`, `AGENT_STATUS_COMPLETED`, `AGENT_STATUS_FAILED`, `AGENT_STATUS_QUEUED`, `AGENT_STATUS_AWAITING_CLIENT_TOOLS`, `AGENT_STATUS_CANCELLED`, `AGENT_STATUS_TIMED_OUT` Variant 2: Type: `integer(int32)` **aggregateUsage** `any` Aggregated model usage reported for the generation run. All of: Variant 1: Usage accounting Model reference: [Usage](/api/models/schema-1j1vov2uoh#response). **promptTokens** `string(int64)` Prompt-token usage reported by the model provider. Pattern: ^-?\d+$ **completionTokens** `string(int64)` Completion-token usage reported by the model provider. Pattern: ^-?\d+$ **totalTokens** `string(int64)` Total token usage reported by the model provider. Pattern: ^-?\d+$ **costEstimate** `any` Estimated cost in USD. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completionTokensDetails** `any` Breakdown of completion tokens. All of: Variant 1: Breakdown of completion-token usage. Categories are measured by different upstream tokenizers and need not sum to completion\_tokens; reasoning\_tokens can exceed completion\_tokens. One category must not be derived by subtracting the others. Model reference: [CompletionTokensDetails](/api/models/schema-1i6q4qpg72#response). **reasoningTokens** `string(int64)` Tokens used for reasoning/thinking. Pattern: ^-?\d+$ **imageTokens** `string(int64)` Completion tokens emitted as image output. Pattern: ^-?\d+$ **audioTokens** `string(int64)` Completion tokens emitted as audio output. Pattern: ^-?\d+$ **promptTokensDetails** `any` Breakdown of prompt tokens (cache). All of: Variant 1: Breakdown of prompt token usage by category (input-side cache accounting) Subset semantics: cached\_tokens and cache\_write\_tokens are a breakdown *of* prompt\_tokens, so cached\_tokens + cache\_write\_tokens \<= Usage.prompt\_tokens. Ordinary (full-rate) prompt tokens = prompt\_tokens - cached\_tokens - cache\_write\_tokens. audio\_tokens / video\_tokens are modality breakdowns of prompt\_tokens (also a subset). Model reference: [PromptTokensDetails](/api/models/schema-1ivj82m55o#response). **cachedTokens** `string(int64)` Prompt tokens served from cache (cache READ). Pattern: ^-?\d+$ **cacheWriteTokens** `string(int64)` Prompt tokens written to cache this call (cache WRITE). Pattern: ^-?\d+$ **audioTokens** `string(int64)` Prompt tokens from audio input (multimodal). Pattern: ^-?\d+$ **videoTokens** `string(int64)` Prompt tokens from video input (multimodal). Pattern: ^-?\d+$ **costDetails** `any` Breakdown of upstream provider cost (BYOK routes). All of: Variant 1: Breakdown of model-provider cost. When the customer supplies the provider key, usage.cost is zero and upstream\_inference\_cost reports the provider spend, split into prompt and completion components. Model reference: [CostDetails](/api/models/schema-1ia0h761lm#response). **upstreamInferenceCost** `any` Total upstream provider cost (USD) on BYOK routes. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferencePromptCost** `any` Upstream cost attributed to prompt tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **upstreamInferenceCompletionCost** `any` Upstream cost attributed to completion tokens (USD). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **isByok** `boolean` Whether this generation used the customer's own model-provider key. **pendingClientTools** `array[llm_v1_common_v1_ToolCall]` Tool calls dispatched for execution by the client. A single structured tool call emitted by the model [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat) is the client answer window. Expiry ends that wait and rejects late results; the timeout policy determines the outcome. Model reference: [ToolCall](/api/models/schema-1it6mqsqoo#response). **id** `string` Provider-supplied call id. **name** `string` Name of the tool or function being invoked. **argumentsJson** `map[string, any]` JSON object payload. **status** `any` Execution status recorded for the tool call. Execution state of a tool call, including approval waiting and terminal outcomes. The terminal outcomes are COMPLETED, FAILED, CANCELLED and TIMED\_OUT; inspect ToolCall.end\_reason for why a call ended rather than treating the reason as another status. Use a listed execution status. The end reason explains the outcome separately from the status.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_EXECUTION_STATUS_PENDING` | 0 | Canonical | The tool call is waiting to begin execution. | | `TOOL_EXECUTION_STATUS_EXECUTING` | 1 | Canonical | The tool call is currently executing. | | `TOOL_EXECUTION_STATUS_COMPLETED` | 2 | Canonical | The tool call completed successfully. This is a terminal outcome. | | `TOOL_EXECUTION_STATUS_FAILED` | 3 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. | | `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 4 | Canonical | The tool call is waiting for approval before it can execute. | | `TOOL_EXECUTION_STATUS_CANCELLED` | 5 | Canonical | The tool call was cancelled before normal completion. | | `TOOL_EXECUTION_STATUS_TIMED_OUT` | 6 | Canonical | Tool execution ended because its time limit elapsed. |
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_EXECUTION_STATUS_PENDING`, `TOOL_EXECUTION_STATUS_EXECUTING`, `TOOL_EXECUTION_STATUS_COMPLETED`, `TOOL_EXECUTION_STATUS_FAILED`, `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, `TOOL_EXECUTION_STATUS_CANCELLED`, `TOOL_EXECUTION_STATUS_TIMED_OUT` Variant 2: Type: `integer(int32)` **resultJson** `map[string, any]` Tool execution result (object). **executedAt** `string(date-time)` Time when the tool execution was recorded. **serverId** `string` Which server provides this tool (for MCP tools). **isClientTool** `boolean` True if this is a client-side tool handled by client. **description** `string` Tool description captured from the resolved tool definition when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. **parametersJsonSchema** `map[string, any]` JSON Schema describing the tool’s input arguments. **requiresApprovalAt** `string(date-time)` Deadline for an approval decision, calculated from the effective approval timeout. This is not the time the call began waiting. An approval received after the deadline is rejected. **approvedAt** `string(date-time)` Timestamp when approval decision was recorded (if approved/rejected) **approvedBy** `string` Identifier of the approver (user id, email, or actor key) **executionDuration** `string` End-to-end execution duration once terminal (includes tool server latency or client-side time) Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **endReason** `string` Why this call ended, in one short phrase — "approval rejected", "approval timeout", or the underlying error. Set only once `status` is terminal, and empty on a clean COMPLETED. Use this reason to distinguish a rejection from a failure without parsing the tool result. **clientToolDeadlineAt** `string(date-time)` Deadline by which the client must submit a result for this call, stamped when the call is dispatched to a caller. **clientToolCursor** `string(int64)` Latest client-tool dispatch sequence represented by this response. Pattern: ^-?\d+$ **error** `any` Structured error for partial success scenarios. Full failures propagate as TerminalError → HTTP error status + RpcError JSON body. All of: Variant 1: Error payload containing an API-defined error code, a message and structured details. Interpret `code` using the ErrorCode enumeration published with this API; numeric equivalence with `google.rpc.Status` is not implied. Model reference: [RpcError](/api/models/schema-1fajlacjs0#response). **code** `any` Machine-readable error code. Clients switch on this field. API-defined categories describing why a request or operation failed. Use the published symbolic name and accompanying error details. These numeric assignments are not interchangeable with `google.rpc.Code`.
| Value | No. | Form | Meaning | |---|---|---|---| | `ERROR_CODE_CANCELLED` | 0 | Canonical | See meaning below. | | `ERROR_CODE_UNKNOWN` | 1 | Canonical | See meaning below. | | `ERROR_CODE_INVALID_ARGUMENT` | 2 | Canonical | See meaning below. | | `ERROR_CODE_DEADLINE_EXCEEDED` | 3 | Canonical | See meaning below. | | `ERROR_CODE_NOT_FOUND` | 4 | Canonical | See meaning below. | | `ERROR_CODE_ALREADY_EXISTS` | 5 | Canonical | See meaning below. | | `ERROR_CODE_PERMISSION_DENIED` | 6 | Canonical | See meaning below. | | `ERROR_CODE_RESOURCE_EXHAUSTED` | 7 | Canonical | See meaning below. | | `ERROR_CODE_FAILED_PRECONDITION` | 8 | Canonical | See meaning below. | | `ERROR_CODE_ABORTED` | 9 | Canonical | See meaning below. | | `ERROR_CODE_OUT_OF_RANGE` | 10 | Canonical | See meaning below. | | `ERROR_CODE_UNIMPLEMENTED` | 11 | Canonical | See meaning below. | | `ERROR_CODE_INTERNAL` | 12 | Canonical | See meaning below. | | `ERROR_CODE_UNAVAILABLE` | 13 | Canonical | See meaning below. | | `ERROR_CODE_DATA_LOSS` | 14 | Canonical | See meaning below. | | `ERROR_CODE_UNAUTHENTICATED` | 15 | Canonical | See meaning below. | | `ERROR_CODE_MODEL_INVALID` | 16 | Canonical | See meaning below. | | `ERROR_CODE_MODEL_UNAVAILABLE` | 17 | Canonical | See meaning below. | | `ERROR_CODE_MODERATION_FLAGGED` | 18 | Canonical | See meaning below. | | `ERROR_CODE_GENERATION_FAILED` | 19 | Canonical | See meaning below. | | `ERROR_CODE_TOOL_EXECUTION_FAILED` | 20 | Canonical | See meaning below. | | `ERROR_CODE_UPSTREAM_PROVIDER` | 21 | Canonical | See meaning below. | | `ERROR_CODE_VALIDATION_EXHAUSTED` | 22 | Canonical | See meaning below. | | `ERROR_CODE_PAYMENT_REQUIRED` | 23 | Canonical | See meaning below. | **`ERROR_CODE_CANCELLED`** The caller cancelled the operation before it completed. Canonical error categories. 499 — Cancelled by caller **`ERROR_CODE_UNKNOWN`** The operation failed without a more specific error classification. 500 — Unknown error **`ERROR_CODE_INVALID_ARGUMENT`** The request contains an invalid argument or field value. 400 — Bad input, invalid field values **`ERROR_CODE_DEADLINE_EXCEEDED`** The operation did not complete before its deadline. 504 — Operation timed out **`ERROR_CODE_NOT_FOUND`** The requested resource does not exist or could not be found. 404 — Resource does not exist **`ERROR_CODE_ALREADY_EXISTS`** The requested creation conflicts with a resource that already exists. 409 — Resource already exists **`ERROR_CODE_PERMISSION_DENIED`** The authenticated caller is not permitted to perform the operation. 403 — Caller lacks permission **`ERROR_CODE_RESOURCE_EXHAUSTED`** A quota, rate limit or other capacity limit prevented the operation. 429 — Rate limited or quota exceeded **`ERROR_CODE_FAILED_PRECONDITION`** The operation requires a system or resource state that is not currently satisfied. 400 — System not in required state **`ERROR_CODE_ABORTED`** The operation was aborted, for example by a concurrent modification conflict. 409 — Concurrent conflict, retry may succeed **`ERROR_CODE_OUT_OF_RANGE`** An argument is outside the range supported by this operation. 400 — Value outside valid range **`ERROR_CODE_UNIMPLEMENTED`** The requested operation is not implemented. 501 — Not implemented **`ERROR_CODE_INTERNAL`** An internal failure prevented the operation from completing. 500 — Internal error **`ERROR_CODE_UNAVAILABLE`** The service or a required dependency is temporarily unavailable. 503 — Service temporarily unavailable **`ERROR_CODE_DATA_LOSS`** The operation encountered unrecoverable loss or corruption of data. 500 — Unrecoverable data loss **`ERROR_CODE_UNAUTHENTICATED`** Authentication credentials are missing or invalid. 401 — Missing or invalid credentials **`ERROR_CODE_MODEL_INVALID`** The requested model identifier is absent from the model catalog. Domain-specific error categories. 400 — Model ID not found in catalog **`ERROR_CODE_MODEL_UNAVAILABLE`** The model exists, but no provider is currently available to serve it. 503 — Model exists but all providers are down **`ERROR_CODE_MODERATION_FLAGGED`** Content moderation flagged the submitted content. 403 — Input flagged by content moderation **`ERROR_CODE_GENERATION_FAILED`** Model generation failed after its configured attempts. 500 — LLM generation failed after retries **`ERROR_CODE_TOOL_EXECUTION_FAILED`** Execution of a requested tool failed. 500 — MCP tool call failed **`ERROR_CODE_UPSTREAM_PROVIDER`** An upstream model provider returned an error. 503 — Upstream provider returned error **`ERROR_CODE_VALIDATION_EXHAUSTED`** Structured-output validation still failed after the configured attempts. 500 — Structured output validation failed after all retries **`ERROR_CODE_PAYMENT_REQUIRED`** The account lacks the credits required for the operation. 402 — Insufficient credits
Exactly one of: Variant 1: Type: `string` Enum: `ERROR_CODE_CANCELLED`, `ERROR_CODE_UNKNOWN`, `ERROR_CODE_INVALID_ARGUMENT`, `ERROR_CODE_DEADLINE_EXCEEDED`, `ERROR_CODE_NOT_FOUND`, `ERROR_CODE_ALREADY_EXISTS`, `ERROR_CODE_PERMISSION_DENIED`, `ERROR_CODE_RESOURCE_EXHAUSTED`, `ERROR_CODE_FAILED_PRECONDITION`, `ERROR_CODE_ABORTED`, `ERROR_CODE_OUT_OF_RANGE`, `ERROR_CODE_UNIMPLEMENTED`, `ERROR_CODE_INTERNAL`, `ERROR_CODE_UNAVAILABLE`, `ERROR_CODE_DATA_LOSS`, `ERROR_CODE_UNAUTHENTICATED`, `ERROR_CODE_MODEL_INVALID`, `ERROR_CODE_MODEL_UNAVAILABLE`, `ERROR_CODE_MODERATION_FLAGGED`, `ERROR_CODE_GENERATION_FAILED`, `ERROR_CODE_TOOL_EXECUTION_FAILED`, `ERROR_CODE_UPSTREAM_PROVIDER`, `ERROR_CODE_VALIDATION_EXHAUSTED`, `ERROR_CODE_PAYMENT_REQUIRED` Variant 2: Type: `integer(int32)` **message** `string` Human-readable error description. Intended for developers, not end users. Must not be parsed programmatically — use code and details instead. **isTerminal** `boolean` Whether this error is classified as terminal (non-retryable). A terminal error should not trigger automatic retries of the failed operation. A nonterminal error may reflect a transient condition that can resolve on retry. **details** `any` Structured error details. At most one of each detail type. All of: Variant 1: Typed error details container. Concrete fields instead of Any for type safety across languages. At most one of each detail type. Model reference: [ErrorDetails](/api/models/schema-1f7d7kh0s1#response). **errorInfo** `any` Identifies the error for machine consumption. Required on all errors by this error contract. All of: Variant 1: Machine-readable error identification (per AIP-193, every error must include this). Model reference: [ErrorInfo](/api/models/schema-1es9uii84j#response). **reason** `string` Stable machine-readable reason string (e.g., "MODEL\_NOT\_FOUND", "RATE\_LIMITED", "MODERATION\_FLAGGED"). Unique within the domain. Clients may switch on this field. **domain** `string` Machine-readable namespace identifying the origin of the error. **metadata** `map[string, string]` Arbitrary key-value metadata. If the message field mentions a specific value (model name, field path, etc.), it MUST also appear here. **retryInfo** `any` Retry guidance for transient errors. All of: Variant 1: Retry guidance for transient errors. Model reference: [RetryInfo](/api/models/schema-1f439vae2d#response). **retryDelayMs** `string(int64)` Suggested minimum delay before retrying, in milliseconds. Pattern: ^-?\d+$ **fieldViolations** `array[common_v1_FieldViolation]` Field-level validation failures. A single field-level validation violation. Model reference: [FieldViolation](/api/models/schema-1eu5noj3g1#response). **field** `string` Dot-separated path to the field (e.g., "generation\_config.model"). **description** `string` Human-readable description of the violation. **upstreamError** `any` Upstream provider error context. All of: Variant 1: Context from an upstream provider error, including the provider name when reported. Model reference: [UpstreamError](/api/models/schema-1f66rlcp5a#response). **provider** `string` Name of the upstream provider that reported the error. **statusCode** `string(int64)` HTTP status code returned by the provider. Pattern: ^-?\d+$ **rawBody** `string` Raw error body from the provider, truncated to 512 bytes. **modelError** `any` Model-specific error context. All of: Variant 1: Model-specific error context. Model reference: [ModelError](/api/models/schema-1f2939tg20#response). **modelId** `string` The model ID that caused the error. **reason** `string` Why the model failed (e.g., "invalid", "unavailable", "moderation\_flagged"). **alternativesTried** `array[string]` Alternative models that were tried or could be tried. Type: `string` **helpLinks** `array[common_v1_HelpLink]` Help links for error resolution. A help link for error resolution. Model reference: [HelpLink](/api/models/schema-1f0qdi91b8#response). **url** `string` URL to documentation or resolution guide. **description** `string` Description of what the link provides. #### conversations-submitClientToolResultsSync-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "runId": "example_123", "messages": [ { "role": "ROLE_SYSTEM", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Example text", "cachePreferred": true } ], "toolCalls": [ { "id": "example_123", "name": "example", "status": "TOOL_EXECUTION_STATUS_PENDING", "serverId": "example_123", "isClientTool": true, "description": "example", "approvedBy": "example", "endReason": "example" } ], "name": "example", "timestamp": "2026-09-16T12:00:00Z", "messageId": "example_123", "annotations": [ { "kind": "ANNOTATION_KIND_URL_CITATION" } ], "sequence": "1", "generatedBy": "example", "usage": { "promptTokens": 1, "completionTokens": 1, "totalTokens": 1, "costEstimate": 1, "isByok": true }, "model": "example", "generationContext": { "languagePreference": "en-US", "resolvedSystemPrompt": "Example text", "profileId": "example_123", "model": "example", "promptSource": "PROMPT_SOURCE_CLIENT_OVERRIDE", "profileVersion": 1, "fragmentsVersion": 1, "profileRenderFailed": true, "resolvedPromptHash": "Example text", "resolvedUserContext": "Example text" }, "clientContext": {}, "feedback": [ { "kind": "FEEDBACK_KIND_THUMB", "thumbUp": true, "reason": "example", "ratedBy": "example" } ], "sourceUserMessageId": "example_123", "finishReason": "example" } ], "status": "AGENT_STATUS_ACTIVE", "aggregateUsage": { "promptTokens": 1, "completionTokens": 1, "totalTokens": 1, "costEstimate": 1, "completionTokensDetails": { "reasoningTokens": 1, "imageTokens": 1, "audioTokens": 1 }, "promptTokensDetails": { "cachedTokens": 1, "cacheWriteTokens": 1, "audioTokens": 1, "videoTokens": 1 }, "costDetails": { "upstreamInferenceCost": 1, "upstreamInferencePromptCost": 1, "upstreamInferenceCompletionCost": 1 }, "isByok": true }, "pendingClientTools": [ { "id": "example_123", "name": "example", "argumentsJson": { "example": "value" }, "status": "TOOL_EXECUTION_STATUS_PENDING", "resultJson": { "example": "value" }, "executedAt": "2026-09-16T12:00:00Z", "serverId": "example_123", "isClientTool": true, "description": "example", "parametersJsonSchema": { "example": "value" }, "requiresApprovalAt": "2026-09-16T12:00:00Z", "approvedAt": "2026-09-16T12:00:00Z", "approvedBy": "example", "executionDuration": "1s", "endReason": "example", "clientToolDeadlineAt": "2026-09-16T12:00:00Z" } ], "clientToolCursor": 1, "error": { "code": "ERROR_CODE_CANCELLED", "message": "example", "isTerminal": true, "details": {} } } ``` #### cookbook-managed-agents-delegation-approvals-build-agent-with-tools-json-03-response Illustrative response for Step 3: Navigate once and report what happened. Replace example resource identifiers with your own authorized values. ```json { "runId": "64403669-5989-4ec3-ad9c-d84223f9679f", "status": "AGENT_STATUS_COMPLETED", "messages": [ { "role": "ROLE_ASSISTANT", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Taking you to your profile." } ], "finishReason": "stop" } ] } ``` #### cookbook-managed-agents-delegation-approvals-using-tools-json-03-response Illustrative response for Step 2: Validate, open and return the real result. Replace example resource identifiers with your own authorized values. ```json { "runId": "cf9f08e7-4486-41e1-bac1-b9428d1aeb85", "status": "AGENT_STATUS_COMPLETED", "messages": [ { "role": "ROLE_ASSISTANT", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "I've opened your profile." } ], "finishReason": "stop" } ] } ``` Document ID: `DOC-MA-conversations-api-submitClientToolResultsSync`. [Section identities and revisions](/documentation-manifest.json). - Submit client-side tool results and wait for the next segment: `DOC-MA-conversations-api-submitClientToolResultsSync#overview` - Request: `DOC-MA-conversations-api-submitClientToolResultsSync#request` - Responses: `DOC-MA-conversations-api-submitClientToolResultsSync#responses` --- # Submit client-side tool execution results URL: https://docs.travila.ai/api/conversations/submit-client-tool-results **POST** `/api/v1/llm/submit-client-tool-results` Submits results for client-side tool calls and returns without waiting for the next generation segment. While the conversation still identifies a run, workflow validation rejects unmatched calls with `400` and already-resolved calls with `410`. If no active run is recorded, this call can succeed without applying any results. Reconcile stored run and tool state before treating HTTP success as confirmation that the results were applied. A run can request further batches. Read pending client tools, execute each new batch and submit its results until the run reaches a terminal outcome. An unknown status requires reconciliation with a bounded wait, not an assumption of success. See [Messages and run outcomes](/api/conversations/messages-and-runs) for outcome handling and the synchronous client-tool loop. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for returning client-side tool execution results to the conversation. **conversationKey** `string` **required** Identifier of the conversation thread. Minimum length: 1 **results** `array[llm_v1_common_v1_ClientToolResult]` Execution results for tools that ran on the client. Result submitted by the caller for a client-side tool call. Both tool\_call\_id and tool\_name must identify the same pending call. When submission reaches workflow validation, either missing value causes a 400 response. Copy the call's id and name into these result fields, rather than submitting the pending ToolCall unchanged. Fields marked optional in the wire shape may still be required for a valid workflow submission. Both `tool_call_id` and `tool_name` must identify the same pending call; workflow validation rejects either missing value. Model reference: [ClientToolResult](/api/models/schema-1i4kndhs46#request). **toolCallId** `string` Required call identifier, copied from the pending ToolCall.id. **toolName** `string` Required tool name, copied from the pending ToolCall.name. **resultJson** `map[string, any]` Structured output for a matched pending call. A nonempty object records COMPLETED; an empty or omitted object records FAILED, including when the client could not complete the action. **error** `any` Supplied error detail. The current result handler does not consume this field; the presence of a nonempty result\_json alone determines whether the tool is recorded as completed. All of: Variant 1: Error payload containing an API-defined error code, a message and structured details. Interpret `code` using the ErrorCode enumeration published with this API; numeric equivalence with `google.rpc.Status` is not implied. Model reference: [RpcError](/api/models/schema-1fajlacjs0#request). **code** `any` Machine-readable error code. Clients switch on this field. API-defined categories describing why a request or operation failed. Use the published symbolic name and accompanying error details. These numeric assignments are not interchangeable with `google.rpc.Code`.
| Value | No. | Form | Meaning | |---|---|---|---| | `ERROR_CODE_CANCELLED` | 0 | Canonical | See meaning below. | | `ERROR_CODE_UNKNOWN` | 1 | Canonical | See meaning below. | | `ERROR_CODE_INVALID_ARGUMENT` | 2 | Canonical | See meaning below. | | `ERROR_CODE_DEADLINE_EXCEEDED` | 3 | Canonical | See meaning below. | | `ERROR_CODE_NOT_FOUND` | 4 | Canonical | See meaning below. | | `ERROR_CODE_ALREADY_EXISTS` | 5 | Canonical | See meaning below. | | `ERROR_CODE_PERMISSION_DENIED` | 6 | Canonical | See meaning below. | | `ERROR_CODE_RESOURCE_EXHAUSTED` | 7 | Canonical | See meaning below. | | `ERROR_CODE_FAILED_PRECONDITION` | 8 | Canonical | See meaning below. | | `ERROR_CODE_ABORTED` | 9 | Canonical | See meaning below. | | `ERROR_CODE_OUT_OF_RANGE` | 10 | Canonical | See meaning below. | | `ERROR_CODE_UNIMPLEMENTED` | 11 | Canonical | See meaning below. | | `ERROR_CODE_INTERNAL` | 12 | Canonical | See meaning below. | | `ERROR_CODE_UNAVAILABLE` | 13 | Canonical | See meaning below. | | `ERROR_CODE_DATA_LOSS` | 14 | Canonical | See meaning below. | | `ERROR_CODE_UNAUTHENTICATED` | 15 | Canonical | See meaning below. | | `ERROR_CODE_MODEL_INVALID` | 16 | Canonical | See meaning below. | | `ERROR_CODE_MODEL_UNAVAILABLE` | 17 | Canonical | See meaning below. | | `ERROR_CODE_MODERATION_FLAGGED` | 18 | Canonical | See meaning below. | | `ERROR_CODE_GENERATION_FAILED` | 19 | Canonical | See meaning below. | | `ERROR_CODE_TOOL_EXECUTION_FAILED` | 20 | Canonical | See meaning below. | | `ERROR_CODE_UPSTREAM_PROVIDER` | 21 | Canonical | See meaning below. | | `ERROR_CODE_VALIDATION_EXHAUSTED` | 22 | Canonical | See meaning below. | | `ERROR_CODE_PAYMENT_REQUIRED` | 23 | Canonical | See meaning below. | **`ERROR_CODE_CANCELLED`** The caller cancelled the operation before it completed. Canonical error categories. 499 — Cancelled by caller **`ERROR_CODE_UNKNOWN`** The operation failed without a more specific error classification. 500 — Unknown error **`ERROR_CODE_INVALID_ARGUMENT`** The request contains an invalid argument or field value. 400 — Bad input, invalid field values **`ERROR_CODE_DEADLINE_EXCEEDED`** The operation did not complete before its deadline. 504 — Operation timed out **`ERROR_CODE_NOT_FOUND`** The requested resource does not exist or could not be found. 404 — Resource does not exist **`ERROR_CODE_ALREADY_EXISTS`** The requested creation conflicts with a resource that already exists. 409 — Resource already exists **`ERROR_CODE_PERMISSION_DENIED`** The authenticated caller is not permitted to perform the operation. 403 — Caller lacks permission **`ERROR_CODE_RESOURCE_EXHAUSTED`** A quota, rate limit or other capacity limit prevented the operation. 429 — Rate limited or quota exceeded **`ERROR_CODE_FAILED_PRECONDITION`** The operation requires a system or resource state that is not currently satisfied. 400 — System not in required state **`ERROR_CODE_ABORTED`** The operation was aborted, for example by a concurrent modification conflict. 409 — Concurrent conflict, retry may succeed **`ERROR_CODE_OUT_OF_RANGE`** An argument is outside the range supported by this operation. 400 — Value outside valid range **`ERROR_CODE_UNIMPLEMENTED`** The requested operation is not implemented. 501 — Not implemented **`ERROR_CODE_INTERNAL`** An internal failure prevented the operation from completing. 500 — Internal error **`ERROR_CODE_UNAVAILABLE`** The service or a required dependency is temporarily unavailable. 503 — Service temporarily unavailable **`ERROR_CODE_DATA_LOSS`** The operation encountered unrecoverable loss or corruption of data. 500 — Unrecoverable data loss **`ERROR_CODE_UNAUTHENTICATED`** Authentication credentials are missing or invalid. 401 — Missing or invalid credentials **`ERROR_CODE_MODEL_INVALID`** The requested model identifier is absent from the model catalog. Domain-specific error categories. 400 — Model ID not found in catalog **`ERROR_CODE_MODEL_UNAVAILABLE`** The model exists, but no provider is currently available to serve it. 503 — Model exists but all providers are down **`ERROR_CODE_MODERATION_FLAGGED`** Content moderation flagged the submitted content. 403 — Input flagged by content moderation **`ERROR_CODE_GENERATION_FAILED`** Model generation failed after its configured attempts. 500 — LLM generation failed after retries **`ERROR_CODE_TOOL_EXECUTION_FAILED`** Execution of a requested tool failed. 500 — MCP tool call failed **`ERROR_CODE_UPSTREAM_PROVIDER`** An upstream model provider returned an error. 503 — Upstream provider returned error **`ERROR_CODE_VALIDATION_EXHAUSTED`** Structured-output validation still failed after the configured attempts. 500 — Structured output validation failed after all retries **`ERROR_CODE_PAYMENT_REQUIRED`** The account lacks the credits required for the operation. 402 — Insufficient credits
Exactly one of: Variant 1: Type: `string` Enum: `ERROR_CODE_CANCELLED`, `ERROR_CODE_UNKNOWN`, `ERROR_CODE_INVALID_ARGUMENT`, `ERROR_CODE_DEADLINE_EXCEEDED`, `ERROR_CODE_NOT_FOUND`, `ERROR_CODE_ALREADY_EXISTS`, `ERROR_CODE_PERMISSION_DENIED`, `ERROR_CODE_RESOURCE_EXHAUSTED`, `ERROR_CODE_FAILED_PRECONDITION`, `ERROR_CODE_ABORTED`, `ERROR_CODE_OUT_OF_RANGE`, `ERROR_CODE_UNIMPLEMENTED`, `ERROR_CODE_INTERNAL`, `ERROR_CODE_UNAVAILABLE`, `ERROR_CODE_DATA_LOSS`, `ERROR_CODE_UNAUTHENTICATED`, `ERROR_CODE_MODEL_INVALID`, `ERROR_CODE_MODEL_UNAVAILABLE`, `ERROR_CODE_MODERATION_FLAGGED`, `ERROR_CODE_GENERATION_FAILED`, `ERROR_CODE_TOOL_EXECUTION_FAILED`, `ERROR_CODE_UPSTREAM_PROVIDER`, `ERROR_CODE_VALIDATION_EXHAUSTED`, `ERROR_CODE_PAYMENT_REQUIRED` Variant 2: Type: `integer(int32)` **message** `string` Human-readable error description. Intended for developers, not end users. Must not be parsed programmatically — use code and details instead. **isTerminal** `boolean` Whether this error is classified as terminal (non-retryable). A terminal error should not trigger automatic retries of the failed operation. A nonterminal error may reflect a transient condition that can resolve on retry. **details** `any` Structured error details. At most one of each detail type. All of: Variant 1: Typed error details container. Concrete fields instead of Any for type safety across languages. At most one of each detail type. Model reference: [ErrorDetails](/api/models/schema-1f7d7kh0s1#request). **errorInfo** `any` Identifies the error for machine consumption. Required on all errors by this error contract. All of: Variant 1: Machine-readable error identification (per AIP-193, every error must include this). Model reference: [ErrorInfo](/api/models/schema-1es9uii84j#request). **reason** `string` Stable machine-readable reason string (e.g., "MODEL\_NOT\_FOUND", "RATE\_LIMITED", "MODERATION\_FLAGGED"). Unique within the domain. Clients may switch on this field. **domain** `string` Machine-readable namespace identifying the origin of the error. **metadata** `map[string, string]` Arbitrary key-value metadata. If the message field mentions a specific value (model name, field path, etc.), it MUST also appear here. **retryInfo** `any` Retry guidance for transient errors. All of: Variant 1: Retry guidance for transient errors. Model reference: [RetryInfo](/api/models/schema-1f439vae2d#request). **retryDelayMs** `string(int64)` Suggested minimum delay before retrying, in milliseconds. Pattern: ^-?\d+$ **fieldViolations** `array[common_v1_FieldViolationInput]` Field-level validation failures. A single field-level validation violation. Model reference: [FieldViolation](/api/models/schema-1eu5noj3g1#request). **field** `string` Dot-separated path to the field (e.g., "generation\_config.model"). **description** `string` Human-readable description of the violation. **upstreamError** `any` Upstream provider error context. All of: Variant 1: Context from an upstream provider error, including the provider name when reported. Model reference: [UpstreamError](/api/models/schema-1f66rlcp5a#request). **provider** `string` Name of the upstream provider that reported the error. **statusCode** `string(int64)` HTTP status code returned by the provider. Pattern: ^-?\d+$ **rawBody** `string` Raw error body from the provider, truncated to 512 bytes. **modelError** `any` Model-specific error context. All of: Variant 1: Model-specific error context. Model reference: [ModelError](/api/models/schema-1f2939tg20#request). **modelId** `string` The model ID that caused the error. **reason** `string` Why the model failed (e.g., "invalid", "unavailable", "moderation\_flagged"). **alternativesTried** `array[string]` Alternative models that were tried or could be tried. Type: `string` **helpLinks** `array[common_v1_HelpLinkInput]` Help links for error resolution. A help link for error resolution. Model reference: [HelpLink](/api/models/schema-1f0qdi91b8#request). **url** `string` URL to documentation or resolution guide. **description** `string` Description of what the link provides. #### conversations-submitClientToolResults-request Return a result for a pending client tool call; use its actual ID, name and expected result shape. ```json { "conversationKey": "example_123", "results": [ { "toolCallId": "tool_call_123", "toolName": "lookup_booking", "resultJson": { "bookingStatus": "confirmed" } } ] } ``` ## Responses ### 200 — Client tool results submitted Content type: `application/json` Result of returning client-side tool execution results to the conversation. Returned workflow information can be used to continue reconciliation through the pull API. **runId** `string` Identifier of the generation run, usable for retrieving its result or status after submitting client-tool results. #### conversations-submitClientToolResults-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "runId": "example_123" } ``` Document ID: `DOC-MA-conversations-api-submitClientToolResults`. [Section identities and revisions](/documentation-manifest.json). - Submit client-side tool execution results: `DOC-MA-conversations-api-submitClientToolResults#overview` - Request: `DOC-MA-conversations-api-submitClientToolResults#request` - Responses: `DOC-MA-conversations-api-submitClientToolResults#responses` --- # Approve or reject pending tool calls URL: https://docs.travila.ai/api/conversations/submit-tool-approvals **POST** `/api/v1/llm/submit-tool-approvals` Submits approval decisions for pending calls. An accepted approval permits the conversation workflow to continue subject to execution checks; it is not a general authorization grant. Rejection prevents dispatch of a still-pending call and does not undo an action already executed elsewhere. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Approve a tool action and finish the conversation](/managed-agents/delegation-approvals/using-tools) · [Event catalog](/api/events) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for submitting decisions for tool calls awaiting approval. **conversationKey** `string` **required** Identifier of the conversation thread. Minimum length: 1 **approvals** `array[llm_v1_common_v1_ToolApproval]` Approval decisions for the identified pending tool calls. Approval decision for a specific tool call Model reference: [ToolApproval](/api/models/schema-1j7jbpfsda#request). **toolCallId** `string` Identifier of the tool call whose execution is being approved or rejected. **toolName** `string` Name of the tool associated with the call or result. **approved** `boolean` Whether the caller approves execution of the identified tool call. **reason** `string` Optional rejection reason. #### conversations-submitToolApprovals-request Approve a pending tool call; use its ID from listPendingApprovals. ```json { "conversationKey": "example_123", "approvals": [ { "toolCallId": "tool_call_123", "approved": true } ] } ``` #### cookbook-managed-agents-delegation-approvals-using-tools-02-request Guide request for Step 3: Submit the decision and inspect the outcome. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "support-chat-001", "approvals": [ { "toolCallId": "call_abc123", "approved": true } ] } ``` ## Responses ### 200 — Approvals submitted Content type: `application/json` Result of submitting decisions for tool calls awaiting approval. This message declares no response fields. #### conversations-submitToolApprovals-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json {} ``` Document ID: `DOC-MA-conversations-api-submitToolApprovals`. [Section identities and revisions](/documentation-manifest.json). - Approve or reject pending tool calls: `DOC-MA-conversations-api-submitToolApprovals#overview` - Request: `DOC-MA-conversations-api-submitToolApprovals#request` - Responses: `DOC-MA-conversations-api-submitToolApprovals#responses` --- # Update context management settings URL: https://docs.travila.ai/api/conversations/update-context-management-settings **POST** `/api/v1/llm/update-context-management-settings` Updates how the conversation selects and compacts context for later generations. See [Context and compaction](/api/conversations/context-and-compaction) for strategy selection and outcome handling. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Resume a long conversation with a compacted history](/managed-agents/conversations/context-management) · [Context and compaction](/api/conversations/context-and-compaction) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for updating the conversation’s context compaction configuration. **conversationKey** `string` **required** Identifier of the conversation thread. Minimum length: 1 **contextManagementSettings** `any` Configuration governing the conversation’s context management and compaction. All of: Variant 1: Configuration for context management Model reference: [ContextManagementSettings](/api/models/schema-1hgrvsu34j#request). **strategy** `any` Context management strategy selected for the conversation. How stored conversation history is selected or summarized for model context.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTEXT_STRATEGY_COMPACTION` | 0 | Canonical | Use completed compaction summaries and remaining history; fall back to windowing when no completed summary is available. | | `CONTEXT_STRATEGY_WINDOWING` | 1 | Canonical | Keep a bounded window of recent conversation messages according to the windowing configuration. | | `CONTEXT_STRATEGY_NONE` | 2 | Canonical | Pass the conversation history without applying compaction or windowing. |
Exactly one of: Variant 1: Type: `string` Enum: `CONTEXT_STRATEGY_COMPACTION`, `CONTEXT_STRATEGY_WINDOWING`, `CONTEXT_STRATEGY_NONE` Variant 2: Type: `integer(int32)` **compactionConfig** `any` Configuration applied when summarizing the conversation context. All of: Variant 1: Configuration for compaction strategy Model reference: [CompactionConfig](/api/models/schema-1hbvkcgu5m#request). **mode** `any` Context compaction mode selected by the operation. SYNC, ASYNC Whether context compaction blocks the triggering operation or proceeds asynchronously.
| Value | No. | Form | Meaning | |---|---|---|---| | `COMPACTION_MODE_SYNC` | 0 | Canonical | Wait for compaction to finish before continuing the dependent operation. | | `COMPACTION_MODE_ASYNC` | 1 | Canonical | Start compaction asynchronously and apply its result when it becomes available. |
Exactly one of: Variant 1: Type: `string` Enum: `COMPACTION_MODE_SYNC`, `COMPACTION_MODE_ASYNC` Variant 2: Type: `integer(int32)` **threshold** `any` Token-count or context-window-percentage threshold that triggers compaction. All of: Variant 1: Threshold configuration for triggering compaction token\_count and percentage are mutually exclusive alternatives. Independent tracked fields do not enforce this relationship. Model reference: [ThresholdConfig](/api/models/schema-1frig4k431#request). **tokenCount** `string(int64)` Absolute token limit. Pattern: ^-?\d+$ **percentage** `string(int64)` % of model's context window. Pattern: ^-?\d+$ **generationConfig** `any` Separate config for compaction LLM calls. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#request). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#request). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#request). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#request). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#request). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#request). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinitionInput]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#request). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinitionInput]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRuleInput]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#request). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#request). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#request). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRuleInput]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#request). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#request). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfigInput]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#request). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#request). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#request). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#request). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) Minimum length: 2 Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$ **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#request). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" Maximum length: 50 **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" Enum: ``, `friendly`, `iso8601`, `date_only` Maximum length: 50 **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#request). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` **required** Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" Enum: `minimal`, `standard`, `verbose` **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#request). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#request). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **preserveRecent** `string(int64)` Messages to keep uncompacted. Pattern: ^-?\d+$ **windowingConfig** `any` Rules selecting the message window retained in model context. All of: Variant 1: Configuration for windowing strategy Model reference: [WindowingConfig](/api/models/schema-1he7ulevif#request). **maxMessages** `string(int64)` Maximum number of conversation messages to retain in the context window. Default: 100 Pattern: ^-?\d+$ **selectiveExclusionConfig** `any` Rules selecting content to omit from the model context. All of: Variant 1: Configuration for selective exclusion Model reference: [SelectiveExclusionConfig](/api/models/schema-1hc73qpaio#request). **excludeToolResults** `boolean` Whether tool-result content is excluded from model context. **excludeImages** `boolean` Whether image content is excluded from model context. **excludeFiles** `boolean` Whether file content is excluded from model context. **excludeReasoning** `boolean` When true, reasoning/thinking content parts are excluded from context #### conversations-updateContextManagementSettings-request Update the window size for an existing conversation already using the windowing strategy. ```json { "conversationKey": "example_123", "contextManagementSettings": { "strategy": "CONTEXT_STRATEGY_WINDOWING", "windowingConfig": { "maxMessages": 50 } } } ``` #### cookbook-managed-agents-conversations-context-management-01-request Guide request for Recipe: compact the older history, then continue the thread. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "support-chat-001", "contextManagementSettings": { "strategy": "CONTEXT_STRATEGY_COMPACTION", "compactionConfig": { "mode": "COMPACTION_MODE_SYNC", "threshold": { "percentage": 80 }, "preserveRecent": 10 } } } ``` #### cookbook-managed-agents-conversations-context-management-04-request Guide request for Variant: omit a file or tool result that later replies no longer need. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "support-chat-001", "contextManagementSettings": { "strategy": "CONTEXT_STRATEGY_COMPACTION", "selectiveExclusionConfig": { "excludeToolResults": true, "excludeImages": true } } } ``` ## Responses ### 200 — Context management settings updated Content type: `application/json` Result of updating the conversation’s context compaction configuration. **contextManagementSettings** `any` Configuration governing the conversation’s context management and compaction. All of: Variant 1: Configuration for context management Model reference: [ContextManagementSettings](/api/models/schema-1hgrvsu34j#response). **strategy** `any` Context management strategy selected for the conversation. How stored conversation history is selected or summarized for model context.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTEXT_STRATEGY_COMPACTION` | 0 | Canonical | Use completed compaction summaries and remaining history; fall back to windowing when no completed summary is available. | | `CONTEXT_STRATEGY_WINDOWING` | 1 | Canonical | Keep a bounded window of recent conversation messages according to the windowing configuration. | | `CONTEXT_STRATEGY_NONE` | 2 | Canonical | Pass the conversation history without applying compaction or windowing. |
Exactly one of: Variant 1: Type: `string` Enum: `CONTEXT_STRATEGY_COMPACTION`, `CONTEXT_STRATEGY_WINDOWING`, `CONTEXT_STRATEGY_NONE` Variant 2: Type: `integer(int32)` **compactionConfig** `any` Configuration applied when summarizing the conversation context. All of: Variant 1: Configuration for compaction strategy Model reference: [CompactionConfig](/api/models/schema-1hbvkcgu5m#response). **mode** `any` Context compaction mode selected by the operation. SYNC, ASYNC Whether context compaction blocks the triggering operation or proceeds asynchronously.
| Value | No. | Form | Meaning | |---|---|---|---| | `COMPACTION_MODE_SYNC` | 0 | Canonical | Wait for compaction to finish before continuing the dependent operation. | | `COMPACTION_MODE_ASYNC` | 1 | Canonical | Start compaction asynchronously and apply its result when it becomes available. |
Exactly one of: Variant 1: Type: `string` Enum: `COMPACTION_MODE_SYNC`, `COMPACTION_MODE_ASYNC` Variant 2: Type: `integer(int32)` **threshold** `any` Token-count or context-window-percentage threshold that triggers compaction. All of: Variant 1: Threshold configuration for triggering compaction token\_count and percentage are mutually exclusive alternatives. Independent tracked fields do not enforce this relationship. Model reference: [ThresholdConfig](/api/models/schema-1frig4k431#response). **tokenCount** `string(int64)` Absolute token limit. Pattern: ^-?\d+$ **percentage** `string(int64)` % of model's context window. Pattern: ^-?\d+$ **generationConfig** `any` Separate config for compaction LLM calls. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#response). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#response). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#response). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#response). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#response). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#response). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#response). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinition]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#response). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfig]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#response). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#response). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#response). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#response). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#response). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#response). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#response). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#response). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **preserveRecent** `string(int64)` Messages to keep uncompacted. Pattern: ^-?\d+$ **windowingConfig** `any` Rules selecting the message window retained in model context. All of: Variant 1: Configuration for windowing strategy Model reference: [WindowingConfig](/api/models/schema-1he7ulevif#response). **maxMessages** `string(int64)` Maximum number of conversation messages to retain in the context window. Default: 100 Pattern: ^-?\d+$ **selectiveExclusionConfig** `any` Rules selecting content to omit from the model context. All of: Variant 1: Configuration for selective exclusion Model reference: [SelectiveExclusionConfig](/api/models/schema-1hc73qpaio#response). **excludeToolResults** `boolean` Whether tool-result content is excluded from model context. **excludeImages** `boolean` Whether image content is excluded from model context. **excludeFiles** `boolean` Whether file content is excluded from model context. **excludeReasoning** `boolean` When true, reasoning/thinking content parts are excluded from context #### conversations-updateContextManagementSettings-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "contextManagementSettings": { "strategy": "CONTEXT_STRATEGY_COMPACTION", "compactionConfig": { "mode": "COMPACTION_MODE_SYNC", "preserveRecent": 1 }, "windowingConfig": { "maxMessages": 1 }, "selectiveExclusionConfig": { "excludeToolResults": true, "excludeImages": true, "excludeFiles": true, "excludeReasoning": true } } } ``` Document ID: `DOC-MA-conversations-api-updateContextManagementSettings`. [Section identities and revisions](/documentation-manifest.json). - Update context management settings: `DOC-MA-conversations-api-updateContextManagementSettings#overview` - Request: `DOC-MA-conversations-api-updateContextManagementSettings#request` - Responses: `DOC-MA-conversations-api-updateContextManagementSettings#responses` --- # Update default generation config URL: https://docs.travila.ai/api/conversations/update-default-generation-config **POST** `/api/v1/llm/update-default-generation-config` Updates the conversation’s default generation configuration for later messages. An active profile supplies the base configuration when selected; populated per-request overrides take precedence. Conversation memory settings fill settings omitted by an active profile. Use this in a guide: [Use remembered preferences in a returning user’s conversation](/managed-agents/memory-knowledge) · [Configure a support conversation that stays predictable](/managed-agents/conversations/configuration) · [Profile selection and prompt versions](/api/agent-profiles/selection-and-versioning) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for updating the conversation’s base generation configuration. **conversationKey** `string` **required** Identifier of the conversation thread. Minimum length: 1 **defaultGenerationConfig** `any` Base model and tool configuration for turns in this conversation. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#request). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#request). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#request). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#request). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#request). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#request). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinitionInput]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#request). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinitionInput]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRuleInput]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#request). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#request). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#request). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRuleInput]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#request). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#request). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfigInput]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#request). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#request). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#request). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#request). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) Minimum length: 2 Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$ **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#request). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" Maximum length: 50 **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" Enum: ``, `friendly`, `iso8601`, `date_only` Maximum length: 50 **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#request). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` **required** Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" Enum: `minimal`, `standard`, `verbose` **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#request). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#request). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. #### conversations-updateDefaultGenerationConfig-request Replace the default generation configuration on an existing conversation. ```json { "conversationKey": "example_123", "defaultGenerationConfig": { "languagePreference": "en-US", "maxOutputTokens": 512 } } ``` #### cookbook-managed-agents-conversations-configuration-01-request Guide request for Step 1: Set the model and answer length. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "support-chat-001", "defaultGenerationConfig": { "model": "anthropic/claude-sonnet-5", "temperature": 0.7, "maxOutputTokens": 2048, "topP": 0.9 } } ``` #### cookbook-managed-agents-memory-knowledge-index-json-02-request Guide request for Step 4: Include relevant memory in later replies. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "conv_abc", "defaultGenerationConfig": { "mem0": { "enabled": true, "searchTopK": 5, "searchThreshold": 0.3, "injectAsSystemContext": true, "injectMemoryTimestamps": true } } } ``` ## Responses ### 200 — Generation config updated Content type: `application/json` Result of updating the conversation’s base generation configuration. **defaultGenerationConfig** `any` Base model and tool configuration for turns in this conversation. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#response). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#response). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#response). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#response). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#response). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#response). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#response). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinition]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#response). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfig]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#response). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#response). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#response). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#response). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#response). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#response). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#response). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#response). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. #### conversations-updateDefaultGenerationConfig-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "defaultGenerationConfig": { "model": "example", "models": [ "example" ], "systemPrompt": "Example text", "modelRoutingFilter": { "minContextLength": "1", "minMaxCompletionTokens": "1", "requiredInputModalities": [ "example" ], "requiredOutputModalities": [ "example" ], "maxPromptCost": 1, "maxCompletionCost": 1, "excludeModerated": true, "requiredParameters": [ "example" ] }, "provider": { "order": [ "example" ], "allowFallbacks": true, "requireParameters": true, "dataCollection": "DATA_COLLECTION_MODE_ALLOW", "zdr": true, "only": [ "example" ], "ignore": [ "example" ], "quantizations": [ "example" ], "sort": "PROVIDER_SORT_PRICE", "enforceDistillableText": true }, "reasoning": { "effort": "EFFORT_HIGH", "maxTokens": 1, "exclude": true, "includeReasoningHistory": true }, "usage": { "include": true }, "transforms": [ "example" ], "tools": [ { "name": "example", "description": "example", "serverId": "example_123", "tags": [ "example" ], "documentationUrl": "https://example.com/resource" } ], "toolChoice": { "kind": "TOOL_CHOICE_KIND_AUTO", "specificToolName": "example" }, "clientTools": [ { "name": "example", "description": "example", "serverId": "example_123", "tags": [ "example" ], "documentationUrl": "https://example.com/resource" } ], "toolPolicy": { "requireApprovalToolNamePatterns": [ "example" ], "requireApprovalServerIds": [ "example_123" ], "autoApproveToolNamePatterns": [ "example" ], "autoApproveServerIds": [ "example_123" ], "approvalMode": "APPROVAL_MODE_MIXED", "clientToolMode": "CLIENT_TOOL_MODE_MIXED", "approvalTimeoutMs": 1, "failOnApprovalTimeoutToolNamePatterns": [ "example" ], "stableSortByCallIndexOnTie": true, "maxParallelToolCalls": 1, "maxToolCallsPerLoop": 1, "maxTotalToolCalls": 1, "retriableToolNamePatterns": [ "example" ], "maxRetries": 1, "retryableErrorSubstrings": [ "example" ], "nonRetryableErrorSubstrings": [ "example" ], "clientToolTimeoutMs": 1, "failureMode": "FAILURE_MODE_CONTINUE" }, "temperature": 1, "topP": 1, "maxOutputTokens": 1, "frequencyPenalty": 1, "presencePenalty": 1, "stopSequences": [ "example" ], "seed": "1", "responseFormat": { "jsonObject": true, "schemaName": "example", "validate": true, "maxValidationRetries": 1, "responseHealing": true }, "allowParallelToolCalls": true, "topK": 1, "repetitionPenalty": 1, "logitBias": {}, "topLogprobs": 1, "minP": 1, "topA": 1, "user": "example", "modalities": [ "MODALITY_TEXT" ], "plugins": [ { "id": "example_123" } ], "languagePreference": "en-US", "timeAware": { "includeCurrentTime": true, "includeMessageTimestamps": true, "includeFileTimestamps": true, "timezone": "example", "timestampFormat": "" }, "turnContext": { "enabled": true, "includeToolGuidance": true, "format": "minimal" }, "mem0": { "enabled": true, "searchTopK": 1, "searchThreshold": 1, "injectAsSystemContext": true, "searchQueryOverride": "Example text", "enableRerank": true, "addMemoriesAsync": true, "customExtractionPrompt": "Example text", "enableGraph": true, "agentIdOverride": "example_123", "exposeAsMcpTool": true, "includeAssistantMessages": true, "injectMemoryTimestamps": true }, "requestTimeoutSeconds": 1, "fileResolution": { "failureMode": "FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION" }, "clearTools": true } } ``` Document ID: `DOC-MA-conversations-api-updateDefaultGenerationConfig`. [Section identities and revisions](/documentation-manifest.json). - Update default generation config: `DOC-MA-conversations-api-updateDefaultGenerationConfig#overview` - Request: `DOC-MA-conversations-api-updateDefaultGenerationConfig#request` - Responses: `DOC-MA-conversations-api-updateDefaultGenerationConfig#responses` --- # Update a memory URL: https://docs.travila.ai/api/conversations/update-memory **POST** `/api/v1/llm/update-memory` Updates a memory by ID. Full project/user ownership checks are not currently enforced for these by-ID operations. They are not a supported access boundary for an untrusted end-user client. See [Memory](/managed-agents/memory-knowledge) for the current limits. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Use remembered preferences in a returning user’s conversation](/managed-agents/memory-knowledge) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for replacing the text of a memory record. **memoryId** `string` **required** Memory ID to update Minimum length: 1 **text** `string` **required** New memory text content Minimum length: 1 #### conversations-updateMemory-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "memoryId": "example_123", "text": "Example text" } ``` #### cookbook-managed-agents-memory-knowledge-index-04-request Guide request for Step 3: Correct an outdated preference. Replace example resource identifiers with your own authorized values. ```json { "memoryId": "mem_abc123", "text": "User is vegetarian, avoids gluten, and prefers organic produce" } ``` ## Responses ### 200 — Memory updated Content type: `application/json` Result of replacing the text of a memory record. This message declares no response fields. #### conversations-updateMemory-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json {} ``` Document ID: `DOC-MA-conversations-api-updateMemory`. [Section identities and revisions](/documentation-manifest.json). - Update a memory: `DOC-MA-conversations-api-updateMemory#overview` - Request: `DOC-MA-conversations-api-updateMemory#request` - Responses: `DOC-MA-conversations-api-updateMemory#responses` --- # Update prompt variables URL: https://docs.travila.ai/api/conversations/update-prompt-variables **POST** `/api/v1/llm/update-prompt-variables` Agent Profiles: merges prompt variables into the thread for late-binding. The variables are re-rendered into the active profile's prompt on the next turn. Returns the merged conversation settings. ### Prompt-variable update masks When you supply [`updateMask`](/api/conversations/update-prompt-variables#request-field-updatemask): * **Masked keys are authoritative.** A masked key whose value is `null` or absent **clears** that variable. * **Unmasked keys are untouched.** Variables not listed in the mask keep their current values, even if you include them in the payload. Without [`updateMask`](/api/conversations/update-prompt-variables#request-field-updatemask): * Supplied keys overwrite or add. * Null or empty values clear the variable. * Keys you omit are not touched. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Configure a support conversation that stays predictable](/managed-agents/conversations/configuration) · [Profile selection and prompt versions](/api/agent-profiles/selection-and-versioning) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for merging updated prompt variables into a conversation. The profile template is rendered with the updated variables on the next turn. **conversationKey** `string` **required** Identifier of the conversation thread. Minimum length: 1 **variables** `map[string, any]` Prompt-variable values to merge into the conversation’s settings. **updateMask** `string` Field paths selecting which prompt variables to update. #### conversations-updatePromptVariables-request Merge a destination variable into an existing conversation’s prompt variables. ```json { "conversationKey": "example_123", "variables": { "destination": "Paris" } } ``` #### cookbook-managed-agents-conversations-configuration-03-request Guide request for Variant: personalize the profile for this customer. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "support-chat-001", "variables": { "userName": "Jane", "planTier": "pro" } } ``` #### cookbook-managed-agents-conversations-configuration-json-03-request Guide request for Variant: personalize the profile for this customer. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "support-chat-001", "variables": { "planTier": "enterprise" }, "updateMask": "planTier" } ``` ## Responses ### 200 — Prompt variables merged Content type: `application/json` Result of merging prompt variables into conversation settings. **settings** `any` The merged conversation settings. All of: Variant 1: Conversation-level settings controlling behavior across sends [`maxLoops`](/api/models/schema-ph6avse89k#request-field-maxloops) caps the **total number of generations** in a run — not the number of tool round trips. Default is **2**, which is what one round trip costs: a first generation to emit the tool call, a second to synthesize its result. On the final generation the model is sent **no tools at all** (the request omits the [`tools`](/api/models/schema-1h82h7ri5p#request-field-tools) array), so it cannot emit a call there. `maxLoops: 1` therefore means a single tool-free reply — a valid way to ask for one, but not a way to get one tool round trip. Model reference: [ConversationSettings](/api/models/schema-ph6avse89k#response). **interruptPolicy** `any` Policy for an incoming message while another generation run is active. How a conversation handles a new send while another generation run is active.
| Value | No. | Form | Meaning | |---|---|---|---| | `INTERRUPT_POLICY_REJECT_NEW` | 0 | Canonical | See meaning below. | | `INTERRUPT_POLICY_CANCEL_ONGOING` | 1 | Canonical | See meaning below. | | `INTERRUPT_POLICY_QUEUE` | 2 | Canonical | See meaning below. | | `INTERRUPT_POLICY_IGNORE` | 3 | Canonical | Accept the send without persisting its message or starting a new run; let the ongoing run continue. | **`INTERRUPT_POLICY_REJECT_NEW`** Reject the new send with an error while a run is active; do not append its user message. Reject the new Send with an error if a run is active **`INTERRUPT_POLICY_CANCEL_ONGOING`** Cancel the ongoing run and start a new run for the incoming message. Cancel the ongoing run and immediately start a new one with the new message **`INTERRUPT_POLICY_QUEUE`** Queue the incoming message to run after the current run completes. Queue the new Send; it will run after the current run completes
Exactly one of: Variant 1: Type: `string` Enum: `INTERRUPT_POLICY_REJECT_NEW`, `INTERRUPT_POLICY_CANCEL_ONGOING`, `INTERRUPT_POLICY_QUEUE`, `INTERRUPT_POLICY_IGNORE` Variant 2: Type: `integer(int32)` **maxLoops** `string(int64)` Default limit on agentic generation loops for the conversation. Pattern: ^-?\d+$ **maxParallelTools** `string(int64)` Maximum number of tool executions allowed concurrently by this configuration. Pattern: ^-?\d+$ **mcpServers** `array[llm_v1_common_v1_MCPServerReference]` MCP servers available to this conversation; used for tool discovery/filtering MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#response). **serverId** `string` ID of pre-configured MCP server (e.g., "github", "filesystem"). **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **toolPolicy** `any` Optional per-conversation tool execution policy applied to AgentConfig All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **promptVariables** `map[string, any]` Typed values used when rendering profile prompt templates. Numbers, arrays, Boolean values and strings retain their respective JSON types. The values are shared by profiles in the conversation and can be refreshed with UpdatePromptVariables. Switching profiles renders the new template with the same values. #### conversations-updatePromptVariables-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "settings": { "interruptPolicy": "INTERRUPT_POLICY_REJECT_NEW", "maxLoops": 1, "maxParallelTools": 1, "mcpServers": [ { "serverId": "example_123", "enabled": true, "priority": 1, "allowlistToolPatterns": [ "example" ], "blocklistToolPatterns": [ "example" ] } ], "toolPolicy": { "requireApprovalToolNamePatterns": [ "example" ], "requireApprovalServerIds": [ "example_123" ], "autoApproveToolNamePatterns": [ "example" ], "autoApproveServerIds": [ "example_123" ], "approvalMode": "APPROVAL_MODE_MIXED", "clientToolMode": "CLIENT_TOOL_MODE_MIXED", "approvalTimeoutMs": 1, "failOnApprovalTimeoutToolNamePatterns": [ "example" ], "stableSortByCallIndexOnTie": true, "maxParallelToolCalls": 1, "maxToolCallsPerLoop": 1, "maxTotalToolCalls": 1, "retriableToolNamePatterns": [ "example" ], "maxRetries": 1, "retryableErrorSubstrings": [ "example" ], "nonRetryableErrorSubstrings": [ "example" ], "clientToolTimeoutMs": 1, "failureMode": "FAILURE_MODE_CONTINUE" }, "promptVariables": { "example": "value" } } } ``` Document ID: `DOC-MA-conversations-api-updatePromptVariables`. [Section identities and revisions](/documentation-manifest.json). - Update prompt variables: `DOC-MA-conversations-api-updatePromptVariables#overview` - Request: `DOC-MA-conversations-api-updatePromptVariables#request` - Responses: `DOC-MA-conversations-api-updatePromptVariables#responses` --- # Update conversation settings URL: https://docs.travila.ai/api/conversations/update-settings **POST** `/api/v1/llm/update-settings` Updates the conversation's behavior settings. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an assistant that researches the web](/integrations/tools-connections) · [MCP server selection](/api/tools/selection) · [Configure a support conversation that stays predictable](/managed-agents/conversations/configuration) · [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Input for updating the conversation’s settings. **conversationKey** `string` **required** Identifier of the conversation thread. Minimum length: 1 **settings** `any` Conversation settings to apply. All of: Variant 1: Conversation-level settings controlling behavior across sends [`maxLoops`](/api/models/schema-ph6avse89k#request-field-maxloops) caps the **total number of generations** in a run — not the number of tool round trips. Default is **2**, which is what one round trip costs: a first generation to emit the tool call, a second to synthesize its result. On the final generation the model is sent **no tools at all** (the request omits the [`tools`](/api/models/schema-1h82h7ri5p#request-field-tools) array), so it cannot emit a call there. `maxLoops: 1` therefore means a single tool-free reply — a valid way to ask for one, but not a way to get one tool round trip. Model reference: [ConversationSettings](/api/models/schema-ph6avse89k#request). **interruptPolicy** `any` Policy for an incoming message while another generation run is active. How a conversation handles a new send while another generation run is active.
| Value | No. | Form | Meaning | |---|---|---|---| | `INTERRUPT_POLICY_REJECT_NEW` | 0 | Canonical | See meaning below. | | `INTERRUPT_POLICY_CANCEL_ONGOING` | 1 | Canonical | See meaning below. | | `INTERRUPT_POLICY_QUEUE` | 2 | Canonical | See meaning below. | | `INTERRUPT_POLICY_IGNORE` | 3 | Canonical | Accept the send without persisting its message or starting a new run; let the ongoing run continue. | **`INTERRUPT_POLICY_REJECT_NEW`** Reject the new send with an error while a run is active; do not append its user message. Reject the new Send with an error if a run is active **`INTERRUPT_POLICY_CANCEL_ONGOING`** Cancel the ongoing run and start a new run for the incoming message. Cancel the ongoing run and immediately start a new one with the new message **`INTERRUPT_POLICY_QUEUE`** Queue the incoming message to run after the current run completes. Queue the new Send; it will run after the current run completes
Exactly one of: Variant 1: Type: `string` Enum: `INTERRUPT_POLICY_REJECT_NEW`, `INTERRUPT_POLICY_CANCEL_ONGOING`, `INTERRUPT_POLICY_QUEUE`, `INTERRUPT_POLICY_IGNORE` Variant 2: Type: `integer(int32)` **maxLoops** `string(int64)` Default limit on agentic generation loops for the conversation. Pattern: ^-?\d+$ **maxParallelTools** `string(int64)` Maximum number of tool executions allowed concurrently by this configuration. Pattern: ^-?\d+$ **mcpServers** `array[llm_v1_common_v1_MCPServerReferenceInput]` MCP servers available to this conversation; used for tool discovery/filtering MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#request). **serverId** `string` **required** ID of pre-configured MCP server (e.g., "github", "filesystem"). Minimum length: 1 **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **toolPolicy** `any` Optional per-conversation tool execution policy applied to AgentConfig All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRuleInput]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#request). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#request). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#request). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRuleInput]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#request). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **promptVariables** `map[string, any]` Typed values used when rendering profile prompt templates. Numbers, arrays, Boolean values and strings retain their respective JSON types. The values are shared by profiles in the conversation and can be refreshed with UpdatePromptVariables. Switching profiles renders the new template with the same values. #### conversations-updateSettings-request Replace settings on an existing conversation; include every setting you want to retain. ```json { "conversationKey": "example_123", "settings": { "maxLoops": 6, "maxParallelTools": 3 } } ``` #### cookbook-integrations-tools-connections-index-02-request Guide request for 2. Enable research for the conversation. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "thread_abc123", "settings": { "mcpServers": [ { "serverId": "built-in:tavily" } ] } } ``` #### cookbook-managed-agents-conversations-configuration-02-request Guide request for Step 2: Keep one unresolved turn at a time. Replace example resource identifiers with your own authorized values. ```json { "conversationKey": "support-chat-001", "settings": { "interruptPolicy": "INTERRUPT_POLICY_REJECT_NEW", "maxLoops": 4 } } ``` ## Responses ### 200 — Settings updated Content type: `application/json` Result of updating the conversation’s settings. **settings** `any` Updated conversation settings returned by the operation. All of: Variant 1: Conversation-level settings controlling behavior across sends [`maxLoops`](/api/models/schema-ph6avse89k#request-field-maxloops) caps the **total number of generations** in a run — not the number of tool round trips. Default is **2**, which is what one round trip costs: a first generation to emit the tool call, a second to synthesize its result. On the final generation the model is sent **no tools at all** (the request omits the [`tools`](/api/models/schema-1h82h7ri5p#request-field-tools) array), so it cannot emit a call there. `maxLoops: 1` therefore means a single tool-free reply — a valid way to ask for one, but not a way to get one tool round trip. Model reference: [ConversationSettings](/api/models/schema-ph6avse89k#response). **interruptPolicy** `any` Policy for an incoming message while another generation run is active. How a conversation handles a new send while another generation run is active.
| Value | No. | Form | Meaning | |---|---|---|---| | `INTERRUPT_POLICY_REJECT_NEW` | 0 | Canonical | See meaning below. | | `INTERRUPT_POLICY_CANCEL_ONGOING` | 1 | Canonical | See meaning below. | | `INTERRUPT_POLICY_QUEUE` | 2 | Canonical | See meaning below. | | `INTERRUPT_POLICY_IGNORE` | 3 | Canonical | Accept the send without persisting its message or starting a new run; let the ongoing run continue. | **`INTERRUPT_POLICY_REJECT_NEW`** Reject the new send with an error while a run is active; do not append its user message. Reject the new Send with an error if a run is active **`INTERRUPT_POLICY_CANCEL_ONGOING`** Cancel the ongoing run and start a new run for the incoming message. Cancel the ongoing run and immediately start a new one with the new message **`INTERRUPT_POLICY_QUEUE`** Queue the incoming message to run after the current run completes. Queue the new Send; it will run after the current run completes
Exactly one of: Variant 1: Type: `string` Enum: `INTERRUPT_POLICY_REJECT_NEW`, `INTERRUPT_POLICY_CANCEL_ONGOING`, `INTERRUPT_POLICY_QUEUE`, `INTERRUPT_POLICY_IGNORE` Variant 2: Type: `integer(int32)` **maxLoops** `string(int64)` Default limit on agentic generation loops for the conversation. Pattern: ^-?\d+$ **maxParallelTools** `string(int64)` Maximum number of tool executions allowed concurrently by this configuration. Pattern: ^-?\d+$ **mcpServers** `array[llm_v1_common_v1_MCPServerReference]` MCP servers available to this conversation; used for tool discovery/filtering MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Model reference: [MCPServerReference](/api/models/schema-1hik90rmo1#response). **serverId** `string` ID of pre-configured MCP server (e.g., "github", "filesystem"). **enabled** `boolean` Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. **priority** `string(int64)` Priority override for tool selection (higher = preferred). Pattern: ^-?\d+$ **allowlistToolPatterns** `array[string]` Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). Type: `string` **blocklistToolPatterns** `array[string]` Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). Type: `string` **serverOverrides** `map[string, string]` Override server settings for this usage. **deferTools** `boolean` Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. **toolPolicy** `any` Optional per-conversation tool execution policy applied to AgentConfig All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **promptVariables** `map[string, any]` Typed values used when rendering profile prompt templates. Numbers, arrays, Boolean values and strings retain their respective JSON types. The values are shared by profiles in the conversation and can be refreshed with UpdatePromptVariables. Switching profiles renders the new template with the same values. #### conversations-updateSettings-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "settings": { "interruptPolicy": "INTERRUPT_POLICY_REJECT_NEW", "maxLoops": 1, "maxParallelTools": 1, "mcpServers": [ { "serverId": "example_123", "enabled": true, "priority": 1, "allowlistToolPatterns": [ "example" ], "blocklistToolPatterns": [ "example" ] } ], "toolPolicy": { "requireApprovalToolNamePatterns": [ "example" ], "requireApprovalServerIds": [ "example_123" ], "autoApproveToolNamePatterns": [ "example" ], "autoApproveServerIds": [ "example_123" ], "approvalMode": "APPROVAL_MODE_MIXED", "clientToolMode": "CLIENT_TOOL_MODE_MIXED", "approvalTimeoutMs": 1, "failOnApprovalTimeoutToolNamePatterns": [ "example" ], "stableSortByCallIndexOnTie": true, "maxParallelToolCalls": 1, "maxToolCallsPerLoop": 1, "maxTotalToolCalls": 1, "retriableToolNamePatterns": [ "example" ], "maxRetries": 1, "retryableErrorSubstrings": [ "example" ], "nonRetryableErrorSubstrings": [ "example" ], "clientToolTimeoutMs": 1, "failureMode": "FAILURE_MODE_CONTINUE" }, "promptVariables": { "example": "value" } } } ``` Document ID: `DOC-MA-conversations-api-updateSettings`. [Section identities and revisions](/documentation-manifest.json). - Update conversation settings: `DOC-MA-conversations-api-updateSettings#overview` - Request: `DOC-MA-conversations-api-updateSettings#request` - Responses: `DOC-MA-conversations-api-updateSettings#responses` --- # End User APIs URL: https://docs.travila.ai/api/end-users Version: `aju17f20mq` Use the reference below for request and response fields and operation-specific requirements. # Overview \{#overview} Manage the effective user’s location, locale, default generation preferences and metadata. There is no arbitrary target-user field in these request bodies. Authorized backend calls can act on behalf of a user. ## Authentication \{#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](https://docs.travila.ai/core-platform/identity-access/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. **Related guide:** [Manage end-user profiles](https://docs.travila.ai/core-platform/identity-access/end-users) ### JSON conventions \{#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](https://docs.travila.ai/api). ## Profile \{#reference-group-1} Read the caller's end-user profile. * [Get the caller's end-user profile](/api/end-users/get-end-user) ## Preferences \{#reference-group-2} Update the caller's location, locale, default generation config, and metadata. * [Update the caller's location](/api/end-users/update-location) * [Update the caller's locale override](/api/end-users/update-locale) * [Update the caller's default generation config](/api/end-users/update-default-generation-config) * [Update the caller's metadata](/api/end-users/update-metadata) ## Server 1 \{#reference-server-1} Travila API [https://api.travila.ai](https://api.travila.ai) ## X-API-Key \{#authentication-apiKeyAuth} 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 \{#authentication-onBehalfOf} 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 \{#authentication-bearerAuth} 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

### apiKeyAuth Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-API-Key` ### onBehalfOf Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-On-Behalf-Of` ### bearerAuth Security scheme type: `http` HTTP authorization scheme: `bearer` ## Operations - [Update the caller's location](/api/end-users/update-location) — `POST /api/v1/enduser/update-location` - [Update the caller's locale override](/api/end-users/update-locale) — `POST /api/v1/enduser/update-locale` - [Update the caller's default generation config](/api/end-users/update-default-generation-config) — `POST /api/v1/enduser/update-generation-config` - [Update the caller's metadata](/api/end-users/update-metadata) — `POST /api/v1/enduser/update-metadata` - [Get the caller's end-user profile](/api/end-users/get-end-user) — `POST /api/v1/enduser/get` Document ID: `DOC-API-end-users-overview`. [Section identities and revisions](/documentation-manifest.json). - Overview: `DOC-API-end-users-overview#overview` - Authentication: `DOC-API-end-users-overview#authentication` - JSON conventions: `DOC-API-end-users-overview#json-conventions` - Profile: `DOC-API-end-users-overview#reference-group-1` - Preferences: `DOC-API-end-users-overview#reference-group-2` - Server 1: `DOC-API-end-users-overview#reference-server-1` - X-API-Key: `DOC-API-end-users-overview#authentication-apiKeyAuth` - X-On-Behalf-Of: `DOC-API-end-users-overview#authentication-onBehalfOf` - Authorization: Bearer: `DOC-API-end-users-overview#authentication-bearerAuth` --- # Get the caller's end-user profile URL: https://docs.travila.ai/api/end-users/get-end-user **POST** `/api/v1/enduser/get` Returns the caller's full end-user record — identity claims sourced from the identity provider, profile settings the user has set, and lifecycle timestamps. **A user with no profile is not a 404** If no row exists yet, the call still succeeds and returns an empty [`endUser`](/api/end-users/get-end-user#response-field-enduser) object. Treat "no profile yet" and "profile with no overrides" identically — do not branch on the difference when choosing settings. Treat the missing profile as an absent record; default-valued fields alone do not prove that an account exists or that deletion completed. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an agent preferences screen](/core-platform/identity-access/end-users) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for retrieving an end-user identity and profile record. This schema declares no request fields. #### end-users-getEndUser-request Read the end user selected by authentication; no user identifier is accepted in this body. ```json {} ``` ## Responses ### 200 — Profile returned (possibly empty if no row exists yet) Content type: `application/json` Result of retrieving an end-user identity and profile record. If no record exists, the returned end-user state is empty. **endUser** `any` End-user identity and profile returned by the lookup. An empty message is returned when no matching end user exists. All of: Variant 1: Captured identity claims and editable profile values for a tenant's end user. Identity claims are copied from the verified token and are read-only through the profile update operations. Location, locale overrides, generation preferences and application metadata are set through their corresponding profile update operations. Model reference: [EndUserState](/api/models/schema-1l1et4gp2i#response). **subject** `string` Subject claim identifying the end user within the identity provider. **tenantId** `string` Identifier of the tenant that owns or scopes this record. **issuer** `string` OIDC issuer identifying the identity provider. **projectId** `string` Identifier of the project within the tenant that scopes this record. **email** `string` Email address received from the identity provider. **emailVerified** `boolean` Whether the identity provider marked the email address as verified. **name** `string` Full name received from the identity provider. **givenName** `string` Given-name claim received from the identity provider. **familyName** `string` Family-name claim received from the identity provider. **preferredUsername** `string` Preferred username claim received from the identity provider. **picture** `string` Profile picture URL received from the identity provider. **phoneNumber** `string` Telephone number received from the identity provider. **phoneNumberVerified** `boolean` Whether the identity provider marked the telephone number as verified. **signInProvider** `string` Sign-in provider recorded with the captured identity. **authMethod** `string` Authentication method recorded with the captured identity. **locale** `string` Locale preference associated with the user or subscriber. IdP-sourced default (not the override). **zoneinfo** `string` Time zone claim received from the identity provider. IdP-sourced default. **customClaims** `map[string, string]` Additional identity claims represented as string key-value pairs. The current end-user store does not populate this field. **location** `any` Coordinates and derived location metadata selected by the end user. All of: Variant 1: End-user coordinates and associated location metadata. Model reference: [Location](/api/models/schema-1kvbjenggb#response). **latitude** `any` Latitude of the location in decimal degrees. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **longitude** `any` Longitude of the location in decimal degrees. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **city** `string` City associated with the location; currently left empty because reverse geocoding is not implemented. **timezone** `string` IANA time zone associated with the location, derived from its coordinates server-side. **updatedAt** `string(date-time)` Time this record was most recently updated. **localeOverride** `string` Locale explicitly selected by the end user. When set, takes precedence over the identity provider's locale; when empty, the identity-provider locale is used. **defaultGenerationConfig** `any` Default model generation settings associated with the end-user profile. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#response). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#response). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#response). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#response). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#response). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#response). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#response). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinition]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#response). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinition]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#response). **name** `string` Name used to select and invoke the tool. **description** `string` Explanation of the tool’s purpose supplied to the model and callers. **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRule]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#response). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#response). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRule]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#response). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#response). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfig]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#response). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#response). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#response). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#response). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#response). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#response). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#response). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#response). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. **metadata** `map[string, string]` Application-defined key-value metadata associated with the end user. **firstSeenAt** `string(date-time)` Time the end-user identity was first captured. **lastSeenAt** `string(date-time)` Time the end user's identity was most recently observed. **updatedAt** `string(date-time)` Time this record was most recently updated. **createdAt** `string(date-time)` Time this record was created. #### end-users-getEndUser-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "endUser": { "subject": "example", "tenantId": "example_123", "issuer": "example", "projectId": "example_123", "email": "user@example.com", "emailVerified": true, "name": "example", "givenName": "example", "familyName": "example", "preferredUsername": "example", "picture": "example", "phoneNumber": "example", "phoneNumberVerified": true, "signInProvider": "example_123", "authMethod": "example", "locale": "en-US", "zoneinfo": "example", "customClaims": {}, "location": { "latitude": 1, "longitude": 1, "city": "example", "timezone": "example" }, "localeOverride": "en-US", "defaultGenerationConfig": { "model": "example", "models": [ "example" ], "systemPrompt": "Example text", "transforms": [ "example" ], "temperature": 1, "topP": 1, "maxOutputTokens": 1, "frequencyPenalty": 1, "presencePenalty": 1, "stopSequences": [ "example" ], "seed": "1", "allowParallelToolCalls": true, "topK": 1, "repetitionPenalty": 1, "topLogprobs": 1, "minP": 1, "topA": 1, "user": "example", "modalities": [ "MODALITY_TEXT" ], "languagePreference": "en-US", "requestTimeoutSeconds": 1, "clearTools": true }, "metadata": {}, "firstSeenAt": "2026-09-16T12:00:00Z", "lastSeenAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z", "createdAt": "2026-09-16T12:00:00Z" } } ``` #### cookbook-core-platform-identity-access-end-users-json-01-response Illustrative response for 1. Load the saved settings and account defaults. Replace example resource identifiers with your own authorized values. ```json { "endUser": { "subject": "user_123", "tenantId": "tenant_abc", "email": "jane@example.com", "emailVerified": true, "name": "Jane Doe", "givenName": "Jane", "picture": "https://…", "signInProvider": "google.com", "locale": "en-US", "zoneinfo": "Europe/London", "location": { "latitude": 51.5072, "longitude": -0.1276, "timezone": "Europe/London", "updatedAt": "2026-08-14T09:31:02Z" }, "localeOverride": "es-MX", "defaultGenerationConfig": { "model": "google/gemini-3.6-flash", "temperature": 0.4, "languagePreference": "es" }, "metadata": { "preferredView": "compact" }, "firstSeenAt": "2026-01-14T09:12:00Z", "lastSeenAt": "2026-08-14T09:30:58Z", "updatedAt": "2026-08-14T09:31:02Z", "createdAt": "2026-01-14T09:12:00Z" } } ``` Document ID: `DOC-CP-identity-access-api-getEndUser`. [Section identities and revisions](/documentation-manifest.json). - Get the caller's end-user profile: `DOC-CP-identity-access-api-getEndUser#overview` - Request: `DOC-CP-identity-access-api-getEndUser#request` - Responses: `DOC-CP-identity-access-api-getEndUser#responses` --- # Update the caller's default generation config URL: https://docs.travila.ai/api/end-users/update-default-generation-config **POST** `/api/v1/enduser/update-generation-config` Stores the caller's generation preferences. The generation path fills fields left unset by the selected per-send, profile or conversation configuration; already set values remain unchanged. Explicitly present sampling values, including zero, preserve their presence. Model/provider support determines which accepted controls affect a response. Only user-settable controls are accepted. A recognized operational setting or a model outside the platform allowlist fails the whole request; settings are not silently removed to make a config acceptable. Read the saved profile after an update rather than assuming every submitted setting took effect. Use this in a guide: [Build an agent preferences screen](/core-platform/identity-access/end-users) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for updating default model generation settings. **config** `any` **required** Default generation settings restricted to these user-settable fields: model, models, temperature, top\_p, max\_output\_tokens, frequency\_penalty, presence\_penalty, stop\_sequences, seed and language\_preference. Recognized fields outside this list, including operational settings for prompts, tools, MCP and timeouts, reject the whole request. New GenerationConfig fields are rejected unless added to this allowlist. Each model must also be permitted by the platform model allowlist. Unknown JSON names may be discarded before these checks; they are not supported configuration settings. All of: Variant 1: Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Model reference: [GenerationConfig](/api/models/schema-1h82h7ri5p#request). **model** `string` Primary model identifier requested for generation. **models** `array[string]` Candidate models for routing. Type: `string` **systemPrompt** `string` Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. **modelRoutingFilter** `any` Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. All of: Variant 1: ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Model reference: [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#request). **minContextLength** `string(int64)` Minimum context window (tokens). Models below this are excluded. Pattern: ^-?\d+$ **minMaxCompletionTokens** `string(int64)` Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: ^-?\d+$ **requiredInputModalities** `array[string]` Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). Type: `string` **requiredOutputModalities** `array[string]` Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). Type: `string` **maxPromptCost** `any` Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxCompletionCost** `any` Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **excludeModerated** `boolean` Exclude models with content moderation enabled. **requiredParameters** `array[string]` Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. Type: `string` **provider** `any` Provider/multi-provider routing preferences All of: Variant 1: Routing preferences restricting and ordering the model providers eligible for a request. Model reference: [ProviderPreferences](/api/models/schema-1gg690bhqh#request). **order** `array[string]` Preferred ordering of model providers for routing. Type: `string` **allowFallbacks** `boolean` The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. **requireParameters** `boolean` Whether routing requires providers to support the requested parameters. **dataCollection** `any` Provider data-collection preference used when routing the request. Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
Exactly one of: Variant 1: Type: `string` Enum: `DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY` Variant 2: Type: `integer(int32)` **zdr** `boolean` Whether routing requests providers offering zero data retention. **only** `array[string]` Provider identifiers allowed by the routing preference. Type: `string` **ignore** `array[string]` Provider identifiers excluded by the routing preference. Type: `string` **quantizations** `array[string]` Model quantization formats allowed by the routing preference. generic string for portability Type: `string` **sort** `any` Metric used to order eligible model providers. Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY` Variant 2: Type: `integer(int32)` **maxPrice** `any` Upper price bounds used when selecting a model provider. All of: Variant 1: Routing / provider preferences (generic superset) Model reference: [ProviderMaxPrice](/api/models/schema-1geaq4stvt#request). **prompt** `any` $/1M prompt tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **completion** `any` $/1M completion tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **request** `any` Maximum provider cost allowed per request, in US dollars. $/request Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **image** `any` Maximum provider cost allowed per image, in US dollars. $/image Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **audio** `any` $/1M audio tokens. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **enforceDistillableText** `boolean` Embeddings: enforce distillable text. **preferredMinThroughput** `any` Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **preferredMaxLatency** `any` Deprioritize providers above this latency (ms). All of: Variant 1: Percentile thresholds for provider performance metrics Model reference: [PercentileThreshold](/api/models/schema-1gcuue0out#request). **p50** `any` Threshold applied to the provider metric’s 50th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` Threshold applied to the provider metric’s 90th percentile. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **reasoning** `any` Reasoning effort and output options passed to the model provider. All of: Variant 1: Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Model reference: [ReasoningOptions](/api/models/schema-1gi26i7r89#request). **effort** `any` Requested model reasoning effort. Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
Exactly one of: Variant 1: Type: `string` Enum: `EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE` Variant 2: Type: `integer(int32)` **maxTokens** `string(int64)` Maximum reasoning-token count requested from the model provider. Pattern: ^-?\d+$ **exclude** `boolean` Whether the provider should omit reasoning content from its response. **includeReasoningHistory** `boolean` When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. **usage** `any` Token and cost accounting associated with the operation. All of: Variant 1: Usage accounting preferences Model reference: [UsageOptions](/api/models/schema-1h615aquj0#request). **include** `boolean` Whether usage accounting should be included in the provider response. **transforms** `array[string]` Provider transformations requested for the generation input. Type: `string` **tools** `array[llm_v1_common_v1_ToolDefinitionInput]` Tool definitions exposed to the model for server-side execution. A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolChoice** `any` Policy controlling whether and which tool the model may call. All of: Variant 1: Policy selecting automatic tool choice, no tool use, or a named tool. Model reference: [ToolChoice](/api/models/schema-1gmq0e4ilg#request). **kind** `any` Discriminator selecting the representation or policy used by this message. How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
Exactly one of: Variant 1: Type: `string` Enum: `TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC` Variant 2: Type: `integer(int32)` **specificToolName** `string` Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. **clientTools** `array[llm_v1_common_v1_ToolDefinitionInput]` Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Model reference: [ToolDefinition](/api/models/schema-1gomaj79cc#request). **name** `string` **required** Name used to select and invoke the tool. Minimum length: 1 **description** `string` **required** Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1 **parametersJsonSchema** `map[string, any]` JSON Schema object. **metadata** `map[string, string]` Additional tool metadata (version, category, etc.). **serverId** `string` **required** Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1 **tags** `array[string]` Tool categorization tags. Type: `string` **documentationUrl** `string` Link to detailed documentation. **outputJsonSchema** `map[string, any]` Optional output schema (JSON Schema serialized as string) describing structured results **toolPolicy** `any` Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) All of: Variant 1: Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Model reference: [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request). **requireApprovalToolNamePatterns** `array[string]` Tool-name patterns selecting calls that require an approval decision. Type: `string` **requireApprovalServerIds** `array[string]` MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. Type: `string` **autoApproveToolNamePatterns** `array[string]` Tool-name patterns whose matching calls may be approved automatically. Type: `string` **autoApproveServerIds** `array[string]` MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. Type: `string` **approvalMode** `any` How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Exactly one of: Variant 1: Type: `string` Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **clientToolMode** `any` Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
Exactly one of: Variant 1: Type: `string` Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL` Variant 2: Type: `integer(int32)` **approvalTimeoutMs** `string(int64)` Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$ **failOnApprovalTimeoutToolNamePatterns** `array[string]` Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. Type: `string` **orderRules** `array[llm_v1_common_v1_ToolExecutionOrderRuleInput]` Stored requested ordering rules; not applied by the current generation workflow. Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Model reference: [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#request). **toolNamePatterns** `array[string]` Requested tool-name patterns; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Optional requested MCP server filter; not evaluated by the current generation workflow. Type: `string` **weight** `string(int64)` Requested ordering weight; not applied by the current generation workflow. lower executes first Pattern: ^-?\d+$ **stableSortByCallIndexOnTie** `boolean` Stored requested ordering tie-breaker; not applied by the current generation workflow. **maxParallelToolCalls** `string(int64)` Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$ **maxToolCallsPerLoop** `string(int64)` Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap Pattern: ^-?\d+$ **maxTotalToolCalls** `string(int64)` Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$ **retriableToolNamePatterns** `array[string]` Stored requested retry selection; does not enable retries in the current workflow. Type: `string` **maxRetries** `string(int64)` Stored requested retry count; does not enable retries in the current workflow. per tool-call Pattern: ^-?\d+$ **retryBackoff** `any` Stored requested retry delays; not applied by the current generation workflow. All of: Variant 1: Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Model reference: [Backoff](/api/models/schema-1gqlghlp0v#request). **initialMs** `string(int64)` Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 Pattern: ^-?\d+$ **multiplier** `any` Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxMs** `string(int64)` Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 Pattern: ^-?\d+$ **retryableErrorSubstrings** `array[string]` Stored requested retryable-error selection; not evaluated by the current workflow. Type: `string` **nonRetryableErrorSubstrings** `array[string]` Stored requested retry exclusions; not evaluated by the current generation workflow. Type: `string` **timeouts** `any` Overall execution time budget for the generation run. All of: Variant 1: Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Model reference: [TimeoutPolicy](/api/models/schema-1gu5od417l#request). **overallMs** `string(int64)` Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: ^-?\d+$ **clientToolTimeoutMs** `string(int64)` Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$ **failureMode** `any` Stored requested failure action; not enforced by the current generation workflow. default if no rule matches Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **stopOnFailureRules** `array[llm_v1_common_v1_StopOnFailureRuleInput]` Stored requested stop rules; not evaluated by the current generation workflow. Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Model reference: [StopOnFailureRule](/api/models/schema-1gstrgb39r#request). **toolNamePatterns** `array[string]` Requested tool-name selection; not evaluated by the current generation workflow. Type: `string` **serverIds** `array[string]` Requested MCP server selection; not evaluated by the current generation workflow. Type: `string` **onFailure** `any` Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
Exactly one of: Variant 1: Type: `string` Enum: `FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN` Variant 2: Type: `integer(int32)` **includeTimeouts** `boolean` Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **errorSubstrings** `array[string]` Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches Type: `string` **priority** `string(int64)` Requested rule priority; not evaluated by the current generation workflow. lower evaluated first Pattern: ^-?\d+$ **temperature** `any` Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topP** `any` Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxOutputTokens** `string(int64)` Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: ^-?\d+$ **frequencyPenalty** `any` Sampling penalty applied to tokens according to their prior frequency. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **presencePenalty** `any` Sampling penalty applied to tokens already present in generated content. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stopSequences** `array[string]` Token sequences at which the model should stop generation. Type: `string` **seed** `string(int64)` Deterministic control where supported. Pattern: ^-?\d+$ **responseFormat** `any` Structured-output format and schema requested for the model response. All of: Variant 1: Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Model reference: [ResponseFormat](/api/models/schema-1g69v4vltg#request). **jsonObject** `boolean` Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **jsonSchema** `map[string, any]` JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) **schemaName** `string` Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. **validate** `boolean` Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). **maxValidationRetries** `string(int64)` Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: ^-?\d+$ **responseHealing** `boolean` Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. **allowParallelToolCalls** `boolean` Allow the model to issue multiple tool calls in parallel where supported **topK** `string(int64)` Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: ^-?\d+$ **repetitionPenalty** `any` Provider sampling penalty used to discourage repeated output. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **logitBias** `map[string, any]` Per-token adjustments applied to the provider token-selection logits. Map values: Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topLogprobs** `string(int64)` Number of top token log probabilities requested from the provider. Pattern: ^-?\d+$ **minP** `any` Minimum relative token probability used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **topA** `any` Adaptive probability cutoff used by supported sampling providers. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **user** `string` User identifier forwarded for provider-side request attribution. **modalities** `array[any]` Output modalities (e.g., \[TEXT, IMAGE]) Output media requested from a model that supports that modality. Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
Exactly one of: Variant 1: Type: `string` Enum: `MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO` Variant 2: Type: `integer(int32)` **plugins** `array[llm_v1_common_v1_GenerationConfig_PluginConfigInput]` Provider plugins requested for pre-processing or post-processing. Provider plugin identifier and its parser, search, or additional configuration. Model reference: [PluginConfig](/api/models/schema-1g5jvg1icc#request). **id** `string` Provider plugin identifier, such as file-parser. e.g., "file-parser" **pdf** `any` PDF annotation or parser configuration selected by the enclosing message. All of: Variant 1: Plugins for pre/post-processing (generic representation) Model reference: [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#request). **engine** `string` PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" **web** `any` Web-search configuration for the selected generation plugin. All of: Variant 1: Provider web-search configuration used to augment a generation request. Model reference: [PluginWebConfig](/api/models/schema-1g3q0m5uun#request). **engine** `string` Search engine selected for the provider’s web-search plugin. e.g., native/exa **maxResults** `string(int64)` Maximum web-search result count requested by the plugin. Pattern: ^-?\d+$ **searchPrompt** `string` Instructions supplied to the web-search plugin. **webSearchOptions** `any` Options controlling the amount of web-search context requested. All of: Variant 1: Amount of web-search context requested for generation. Model reference: [WebSearchOptions](/api/models/schema-1g1r4lmi7m#request). **searchContextSize** `string` Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" **params** `map[string, string]` Additional provider-specific plugin parameters. **languagePreference** `string` Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) Minimum length: 2 Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$ **timeAware** `any` Time-aware generation options (current time, message timestamps, file timestamps) All of: Variant 1: Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Model reference: [TimeAwareConfig](/api/models/schema-1gkqaobt3t#request). **includeCurrentTime** `boolean` When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. **includeMessageTimestamps** `boolean` Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. **includeFileTimestamps** `boolean` Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \]" annotations. Default: false **timezone** `string` Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" Maximum length: 50 **timestampFormat** `string` Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" Enum: ``, `friendly`, `iso8601`, `date_only` Maximum length: 50 **turnContext** `any` Turn context configuration for turn-aware generation All of: Variant 1: Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Model reference: [TurnContextConfig](/api/models/schema-1h5dj58uph#request). **enabled** `boolean` Enable turn context injection into system prompt Default: true **includeToolGuidance** `boolean` Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) **format** `string` **required** Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" Enum: `minimal`, `standard`, `verbose` **mem0** `any` Configuration for semantic memory search, context injection and extraction during generation. All of: Variant 1: Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Model reference: [MemoryConfig](/api/models/schema-1g8iadjcu1#request). **enabled** `boolean` Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. **searchTopK** `string(int64)` Number of memories to retrieve during search. Higher values provide more context but increase token usage. The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results. Range: 1–50 when memory is enabled. Pattern: ^-?\d+$ **searchThreshold** `any` Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **injectAsSystemContext** `boolean` When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. **searchQueryOverride** `string` Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. **enableRerank** `boolean` Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. **addMemoriesAsync** `boolean` This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. **customExtractionPrompt** `string` Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. **enableGraph** `boolean` Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. **agentIdOverride** `string` Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. **exposeAsMcpTool** `boolean` This flag is currently ignored. It does not expose memory search as a model tool. Default: false. **includeAssistantMessages** `boolean` Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false **injectMemoryTimestamps** `boolean` Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \)" annotation and optionally "(updated: \)" if the memory was modified after creation. Default: true **requestTimeoutSeconds** `string(int64)` Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: ^-?\d+$ **fileResolution** `any` Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. All of: Variant 1: Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Model reference: [FileResolutionConfig](/api/models/schema-1ftcunpmha#request). **failureMode** `any` Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
Exactly one of: Variant 1: Type: `string` Enum: `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` Variant 2: Type: `integer(int32)` **clearTools** `boolean` Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. **clearClientTools** `boolean` Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. #### end-users-updateDefaultGenerationConfig-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "config": { "languagePreference": "en-US" } } ``` #### cookbook-core-platform-identity-access-end-users-03-request Guide request for 3. Offer supported model and response preferences. Replace example resource identifiers with your own authorized values. ```json { "config": { "model": "google/gemini-3.6-flash", "temperature": 0.4, "maxOutputTokens": 2048, "languagePreference": "es" } } ``` ## Responses ### 200 — Default generation config updated Content type: `application/json` Result of updating default model generation settings. This schema declares no result fields. #### end-users-updateDefaultGenerationConfig-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json {} ``` Document ID: `DOC-CP-identity-access-api-updateDefaultGenerationConfig`. [Section identities and revisions](/documentation-manifest.json). - Update the caller's default generation config: `DOC-CP-identity-access-api-updateDefaultGenerationConfig#overview` - Request: `DOC-CP-identity-access-api-updateDefaultGenerationConfig#request` - Responses: `DOC-CP-identity-access-api-updateDefaultGenerationConfig#responses` --- # Update the caller's locale override URL: https://docs.travila.ai/api/end-users/update-locale **POST** `/api/v1/enduser/update-locale` Sets a BCP-47 locale override for the caller, e.g. `es-MX`. This overrides the locale supplied by the identity provider. Send an **empty string** to clear the override and fall back to the identity-provider locale. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an agent preferences screen](/core-platform/identity-access/end-users) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for updating the end user's locale preference. ### Input constraints ### locale The locale value may be empty text. Otherwise it must start with two or three ASCII letters, followed by zero or more segments each consisting of a hyphen and two through eight ASCII letters or digits. No other characters or segments are accepted. **locale** `string` BCP-47 locale override, such as "es-MX". Empty string clears the override. Pattern: ^$|^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$ #### end-users-updateLocale-request Set the authenticated end user’s locale override. ```json { "locale": "en-US" } ``` #### cookbook-core-platform-identity-access-end-users-02-request Guide request for 2. Save the user’s preferred language. Replace example resource identifiers with your own authorized values. ```json { "locale": "es-MX" } ``` #### cookbook-core-platform-identity-access-end-users-json-02-request Guide request for 2. Save the user’s preferred language. Replace example resource identifiers with your own authorized values. ```json { "locale": "" } ``` ## Responses ### 200 — Locale override updated Content type: `application/json` Result of updating the end user's locale preference. This schema declares no result fields. #### end-users-updateLocale-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json {} ``` Document ID: `DOC-CP-identity-access-api-updateLocale`. [Section identities and revisions](/documentation-manifest.json). - Update the caller's locale override: `DOC-CP-identity-access-api-updateLocale#overview` - Request: `DOC-CP-identity-access-api-updateLocale#request` - Responses: `DOC-CP-identity-access-api-updateLocale#responses` --- # Update the caller's location URL: https://docs.travila.ai/api/end-users/update-location **POST** `/api/v1/enduser/update-location` Sets the caller's coordinates. The IANA timezone is **derived server-side** from the coordinates and returned on the response — do not send a timezone. Coordinates (0, 0) are a real location, not a deletion command. This operation does not offer a location-clear control. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an agent preferences screen](/core-platform/identity-access/end-users) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Gateway requests: same payloads as the internal service, minus EndUserRef. Inputs for updating the end user's geographic coordinates. **latitude** `number(double)` Latitude of the location in decimal degrees. Minimum: -90 Maximum: 90 **longitude** `number(double)` Longitude of the location in decimal degrees. Minimum: -180 Maximum: 180 #### end-users-updateLocation-request Set the authenticated end user’s location to the supplied coordinates. ```json { "latitude": 37.7749, "longitude": -122.4194 } ``` #### cookbook-core-platform-identity-access-end-users-05-request Guide request for Variant: use location for local-time context. Replace example resource identifiers with your own authorized values. ```json { "latitude": 51.5072, "longitude": -0.1276 } ``` ## Responses ### 200 — Location updated; response carries the derived timezone Content type: `application/json` Result of updating the end user's geographic coordinates. **location** `any` Coordinates and derived location metadata stored for the end user. Includes derived IANA timezone. All of: Variant 1: End-user coordinates and associated location metadata. Model reference: [Location](/api/models/schema-1kvbjenggb#response). **latitude** `any` Latitude of the location in decimal degrees. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **longitude** `any` Longitude of the location in decimal degrees. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **city** `string` City associated with the location; currently left empty because reverse geocoding is not implemented. **timezone** `string` IANA time zone associated with the location, derived from its coordinates server-side. **updatedAt** `string(date-time)` Time this record was most recently updated. #### end-users-updateLocation-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "location": { "latitude": 1, "longitude": 1, "city": "example", "timezone": "example", "updatedAt": "2026-09-16T12:00:00Z" } } ``` #### cookbook-core-platform-identity-access-end-users-json-06-response Illustrative response for Variant: use location for local-time context. Replace example resource identifiers with your own authorized values. ```json { "location": { "latitude": 51.5072, "longitude": -0.1276, "timezone": "Europe/London", "updatedAt": "2026-08-14T09:31:02Z" } } ``` Document ID: `DOC-CP-identity-access-api-updateLocation`. [Section identities and revisions](/documentation-manifest.json). - Update the caller's location: `DOC-CP-identity-access-api-updateLocation#overview` - Request: `DOC-CP-identity-access-api-updateLocation#request` - Responses: `DOC-CP-identity-access-api-updateLocation#responses` --- # Update the caller's metadata URL: https://docs.travila.ai/api/end-users/update-metadata **POST** `/api/v1/enduser/update-metadata` Merges the supplied key/value pairs into the caller's metadata map. This is a **merge, not a replace**: keys you omit are left untouched. To delete a key, send it with an empty-string value. The request examples below show setting metadata values and deleting `dismissedWelcome` with an empty string. If you send `{"preferredView":"compact","dismissedWelcome":""}` as the metadata map, `preferredView` is overwritten, `dismissedWelcome` is deleted, and an omitted key such as `referralCode` is left untouched. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an agent preferences screen](/core-platform/identity-access/end-users) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for updating the end user's profile metadata. **metadata** `map[string, string]` Application-defined key-value metadata associated with the end user. #### end-users-updateMetadata-request Merge a metadata key for the authenticated end user. ```json { "metadata": { "preferred_destination": "Paris" } } ``` #### cookbook-core-platform-identity-access-end-users-04-request Guide request for Variant: remember a display preference. Replace example resource identifiers with your own authorized values. ```json { "metadata": { "preferredView": "compact", "dismissedWelcome": "true" } } ``` #### cookbook-core-platform-identity-access-end-users-json-05-request Guide request for Variant: remember a display preference. Replace example resource identifiers with your own authorized values. ```json { "metadata": { "dismissedWelcome": "" } } ``` ## Responses ### 200 — Metadata merged Content type: `application/json` Result of updating the end user's profile metadata. This schema declares no result fields. #### end-users-updateMetadata-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json {} ``` Document ID: `DOC-CP-identity-access-api-updateMetadata`. [Section identities and revisions](/documentation-manifest.json). - Update the caller's metadata: `DOC-CP-identity-access-api-updateMetadata#overview` - Request: `DOC-CP-identity-access-api-updateMetadata#request` - Responses: `DOC-CP-identity-access-api-updateMetadata#responses` --- # Add a dataset item URL: https://docs.travila.ai/api/evals/add-dataset-item **POST** `/api/v1/evals/add-dataset-item` Adds a dataset item. The ID is derived from the dataset and `sourceUserMessageId` when supplied, otherwise from the source trace ID. Repeating that identity addresses the same item; a source identity must be meaningful and stable. Provide the intended input and expected output explicitly: the current API does not fetch a gold answer from a source trace. ### Dataset input capture and identity | Input or identity | Contract | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | Dataset item address | Derived from the dataset and source turn. Adding the same turn to different datasets produces different items. | | [`inputJson`](/api/evals/add-dataset-item#request-field-inputjson) and expected output | Only supplied content is recorded; an empty input does not trigger automatic context capture. | | Retry or replacement | A stable item ID does not establish ordering between a stale retry and a newer curated revision. Reconcile the stored item before retrying. | Capture and curate source material explicitly, including redaction, omitted fields and the provenance of tool or memory fixtures. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Replay datasets and runs](/insights/evaluation/datasets-and-runs) · [Dataset identity and run provenance](/api/evals/datasets) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for adding an input and expected-output pair in an evaluation dataset. ### Input constraints ### Record relationship Exactly one of these two conditions must hold: source\_trace\_id is nonempty; both conversation\_id and source\_user\_message\_id are nonempty. When source\_trace\_id is nonempty, the pair must be incomplete, but this predicate does not forbid one nonempty partial-pair field. When source\_trace\_id is empty, both fields in the pair must be nonempty. **datasetId** `string` **required** Identifier of the evaluation dataset. Minimum length: 1 **inputJson** `string` Dataset item input serialized as JSON text. **expectedOutputJson** `string` Expected dataset item output serialized as JSON text. **sourceTraceId** `string` Identifier of the trace used as the source for the dataset item. **metadataJson** `string` Additional evaluation metadata serialized as JSON text. **conversationId** `string` Identifier of the conversation associated with the evaluation record. Maximum length: 256 **sourceUserMessageId** `string` Identifier of the user message that originated the evaluated generation. Maximum length: 256 #### evals-addDatasetItem-request Harvest an existing trace into a named dataset; replace sourceTraceId with the trace being curated. ```json { "datasetId": "support-answers", "sourceTraceId": "trace_123", "inputJson": "{\"question\":\"How do I reset my password?\"}", "expectedOutputJson": "\"Use the password reset link on the sign-in page.\"" } ``` #### cookbook-insights-evaluation-datasets-and-runs-02-request Guide request for 2. Save the input needed to reproduce the problem. Replace example resource identifiers with your own authorized values. ```json { "datasetId": "support-assistant-regressions", "conversationId": "conv_123", "sourceUserMessageId": "msg_abc", "inputJson": "{\"question\":\"What is the return window?\"}" } ``` ## Responses ### 200 — OK Content type: `application/json` Result of adding an input and expected-output pair in an evaluation dataset. **itemId** `string` Identifier of the evaluation dataset item added by the operation. #### evals-addDatasetItem-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "itemId": "example_123" } ``` Document ID: `DOC-IS-evaluation-api-addDatasetItem`. [Section identities and revisions](/documentation-manifest.json). - Add a dataset item: `DOC-IS-evaluation-api-addDatasetItem#overview` - Request: `DOC-IS-evaluation-api-addDatasetItem#request` - Responses: `DOC-IS-evaluation-api-addDatasetItem#responses` --- # Complete an annotation queue item URL: https://docs.travila.ai/api/evals/complete-annotation-queue-item **POST** `/api/v1/evals/complete-annotation-queue-item` Marks an annotation queue item completed. The immediate response can contain [`completedBy`](/api/models/schema-ovc35nr9td#response-field-completedby), but the current API does not persist that attribution for later list reads. Do not use this response alone as a durable reviewer audit record. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Review and score turns](/insights/evaluation/review) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for completing an evaluation object in an annotation queue. **queueId** `string` **required** Identifier of the evaluation annotation queue. Minimum length: 1 **itemId** `string` **required** Identifier of the annotation queue item to complete. Minimum length: 1 #### evals-completeAnnotationQueueItem-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "queueId": "example_123", "itemId": "example_123" } ``` #### cookbook-insights-evaluation-review-07-request Guide request for 4. Complete the saved review. Replace example resource identifiers with your own authorized values. ```json { "queueId": "q_weekly", "itemId": "qi_001" } ``` ## Responses ### 200 — OK Content type: `application/json` Result of completing an evaluation object in an annotation queue. **item** `any` Annotation queue item returned by the operation. All of: Variant 1: Evaluation object assigned to an annotation queue with completion state and attribution. Model reference: [AnnotationQueueItem](/api/models/schema-ovc35nr9td#response). **itemId** `string` Identifier of the annotation queue item. **queueId** `string` Identifier of the annotation queue. **objectId** `string` Identifier of the evaluation object addressed by the annotation queue item. **objectType** `any` Kind of evaluation object addressed by the annotation queue item. Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_TARGET_TYPE_TRACE` | 0 | Canonical | A complete trace identified by its trace identifier. | | `EVAL_TARGET_TYPE_OBSERVATION` | 1 | Canonical | A specific observation within a trace. | | `EVAL_TARGET_TYPE_DATASET_RUN` | 2 | Canonical | An evaluation run over a dataset. | | `EVAL_TARGET_TYPE_SESSION` | 3 | Canonical | A session grouping multiple traces. The evaluation harness attaches session-scoped judge scores directly; the provider does not expose a session-level evaluator target. |
Exactly one of: Variant 1: Type: `string` Enum: `EVAL_TARGET_TYPE_TRACE`, `EVAL_TARGET_TYPE_OBSERVATION`, `EVAL_TARGET_TYPE_DATASET_RUN`, `EVAL_TARGET_TYPE_SESSION` Variant 2: Type: `integer(int32)` **status** `any` Completion state of the annotation queue item. Progress of a work item in a human annotation queue.
| Value | No. | Form | Meaning | |---|---|---|---| | `ANNOTATION_QUEUE_ITEM_STATUS_PENDING` | 0 | Canonical | The item is waiting for its annotation to be completed. | | `ANNOTATION_QUEUE_ITEM_STATUS_COMPLETED` | 1 | Canonical | Annotation of the queue item has been completed. |
Exactly one of: Variant 1: Type: `string` Enum: `ANNOTATION_QUEUE_ITEM_STATUS_PENDING`, `ANNOTATION_QUEUE_ITEM_STATUS_COMPLETED` Variant 2: Type: `integer(int32)` **completedAt** `string(date-time)` Time when the operation was marked complete. **completedBy** `string` Identifier of the user who completed the annotation queue item. **createdAt** `string(date-time)` Time when this record was created. #### evals-completeAnnotationQueueItem-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "item": { "itemId": "example_123", "queueId": "example_123", "objectId": "example_123", "objectType": "EVAL_TARGET_TYPE_TRACE", "status": "ANNOTATION_QUEUE_ITEM_STATUS_PENDING", "completedAt": "2026-09-16T12:00:00Z", "completedBy": "example", "createdAt": "2026-09-16T12:00:00Z" } } ``` #### cookbook-insights-evaluation-review-json-02-response Illustrative response for 4. Complete the saved review. Replace example resource identifiers with your own authorized values. ```json { "item": { "itemId": "qi_001", "queueId": "q_weekly", "status": "ANNOTATION_QUEUE_ITEM_STATUS_COMPLETED", "completedAt": "2026-08-12T17:14:22Z", "completedBy": "reviewer_9" } } ``` Document ID: `DOC-IS-evaluation-api-completeAnnotationQueueItem`. [Section identities and revisions](/documentation-manifest.json). - Complete an annotation queue item: `DOC-IS-evaluation-api-completeAnnotationQueueItem#overview` - Request: `DOC-IS-evaluation-api-completeAnnotationQueueItem#request` - Responses: `DOC-IS-evaluation-api-completeAnnotationQueueItem#responses` --- # Create an annotation queue URL: https://docs.travila.ai/api/evals/create-annotation-queue **POST** `/api/v1/evals/create-annotation-queue` Creates a review queue bound to a set of score configs — the scales reviewers will use on it. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Review and score turns](/insights/evaluation/review) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for creating a queue of evaluation objects awaiting annotation. **name** `string` **required** Name assigned to the evaluation annotation queue. Minimum length: 1 **scoreConfigIds** `array[string]` **required** At least one: a queue's fixed config set is the whole difference between it and ad-hoc annotation. Minimum items: 1 Type: `string` **description** `string` Human-readable explanation of the evaluation record. #### evals-createAnnotationQueue-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "name": "example", "scoreConfigIds": [ "example_123" ] } ``` #### cookbook-insights-evaluation-review-02-request Guide request for 2. Queue what needs reviewing. Replace example resource identifiers with your own authorized values. ```json { "name": "weekly-qa", "scoreConfigIds": [ "cfg_helpfulness" ] } ``` ## Responses ### 200 — OK Content type: `application/json` Result of creating a queue of evaluation objects awaiting annotation. **queueId** `string` Identifier of the evaluation annotation queue. #### evals-createAnnotationQueue-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "queueId": "example_123" } ``` Document ID: `DOC-IS-evaluation-api-createAnnotationQueue`. [Section identities and revisions](/documentation-manifest.json). - Create an annotation queue: `DOC-IS-evaluation-api-createAnnotationQueue#overview` - Request: `DOC-IS-evaluation-api-createAnnotationQueue#request` - Responses: `DOC-IS-evaluation-api-createAnnotationQueue#responses` --- # Create a comment URL: https://docs.travila.ai/api/evals/create-comment **POST** `/api/v1/evals/create-comment` Attaches a reviewer note to an evaluation object. Author attribution comes from trusted caller context when available; a bare key may create an unattributed comment. Current withdrawal suppresses platform reads rather than proving physical erasure. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Review and score turns](/insights/evaluation/review) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for creating a comment attached to an evaluation object. **objectType** `any` **required** Kind of evaluation object to which the comment belongs. Kind of evaluation object to which a reviewer comment is attached.
| Value | No. | Form | Meaning | |---|---|---|---| | `COMMENT_OBJECT_TYPE_TRACE` | 0 | Canonical | Attach the comment to a trace. | | `COMMENT_OBJECT_TYPE_OBSERVATION` | 1 | Canonical | Attach the comment to a particular observation. | | `COMMENT_OBJECT_TYPE_SESSION` | 2 | Canonical | Attach the comment to a session. | | `COMMENT_OBJECT_TYPE_PROMPT` | 3 | Canonical | Attach the comment to a specific prompt version using that version's UUID, not the prompt name. A comment on one version does not appear on later versions. |
Exactly one of: Variant 1: Type: `string` Enum: `COMMENT_OBJECT_TYPE_TRACE`, `COMMENT_OBJECT_TYPE_OBSERVATION`, `COMMENT_OBJECT_TYPE_SESSION`, `COMMENT_OBJECT_TYPE_PROMPT` Variant 2: Type: `integer(int32)` Enum: `0`, `1`, `2`, `3` **objectId** `string` **required** Identifier of the evaluation object to which the comment belongs. Minimum length: 1 **content** `string` **required** Body of the evaluation comment. Minimum length: 1 Maximum length: 3000 #### evals-createComment-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "objectType": "COMMENT_OBJECT_TYPE_TRACE", "objectId": "example_123", "content": "Example text" } ``` #### cookbook-insights-evaluation-review-06-request Guide request for Save the explanation with the reviewed turn. Replace example resource identifiers with your own authorized values. ```json { "objectType": "COMMENT_OBJECT_TYPE_TRACE", "objectId": "trc_a1b2c3", "content": "Tool call returned stale data." } ``` ## Responses ### 200 — OK Content type: `application/json` Result of creating a comment attached to an evaluation object. **commentId** `string` Identifier of the evaluation comment. #### evals-createComment-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "commentId": "example_123" } ``` Document ID: `DOC-IS-evaluation-api-createComment`. [Section identities and revisions](/documentation-manifest.json). - Create a comment: `DOC-IS-evaluation-api-createComment#overview` - Request: `DOC-IS-evaluation-api-createComment#request` - Responses: `DOC-IS-evaluation-api-createComment#responses` --- # Create a dataset URL: https://docs.travila.ai/api/evals/create-dataset **POST** `/api/v1/evals/create-dataset` Creates an evaluation dataset. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Replay datasets and runs](/insights/evaluation/datasets-and-runs) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for creating an evaluation dataset. **name** `string` **required** Name assigned to the evaluation dataset. Minimum length: 1 **description** `string` Human-readable explanation of the evaluation record. **metadataJson** `string` Additional evaluation metadata serialized as JSON text. #### evals-createDataset-request Create a named dataset for subsequent curation. ```json { "name": "support-answers", "description": "Curated product support questions and expected answers." } ``` #### cookbook-insights-evaluation-datasets-and-runs-01-request Guide request for 1. Create the dataset. Replace example resource identifiers with your own authorized values. ```json { "name": "support-assistant-regressions", "description": "Turns we do not want to break" } ``` ## Responses ### 200 — OK Content type: `application/json` Result of creating an evaluation dataset. **datasetId** `string` Identifier of the evaluation dataset. #### evals-createDataset-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "datasetId": "example_123" } ``` Document ID: `DOC-IS-evaluation-api-createDataset`. [Section identities and revisions](/documentation-manifest.json). - Create a dataset: `DOC-IS-evaluation-api-createDataset#overview` - Request: `DOC-IS-evaluation-api-createDataset#request` - Responses: `DOC-IS-evaluation-api-createDataset#responses` --- # Create a score config URL: https://docs.travila.ai/api/evals/create-score-config **POST** `/api/v1/evals/create-score-config` Creates a rating scale that gives scores a consistent interpretation across turns. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Review and score turns](/insights/evaluation/review) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for creating the definition and allowed values of an evaluation score. **name** `string` **required** Name assigned to the evaluation score configuration. Minimum length: 1 **dataType** `any` **required** Value type used to interpret the evaluation score. Scores Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_DATA_TYPE_NUMERIC` | 0 | Canonical | A numeric measurement or rating. | | `SCORE_DATA_TYPE_CATEGORICAL` | 1 | Canonical | A value chosen from a named set of categories. | | `SCORE_DATA_TYPE_BOOLEAN` | 2 | Canonical | A true-or-false evaluation result. | | `SCORE_DATA_TYPE_TEXT` | 3 | Canonical | Free-form text supplied by an evaluator or reviewer. The provider supports text values on score definitions and scores; support through this API depends on the operation. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_DATA_TYPE_NUMERIC`, `SCORE_DATA_TYPE_CATEGORICAL`, `SCORE_DATA_TYPE_BOOLEAN`, `SCORE_DATA_TYPE_TEXT` Variant 2: Type: `integer(int32)` Enum: `0`, `1`, `2`, `3` **categoricalValues** `array[string]` Allowed category values for the score configuration. Type: `string` **minValue** `any` Lower numeric bound for the score range. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxValue** `any` Upper numeric bound for the score range. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` #### evals-createScoreConfig-request Create a numeric scoring rubric ranging from zero to one. ```json { "name": "answer-quality", "dataType": "SCORE_DATA_TYPE_NUMERIC", "minValue": 0, "maxValue": 1 } ``` #### cookbook-insights-evaluation-review-01-request Guide request for 1. Define the dimensions first. Replace example resource identifiers with your own authorized values. ```json { "name": "helpfulness", "dataType": "SCORE_DATA_TYPE_NUMERIC", "minValue": 1, "maxValue": 5 } ``` ## Responses ### 200 — OK Content type: `application/json` Result of creating the definition and allowed values of an evaluation score. **configId** `string` Identifier of the evaluation score configuration. #### evals-createScoreConfig-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "configId": "example_123" } ``` Document ID: `DOC-IS-evaluation-api-createScoreConfig`. [Section identities and revisions](/documentation-manifest.json). - Create a score config: `DOC-IS-evaluation-api-createScoreConfig#overview` - Request: `DOC-IS-evaluation-api-createScoreConfig#request` - Responses: `DOC-IS-evaluation-api-createScoreConfig#responses` --- # Delete a comment URL: https://docs.travila.ai/api/evals/delete-comment **POST** `/api/v1/evals/delete-comment` Suppresses the selected comment from platform reads. The provider retains the comment; a successful response does not mean it was deleted from the provider. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Review and score turns](/insights/evaluation/review) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for deleting a comment attached to an evaluation object. **commentId** `string` **required** Identifier of the evaluation comment. Minimum length: 1 #### evals-deleteComment-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "commentId": "example_123" } ``` ## Responses ### 200 — OK Content type: `application/json` Result of deleting a comment attached to an evaluation object. **deleted** `boolean` Whether the deletion operation reported that it deleted the selected resource. #### evals-deleteComment-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "deleted": true } ``` Document ID: `DOC-IS-evaluation-api-deleteComment`. [Section identities and revisions](/documentation-manifest.json). - Delete a comment: `DOC-IS-evaluation-api-deleteComment#overview` - Request: `DOC-IS-evaluation-api-deleteComment#request` - Responses: `DOC-IS-evaluation-api-deleteComment#responses` --- # Delete a score URL: https://docs.travila.ai/api/evals/delete-score **POST** `/api/v1/evals/delete-score` Deletes a score by ID. The current implementation checks access to the evaluation backend but does not enforce per-author ownership for deletion. Restrict this operation to trusted evaluation administrators until that requirement is implemented. Obtain the score ID from [list scores](/api/evals/list-scores), read back the deletion result and allow for delayed updates in other views. An immediate response does not establish that every analytics projection is cleared. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Review and score turns](/insights/evaluation/review) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for deleting a score attached to an evaluation object. **scoreId** `string` **required** Identifier of the recorded evaluation score. Minimum length: 1 #### evals-deleteScore-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "scoreId": "example_123" } ``` #### cookbook-insights-evaluation-review-08-request Guide request for Withdraw a rating. Replace example resource identifiers with your own authorized values. ```json { "scoreId": "scr_7788" } ``` ## Responses ### 200 — OK Content type: `application/json` Result of deleting a score attached to an evaluation object. **deleted** `boolean` Whether the deletion operation reported that it deleted the selected resource. #### evals-deleteScore-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "deleted": true } ``` Document ID: `DOC-IS-evaluation-api-deleteScore`. [Section identities and revisions](/documentation-manifest.json). - Delete a score: `DOC-IS-evaluation-api-deleteScore#overview` - Request: `DOC-IS-evaluation-api-deleteScore#request` - Responses: `DOC-IS-evaluation-api-deleteScore#responses` --- # Enqueue an item for annotation URL: https://docs.travila.ai/api/evals/enqueue-for-annotation **POST** `/api/v1/evals/enqueue-for-annotation` Adds a trace, observation or session to a review queue. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Review and score turns](/insights/evaluation/review) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for adding an evaluation object to an annotation queue. **queueId** `string` **required** Identifier of the evaluation annotation queue. Minimum length: 1 **targetType** `any` **required** Kind of evaluation object assigned to the annotation queue. Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_TARGET_TYPE_TRACE` | 0 | Canonical | A complete trace identified by its trace identifier. | | `EVAL_TARGET_TYPE_OBSERVATION` | 1 | Canonical | A specific observation within a trace. | | `EVAL_TARGET_TYPE_DATASET_RUN` | 2 | Canonical | An evaluation run over a dataset. | | `EVAL_TARGET_TYPE_SESSION` | 3 | Canonical | A session grouping multiple traces. The evaluation harness attaches session-scoped judge scores directly; the provider does not expose a session-level evaluator target. |
Exactly one of: Variant 1: Type: `string` Enum: `EVAL_TARGET_TYPE_TRACE`, `EVAL_TARGET_TYPE_OBSERVATION`, `EVAL_TARGET_TYPE_DATASET_RUN`, `EVAL_TARGET_TYPE_SESSION` Variant 2: Type: `integer(int32)` Enum: `0`, `1`, `2`, `3` **targetId** `string` **required** Identifier of the evaluation object assigned to the annotation queue. Minimum length: 1 #### evals-enqueueForAnnotation-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "queueId": "example_123", "targetType": "EVAL_TARGET_TYPE_TRACE", "targetId": "example_123" } ``` #### cookbook-insights-evaluation-review-03-request Guide request for 2. Queue what needs reviewing. Replace example resource identifiers with your own authorized values. ```json { "queueId": "q_weekly", "targetType": "EVAL_TARGET_TYPE_TRACE", "targetId": "trc_a1b2c3" } ``` ## Responses ### 200 — OK Content type: `application/json` Result of adding an evaluation object to an annotation queue. **queueItemId** `string` Identifier assigned to the item in the annotation queue. #### evals-enqueueForAnnotation-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "queueItemId": "example_123" } ``` Document ID: `DOC-IS-evaluation-api-enqueueForAnnotation`. [Section identities and revisions](/documentation-manifest.json). - Enqueue an item for annotation: `DOC-IS-evaluation-api-enqueueForAnnotation#overview` - Request: `DOC-IS-evaluation-api-enqueueForAnnotation#request` - Responses: `DOC-IS-evaluation-api-enqueueForAnnotation#responses` --- # Eval APIs URL: https://docs.travila.ai/api/evals Version: `aju17f20mq` Use the reference below for request and response fields and operation-specific requirements. # Overview \{#overview} Read traces and scores, curate datasets, and read evaluation runs. These are evaluation and observability operations. ## Authentication \{#authentication} Use an authorized backend `sk_…` key in `X-API-Key`; most evaluation operations do not need an end-user identity; record-score requires an attributable verified subject. A console JWT belongs to the separate console surface. See [Authentication](https://docs.travila.ai/core-platform/identity-access/authentication). ### Projects \{#projects} 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. User IDs in read filters identify evaluated subjects; they do not assert the caller’s identity. Machine credentials do not establish a human reviewer. Reviewer attribution is taken from trusted caller context when available. HTTP 424 means evaluation is not provisioned for the selected scope. Contact your Travila operator; repeating the same request will not provision it. ### Current API limits \{#current-adapter-limits} `record-score` currently maps numeric and boolean values and sends the resolved target as a trace ID. Categorical/text and observation/session/dataset-run scoring are not faithfully implemented despite their schema enum values. `delete-score` does not currently enforce per-author ownership. Restrict this API to trusted evaluation operators until those controls are qualified. ### Pagination \{#pagination} Cursor lists are list-traces, list-observations, list-scores, list-sessions and list-dataset-runs. Send pageSize, then the exact returned cursorPage.nextCursor as cursor. Continue after a short or empty page when that cursor is present. Other lists use one-based page/pageSize. Only trace lists can return an optional exact total; an unavailable total is not zero. Keep the same scope, filters and time window across pages. Old traces can lack entity tags. ### Reading responses \{#reading-responses} `contentRedacted: true` reports redaction, while its absence is not proof that content is verbatim or free of sensitive information. **Related guide:** [Measure and improve quality](https://docs.travila.ai/insights/evaluation) ### Field naming \{#field-naming} 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](https://docs.travila.ai/api). These examples use cursor pagination where indicated. Older API versions can use page numbers. Match your client to the API available to your account. To attribute a turn to a dataset run, set the `experiment` block on send-message or send-message-sync when the turn is sent; there is no operation that associates traces with a run after they have been recorded. ## Traces \{#reference-group-1} Read the trace an LLM turn produced, and the observations inside it. * [Get a trace](/api/evals/get-trace) * [List observations](/api/evals/list-observations) * [List traces](/api/evals/list-traces) ## Sessions \{#reference-group-2} Group traces by session. * [Get a session](/api/evals/get-session) * [List sessions](/api/evals/list-sessions) ## Scores \{#reference-group-3} Read scores and record numeric or boolean reviewer ratings on traces. Other target and value types are not currently supported for score writes. * [Delete a score](/api/evals/delete-score) * [List scores](/api/evals/list-scores) * [Record a score](/api/evals/record-score) ## Score configs \{#reference-group-4} Define the rating scales reviewers pick from. * [Create a score config](/api/evals/create-score-config) * [List score configs](/api/evals/list-score-configs) * [Update a score config](/api/evals/update-score-config) ## Comments \{#reference-group-5} Free-text notes attached to a trace, observation or session. * [Create a comment](/api/evals/create-comment) * [Delete a comment](/api/evals/delete-comment) * [List comments](/api/evals/list-comments) ## Datasets \{#reference-group-6} Curate evaluation datasets and the items in them. * [Add a dataset item](/api/evals/add-dataset-item) * [Create a dataset](/api/evals/create-dataset) * [List dataset items](/api/evals/list-dataset-items) * [List datasets](/api/evals/list-datasets) * [Update a dataset item](/api/evals/update-dataset-item) ## Dataset runs \{#reference-group-7} Record what a harness scored on a dataset, and read past runs back. * [Get a dataset run](/api/evals/get-dataset-run) * [List dataset runs](/api/evals/list-dataset-runs) ## Annotation queues \{#reference-group-8} Queue items for human review and mark them done. * [Complete an annotation queue item](/api/evals/complete-annotation-queue-item) * [Create an annotation queue](/api/evals/create-annotation-queue) * [Enqueue an item for annotation](/api/evals/enqueue-for-annotation) * [List annotation queue items](/api/evals/list-annotation-queue-items) * [List annotation queues](/api/evals/list-annotation-queues) ## Overview \{#reference-group-9} Aggregate counts and score averages for a time window. * [Get the eval overview](/api/evals/get-overview) ## Server 1 \{#reference-server-1} Travila API [https://api.travila.ai](https://api.travila.ai) ## X-API-Key \{#authentication-apiKeyAuth} Authorized tenant backend secret key (`sk_…`). Most evaluation operations do not need an end-user identity; record-score requires an attributable verified subject. Keep the key out of client apps; authorization and provisioning still apply.

Authentication credentials

### apiKeyAuth Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-API-Key` ### onBehalfOf Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-On-Behalf-Of` ### bearerAuth Security scheme type: `http` HTTP authorization scheme: `bearer` ## Operations - [List traces](/api/evals/list-traces) — `POST /api/v1/evals/list-traces` - [Get a trace](/api/evals/get-trace) — `POST /api/v1/evals/get-trace` - [List observations](/api/evals/list-observations) — `POST /api/v1/evals/list-observations` - [List sessions](/api/evals/list-sessions) — `POST /api/v1/evals/list-sessions` - [Get a session](/api/evals/get-session) — `POST /api/v1/evals/get-session` - [List scores](/api/evals/list-scores) — `POST /api/v1/evals/list-scores` - [Record a score](/api/evals/record-score) — `POST /api/v1/evals/record-score` - [Delete a score](/api/evals/delete-score) — `POST /api/v1/evals/delete-score` - [List score configs](/api/evals/list-score-configs) — `POST /api/v1/evals/list-score-configs` - [Create a score config](/api/evals/create-score-config) — `POST /api/v1/evals/create-score-config` - [Update a score config](/api/evals/update-score-config) — `POST /api/v1/evals/update-score-config` - [Create a comment](/api/evals/create-comment) — `POST /api/v1/evals/create-comment` - [List comments](/api/evals/list-comments) — `POST /api/v1/evals/list-comments` - [Delete a comment](/api/evals/delete-comment) — `POST /api/v1/evals/delete-comment` - [List datasets](/api/evals/list-datasets) — `POST /api/v1/evals/list-datasets` - [Create a dataset](/api/evals/create-dataset) — `POST /api/v1/evals/create-dataset` - [Add a dataset item](/api/evals/add-dataset-item) — `POST /api/v1/evals/add-dataset-item` - [List dataset items](/api/evals/list-dataset-items) — `POST /api/v1/evals/list-dataset-items` - [Update a dataset item](/api/evals/update-dataset-item) — `POST /api/v1/evals/update-dataset-item` - [List dataset runs](/api/evals/list-dataset-runs) — `POST /api/v1/evals/list-dataset-runs` - [Get a dataset run](/api/evals/get-dataset-run) — `POST /api/v1/evals/get-dataset-run` - [List annotation queues](/api/evals/list-annotation-queues) — `POST /api/v1/evals/list-annotation-queues` - [Create an annotation queue](/api/evals/create-annotation-queue) — `POST /api/v1/evals/create-annotation-queue` - [Enqueue an item for annotation](/api/evals/enqueue-for-annotation) — `POST /api/v1/evals/enqueue-for-annotation` - [List annotation queue items](/api/evals/list-annotation-queue-items) — `POST /api/v1/evals/list-annotation-queue-items` - [Complete an annotation queue item](/api/evals/complete-annotation-queue-item) — `POST /api/v1/evals/complete-annotation-queue-item` - [Get the eval overview](/api/evals/get-overview) — `POST /api/v1/evals/get-overview` Document ID: `DOC-API-evals-overview`. [Section identities and revisions](/documentation-manifest.json). - Overview: `DOC-API-evals-overview#overview` - Authentication: `DOC-API-evals-overview#authentication` - Projects: `DOC-API-evals-overview#projects` - Current API limits: `DOC-API-evals-overview#current-adapter-limits` - Pagination: `DOC-API-evals-overview#pagination` - Reading responses: `DOC-API-evals-overview#reading-responses` - Field naming: `DOC-API-evals-overview#field-naming` - Traces: `DOC-API-evals-overview#reference-group-1` - Sessions: `DOC-API-evals-overview#reference-group-2` - Scores: `DOC-API-evals-overview#reference-group-3` - Score configs: `DOC-API-evals-overview#reference-group-4` - Comments: `DOC-API-evals-overview#reference-group-5` - Datasets: `DOC-API-evals-overview#reference-group-6` - Dataset runs: `DOC-API-evals-overview#reference-group-7` - Annotation queues: `DOC-API-evals-overview#reference-group-8` - Overview: `DOC-API-evals-overview#reference-group-9` - Server 1: `DOC-API-evals-overview#reference-server-1` - X-API-Key: `DOC-API-evals-overview#authentication-apiKeyAuth` --- # Get a dataset run URL: https://docs.travila.ai/api/evals/get-dataset-run **POST** `/api/v1/evals/get-dataset-run` Fetches run metadata by dataset name and run name. It does not return per-item results. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Replay datasets and runs](/insights/evaluation/datasets-and-runs) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for retrieving a named run against an evaluation dataset. **datasetName** `string` **required** Name used to address the evaluation dataset. Minimum length: 1 **runName** `string` **required** Name assigned to the evaluation dataset run. Minimum length: 1 #### evals-getDatasetRun-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "datasetName": "example", "runName": "example" } ``` #### cookbook-insights-evaluation-datasets-and-runs-07-request Guide request for 5. Decide whether the change fixes the problem without regressions. Replace example resource identifiers with your own authorized values. ```json { "datasetName": "support-assistant-regressions", "runName": "2026-08-12-candidate" } ``` ## Responses ### 200 — OK Content type: `application/json` Result of retrieving a named run against an evaluation dataset. **run** `any` Evaluation dataset run returned by the lookup. All of: Variant 1: Metadata describing one execution of an evaluation dataset. Model reference: [DatasetRun](/api/models/schema-1jehhpchdc#response). **runId** `string` Identifier of the evaluation dataset run. **datasetId** `string` Identifier of the evaluation dataset. **name** `string` Name assigned to this execution of the evaluation dataset. **description** `string` Human-readable description of the resource. **metadataJson** `string` Additional attributes serialized as a JSON object. **itemCount** `string(int64)` Number of dataset items reported for this run. Pattern: ^-?\d+$ **createdAt** `string(date-time)` Time when this record was created. #### evals-getDatasetRun-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "run": { "runId": "example_123", "datasetId": "example_123", "name": "example", "description": "example", "metadataJson": "{}", "itemCount": 1, "createdAt": "2026-09-16T12:00:00Z" } } ``` #### cookbook-insights-evaluation-datasets-and-runs-json-02-response Illustrative response for 5. Decide whether the change fixes the problem without regressions. Replace example resource identifiers with your own authorized values. ```json { "run": { "runId": "run_0912", "name": "2026-08-12-candidate", "datasetId": "ds_771", "itemCount": 120, "metadataJson": "{\"profileRevisionHash\":\"9f2c1e…\"}", "createdAt": "2026-08-12T18:00:00Z" } } ``` Document ID: `DOC-IS-evaluation-api-getDatasetRun`. [Section identities and revisions](/documentation-manifest.json). - Get a dataset run: `DOC-IS-evaluation-api-getDatasetRun#overview` - Request: `DOC-IS-evaluation-api-getDatasetRun#request` - Responses: `DOC-IS-evaluation-api-getDatasetRun#responses` --- # Get the eval overview URL: https://docs.travila.ai/api/evals/get-overview **POST** `/api/v1/evals/get-overview` Aggregate trace counts, score averages and totals for a time window — the numbers behind a dashboard. Coverage and profile cards use the first 100 roots/scores, while volume metrics can describe a larger population. Observation-targeted scores are not counted as trace coverage. A profile filter does not establish a consistent denominator for every card; do not use these mixed populations as a release gate. ### Overview populations and configuration identity Interpret quality alongside a fixed dataset's eligible, evaluated, failed and excluded cases; sampled coverage is not the proportion of every turn reviewed. Save the full configuration in the [regression workflow](/insights/evaluation/datasets-and-runs#4-record-the-run) before attributing a difference to one change. Callers use platform API access and do not need an evaluation-provider credential or direct evaluation-provider URL. Authorisation depends on verified caller identity and scope, not on which client interface made the request. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Find out why a customer’s reply was slow](/insights/evaluation/reading) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for retrieving aggregate evaluation activity and score statistics. **fromTime** `string(date-time)` Beginning of the time range used to select evaluation records. **toTime** `string(date-time)` End of the time range used to select evaluation records. **profileId** `string` Identifier of the agent profile associated with the operation or generation. Maximum length: 256 **environment** `string` Environment label used to select evaluation records. Maximum length: 256 #### evals-getOverview-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json {} ``` ## Responses ### 200 — OK Content type: `application/json` Result of retrieving aggregate evaluation activity and score statistics. **overview** `any` Aggregate evaluation activity and score statistics for the selected scope. All of: Variant 1: Aggregated trace, score, latency, and profile metrics for an evaluation window. Model reference: [EvalOverview](/api/models/schema-1js2bf073d#response). **totalTraces** `string(int64)` Total trace count reported for the selected evaluation window. Pattern: ^-?\d+$ **tracesByName** `array[llm_v1_services_eval_v1_NamedCount]` Trace counts grouped by trace name. Count of evaluation records grouped under a shared label. Model reference: [NamedCount](/api/models/schema-1jiel5uim6#response). **name** `string` Grouping label associated with this record count. **count** `string(int64)` Number of evaluation records represented by this group. Pattern: ^-?\d+$ **tracesOverTime** `array[llm_v1_services_eval_v1_TimeSeriesPoint]` Trace counts grouped into time buckets. Numeric evaluation measurement associated with a time bucket and series. Model reference: [TimeSeriesPoint](/api/models/schema-1jq6h5scn9#response). **bucket** `string(date-time)` Time bucket identifying this point in the evaluation series. **value** `any` Numeric measurement recorded for this time bucket and series. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **series** `string` Series key when the query is split — a score name, level, or profile id. **observationsByLevel** `array[llm_v1_services_eval_v1_TimeSeriesPoint]` Observation counts grouped by reported log level. Numeric evaluation measurement associated with a time bucket and series. Model reference: [TimeSeriesPoint](/api/models/schema-1jq6h5scn9#response). **bucket** `string(date-time)` Time bucket identifying this point in the evaluation series. **value** `any` Numeric measurement recorded for this time bucket and series. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **series** `string` Series key when the query is split — a score name, level, or profile id. **scores** `array[llm_v1_services_eval_v1_ScoreAggregate]` Score aggregates grouped separately by metric name and source. Count and average for scores grouped by name and source. Model reference: [ScoreAggregate](/api/models/schema-1jo37n9pqa#response). **name** `string` Metric name shared by the aggregated scores. **source** `any` Source classification reported for the evaluation score. Platform classification of who produced an evaluation score. The provider source label retains its original vocabulary: writes accept API or ANNOTATION, while EVAL is reserved for the provider's internal evaluators and is rejected through its public API. SCORE\_SOURCE\_HUMAN maps to ANNOTATION. SCORE\_SOURCE\_USER, SCORE\_SOURCE\_JUDGE and SCORE\_SOURCE\_HARNESS map to API. Reviewer and end-user scores also use separate name namespaces: reviewer scores do not use names beginning with user-feedback-.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_SOURCE_JUDGE` | 0 | Canonical | A score produced by an automated judge. | | `SCORE_SOURCE_HUMAN` | 1 | Canonical | A score entered by a human reviewer through the annotation path. | | `SCORE_SOURCE_USER` | 2 | Canonical | Feedback supplied by an end user. | | `SCORE_SOURCE_HARNESS` | 3 | Canonical | A score written by an evaluation harness or another API-based producer. | | `SCORE_SOURCE_EVAL` | 4 | Canonical | A read-only score produced by the evaluation provider's managed evaluators; it cannot be written through the public score API. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_SOURCE_JUDGE`, `SCORE_SOURCE_HUMAN`, `SCORE_SOURCE_USER`, `SCORE_SOURCE_HARNESS`, `SCORE_SOURCE_EVAL` Variant 2: Type: `integer(int32)` **count** `string(int64)` Number of evaluation records represented by this group. Pattern: ^-?\d+$ **average** `any` Average score value reported for the aggregate. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **scoreMovingAverage** `array[llm_v1_services_eval_v1_TimeSeriesPoint]` Moving-average score series returned for the selected window. Numeric evaluation measurement associated with a time bucket and series. Model reference: [TimeSeriesPoint](/api/models/schema-1jq6h5scn9#response). **bucket** `string(date-time)` Time bucket identifying this point in the evaluation series. **value** `any` Numeric measurement recorded for this time bucket and series. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **series** `string` Series key when the query is split — a score name, level, or profile id. **scoredTraceRatio** `any` Coverage card: share of traces carrying any score, and the annotated count. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **annotatedTraceCount** `string(int64)` Number of traces reported to have annotations in the selected window. Pattern: ^-?\d+$ **byProfile** `array[llm_v1_services_eval_v1_ProfileQualityRow]` Evaluation metrics grouped by agent profile. Aggregated evaluation results and usage for one agent profile. Model reference: [ProfileQualityRow](/api/models/schema-1jku9efe5c#response). **profileId** `string` Identifier of the agent profile associated with the generation. **traceCount** `string(int64)` Number of traces represented by this summary or group. Pattern: ^-?\d+$ **avgEndUserRating** `any` Average end-user rating reported for the selected generation group. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **avgJudgeScore** `any` Average automated judge score reported for the selected generation group. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **thumbsDownCount** `string(int64)` Number of negative thumb ratings reported for the selected group. Pattern: ^-?\d+$ **latencyPercentiles** `array[llm_v1_services_eval_v1_LatencyPercentileRow]` Latency percentile summaries grouped by trace name. Latency percentiles, in seconds, aggregated for one evaluation trace name. Model reference: [LatencyPercentileRow](/api/models/schema-1jgrpr157a#response). **traceName** `string` Display name used to group or identify the evaluation trace. **p50** `any` 50th-percentile latency for the trace group, in seconds. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p90** `any` 90th-percentile latency for the trace group, in seconds. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p95** `any` 95th-percentile latency for the trace group, in seconds. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **p99** `any` 99th-percentile latency for the trace group, in seconds. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **recentLowScores** `array[llm_v1_services_eval_v1_Score]` Recent scores selected by the overview’s low-score query. Evaluation score with its value, source, target identity, and generation attribution. Model reference: [Score](/api/models/schema-1jm5lo00e7#response). **scoreId** `string` Identifier of the evaluation score. **targetType** `any` Kind of evaluation object to which the score applies. Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_TARGET_TYPE_TRACE` | 0 | Canonical | A complete trace identified by its trace identifier. | | `EVAL_TARGET_TYPE_OBSERVATION` | 1 | Canonical | A specific observation within a trace. | | `EVAL_TARGET_TYPE_DATASET_RUN` | 2 | Canonical | An evaluation run over a dataset. | | `EVAL_TARGET_TYPE_SESSION` | 3 | Canonical | A session grouping multiple traces. The evaluation harness attaches session-scoped judge scores directly; the provider does not expose a session-level evaluator target. |
Exactly one of: Variant 1: Type: `string` Enum: `EVAL_TARGET_TYPE_TRACE`, `EVAL_TARGET_TYPE_OBSERVATION`, `EVAL_TARGET_TYPE_DATASET_RUN`, `EVAL_TARGET_TYPE_SESSION` Variant 2: Type: `integer(int32)` **targetId** `string` Identifier of the evaluation object to which the score applies. **name** `string` Metric name identifying the recorded evaluation score. **dataType** `any` Value type used to interpret numeric, categorical, Boolean, or text score values. Scores Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_DATA_TYPE_NUMERIC` | 0 | Canonical | A numeric measurement or rating. | | `SCORE_DATA_TYPE_CATEGORICAL` | 1 | Canonical | A value chosen from a named set of categories. | | `SCORE_DATA_TYPE_BOOLEAN` | 2 | Canonical | A true-or-false evaluation result. | | `SCORE_DATA_TYPE_TEXT` | 3 | Canonical | Free-form text supplied by an evaluator or reviewer. The provider supports text values on score definitions and scores; support through this API depends on the operation. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_DATA_TYPE_NUMERIC`, `SCORE_DATA_TYPE_CATEGORICAL`, `SCORE_DATA_TYPE_BOOLEAN`, `SCORE_DATA_TYPE_TEXT` Variant 2: Type: `integer(int32)` **numericValue** `any` Numeric score value reported by the evaluator. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stringValue** `string` Category label recorded for a categorical evaluation score. **booleanValue** `boolean` Boolean value recorded for a Boolean evaluation score. **source** `any` Source classification reported for the evaluation score. Platform classification of who produced an evaluation score. The provider source label retains its original vocabulary: writes accept API or ANNOTATION, while EVAL is reserved for the provider's internal evaluators and is rejected through its public API. SCORE\_SOURCE\_HUMAN maps to ANNOTATION. SCORE\_SOURCE\_USER, SCORE\_SOURCE\_JUDGE and SCORE\_SOURCE\_HARNESS map to API. Reviewer and end-user scores also use separate name namespaces: reviewer scores do not use names beginning with user-feedback-.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_SOURCE_JUDGE` | 0 | Canonical | A score produced by an automated judge. | | `SCORE_SOURCE_HUMAN` | 1 | Canonical | A score entered by a human reviewer through the annotation path. | | `SCORE_SOURCE_USER` | 2 | Canonical | Feedback supplied by an end user. | | `SCORE_SOURCE_HARNESS` | 3 | Canonical | A score written by an evaluation harness or another API-based producer. | | `SCORE_SOURCE_EVAL` | 4 | Canonical | A read-only score produced by the evaluation provider's managed evaluators; it cannot be written through the public score API. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_SOURCE_JUDGE`, `SCORE_SOURCE_HUMAN`, `SCORE_SOURCE_USER`, `SCORE_SOURCE_HARNESS`, `SCORE_SOURCE_EVAL` Variant 2: Type: `integer(int32)` **comment** `string` Explanatory text attached to the evaluation score. **createdAt** `string(date-time)` Time when this record was created. **textValue** `string` Text value of the evaluation score. **authorUserId** `string` Identifier recorded for the user who authored the score. A stored author identifier alone does not attest to verified human provenance. **configId** `string` Identifier of the score configuration defining the score’s value domain. **queueId** `string` Identifier of the annotation queue. **traceId** `string` Identifier of the evaluation trace. **observationId** `string` Identifier of the evaluation observation. **sessionId** `string` Identifier of the evaluation session grouping related traces. **datasetRunId** `string` Identifier of the dataset run associated with the score. **environment** `string` Environment label attached to the evaluation record. **metadataJson** `string` Additional attributes serialized as a JSON object. **updatedAt** `string(date-time)` Time when this record was last updated. **timestamp** `string(date-time)` Timestamp associated with the evaluation score. **traceName** `string` Trace name included with the score for display in score listings. **userId** `string` User identifier recorded with the evaluation score. **sourceLabel** `string` Original evaluation-provider source label, such as API, ANNOTATION or EVAL. Interpret it alongside source and authorship: API alone does not distinguish an end-user rating from a harness, and a source label does not independently prove verified human provenance. **conversationId** `string` Conversation identifier recorded in the score’s own metadata. Scores authored directly in the evaluation store can lack platform attribution; an empty link is not repaired by retrying. **messageId** `string` Identifier of the conversation message associated with the evaluation record. **messageSequence** `string(int64)` Sequence number of the evaluated message within its conversation. Pattern: ^-?\d+$ **profileId** `string` Identifier of the agent profile associated with the generation. **configHash** `string` Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation results. Other settings are excluded; this is not an immutable profile revision. #### evals-getOverview-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "overview": { "totalTraces": "1", "tracesByName": [ { "name": "example", "count": "1" } ], "tracesOverTime": [ { "value": 1, "series": "example" } ], "observationsByLevel": [ { "value": 1, "series": "example" } ], "scores": [ { "name": "example", "source": "SCORE_SOURCE_JUDGE", "count": "1", "average": 1 } ], "scoreMovingAverage": [ { "value": 1, "series": "example" } ], "scoredTraceRatio": 1, "annotatedTraceCount": "1", "byProfile": [ { "profileId": "example_123", "traceCount": "1", "avgEndUserRating": 1, "avgJudgeScore": 1, "thumbsDownCount": "1" } ], "latencyPercentiles": [ { "traceName": "example", "p50": 1, "p90": 1, "p95": 1, "p99": 1 } ], "recentLowScores": [ { "scoreId": "example_123", "targetType": "EVAL_TARGET_TYPE_TRACE", "targetId": "example_123", "name": "example", "dataType": "SCORE_DATA_TYPE_NUMERIC", "numericValue": 1, "stringValue": "example", "booleanValue": true, "source": "SCORE_SOURCE_JUDGE", "comment": "example", "textValue": "Example text", "authorUserId": "example_123", "configId": "example_123", "queueId": "example_123", "traceId": "example_123", "observationId": "example_123", "sessionId": "example_123", "datasetRunId": "example_123", "environment": "example", "metadataJson": "{}", "traceName": "example", "userId": "example_123", "sourceLabel": "example", "conversationId": "example_123", "messageId": "example_123", "messageSequence": "1", "profileId": "example_123", "configHash": "example" } ] } } ``` Document ID: `DOC-IS-evaluation-api-getOverview`. [Section identities and revisions](/documentation-manifest.json). - Get the eval overview: `DOC-IS-evaluation-api-getOverview#overview` - Request: `DOC-IS-evaluation-api-getOverview#request` - Responses: `DOC-IS-evaluation-api-getOverview#responses` --- # Get a session URL: https://docs.travila.ai/api/evals/get-session **POST** `/api/v1/evals/get-session` Fetch one session and the traces belonging to it. ### Session summaries Session summaries can include activity outside the list window, and a session can repeat at cursor boundaries. Deduplicate by session ID when collecting pages. Missing rollup data reported as zero is not proof that the session used no resources. Keep those limits with your diagnosis. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Find out why a customer’s reply was slow](/insights/evaluation/reading) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for retrieving an evaluation session and its associated traces. **sessionId** `string` **required** Identifier of the evaluation session grouping related traces. Minimum length: 1 #### evals-getSession-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "sessionId": "example_123" } ``` ## Responses ### 200 — OK Content type: `application/json` Result of retrieving an evaluation session and its associated traces. **session** `any` Evaluation session details returned by the lookup. All of: Variant 1: Evaluation session summary together with the traces belonging to the session. Model reference: [SessionDetail](/api/models/schema-ph83s78vr5#response). **summary** `any` Summary information for the evaluation session. All of: Variant 1: Aggregated trace, usage, and score information for an evaluation session. Model reference: [SessionSummary](/api/models/schema-pbibjr8tih#response). **sessionId** `string` Identifier of the evaluation session grouping related traces. **createdAt** `string(date-time)` Time when this record was created. **durationSeconds** `any` Elapsed session duration, in seconds. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **environment** `string` Environment label attached to the evaluation record. **userIds** `array[string]` User identifiers recorded for this evaluation session. Type: `string` **traceCount** `string(int64)` Number of traces represented by this session summary. Pattern: ^-?\d+$ **totalCost** `any` Total cost reported for the evaluated generation or aggregate. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **inputTokens** `string(int64)` Input-token usage reported for the evaluated generation. Pattern: ^-?\d+$ **outputTokens** `string(int64)` Output-token usage reported for the evaluated generation. Pattern: ^-?\d+$ **totalTokens** `string(int64)` Total token usage reported for the evaluated generation or aggregate. Pattern: ^-?\d+$ **traceTags** `array[string]` Labels collected from the session’s evaluation traces. Type: `string` **scores** `array[llm_v1_services_eval_v1_Score]` Evaluation scores returned for the selected objects or query. Evaluation score with its value, source, target identity, and generation attribution. Model reference: [Score](/api/models/schema-1jm5lo00e7#response). **scoreId** `string` Identifier of the evaluation score. **targetType** `any` Kind of evaluation object to which the score applies. Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_TARGET_TYPE_TRACE` | 0 | Canonical | A complete trace identified by its trace identifier. | | `EVAL_TARGET_TYPE_OBSERVATION` | 1 | Canonical | A specific observation within a trace. | | `EVAL_TARGET_TYPE_DATASET_RUN` | 2 | Canonical | An evaluation run over a dataset. | | `EVAL_TARGET_TYPE_SESSION` | 3 | Canonical | A session grouping multiple traces. The evaluation harness attaches session-scoped judge scores directly; the provider does not expose a session-level evaluator target. |
Exactly one of: Variant 1: Type: `string` Enum: `EVAL_TARGET_TYPE_TRACE`, `EVAL_TARGET_TYPE_OBSERVATION`, `EVAL_TARGET_TYPE_DATASET_RUN`, `EVAL_TARGET_TYPE_SESSION` Variant 2: Type: `integer(int32)` **targetId** `string` Identifier of the evaluation object to which the score applies. **name** `string` Metric name identifying the recorded evaluation score. **dataType** `any` Value type used to interpret numeric, categorical, Boolean, or text score values. Scores Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_DATA_TYPE_NUMERIC` | 0 | Canonical | A numeric measurement or rating. | | `SCORE_DATA_TYPE_CATEGORICAL` | 1 | Canonical | A value chosen from a named set of categories. | | `SCORE_DATA_TYPE_BOOLEAN` | 2 | Canonical | A true-or-false evaluation result. | | `SCORE_DATA_TYPE_TEXT` | 3 | Canonical | Free-form text supplied by an evaluator or reviewer. The provider supports text values on score definitions and scores; support through this API depends on the operation. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_DATA_TYPE_NUMERIC`, `SCORE_DATA_TYPE_CATEGORICAL`, `SCORE_DATA_TYPE_BOOLEAN`, `SCORE_DATA_TYPE_TEXT` Variant 2: Type: `integer(int32)` **numericValue** `any` Numeric score value reported by the evaluator. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stringValue** `string` Category label recorded for a categorical evaluation score. **booleanValue** `boolean` Boolean value recorded for a Boolean evaluation score. **source** `any` Source classification reported for the evaluation score. Platform classification of who produced an evaluation score. The provider source label retains its original vocabulary: writes accept API or ANNOTATION, while EVAL is reserved for the provider's internal evaluators and is rejected through its public API. SCORE\_SOURCE\_HUMAN maps to ANNOTATION. SCORE\_SOURCE\_USER, SCORE\_SOURCE\_JUDGE and SCORE\_SOURCE\_HARNESS map to API. Reviewer and end-user scores also use separate name namespaces: reviewer scores do not use names beginning with user-feedback-.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_SOURCE_JUDGE` | 0 | Canonical | A score produced by an automated judge. | | `SCORE_SOURCE_HUMAN` | 1 | Canonical | A score entered by a human reviewer through the annotation path. | | `SCORE_SOURCE_USER` | 2 | Canonical | Feedback supplied by an end user. | | `SCORE_SOURCE_HARNESS` | 3 | Canonical | A score written by an evaluation harness or another API-based producer. | | `SCORE_SOURCE_EVAL` | 4 | Canonical | A read-only score produced by the evaluation provider's managed evaluators; it cannot be written through the public score API. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_SOURCE_JUDGE`, `SCORE_SOURCE_HUMAN`, `SCORE_SOURCE_USER`, `SCORE_SOURCE_HARNESS`, `SCORE_SOURCE_EVAL` Variant 2: Type: `integer(int32)` **comment** `string` Explanatory text attached to the evaluation score. **createdAt** `string(date-time)` Time when this record was created. **textValue** `string` Text value of the evaluation score. **authorUserId** `string` Identifier recorded for the user who authored the score. A stored author identifier alone does not attest to verified human provenance. **configId** `string` Identifier of the score configuration defining the score’s value domain. **queueId** `string` Identifier of the annotation queue. **traceId** `string` Identifier of the evaluation trace. **observationId** `string` Identifier of the evaluation observation. **sessionId** `string` Identifier of the evaluation session grouping related traces. **datasetRunId** `string` Identifier of the dataset run associated with the score. **environment** `string` Environment label attached to the evaluation record. **metadataJson** `string` Additional attributes serialized as a JSON object. **updatedAt** `string(date-time)` Time when this record was last updated. **timestamp** `string(date-time)` Timestamp associated with the evaluation score. **traceName** `string` Trace name included with the score for display in score listings. **userId** `string` User identifier recorded with the evaluation score. **sourceLabel** `string` Original evaluation-provider source label, such as API, ANNOTATION or EVAL. Interpret it alongside source and authorship: API alone does not distinguish an end-user rating from a harness, and a source label does not independently prove verified human provenance. **conversationId** `string` Conversation identifier recorded in the score’s own metadata. Scores authored directly in the evaluation store can lack platform attribution; an empty link is not repaired by retrying. **messageId** `string` Identifier of the conversation message associated with the evaluation record. **messageSequence** `string(int64)` Sequence number of the evaluated message within its conversation. Pattern: ^-?\d+$ **profileId** `string` Identifier of the agent profile associated with the generation. **configHash** `string` Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation results. Other settings are excluded; this is not an immutable profile revision. **commentCount** `string(int64)` Number of comments reported on the evaluation object. Pattern: ^-?\d+$ **metadataJson** `string` Additional attributes serialized as a JSON object. **bookmarked** `boolean` Whether the evaluation object is bookmarked. **conversationIds** `array[string]` Conversation identifiers observed on the session’s traces; a session may span multiple conversations. Type: `string` **traces** `array[llm_v1_services_eval_v1_TraceSummary]` Evaluation traces returned by the query. Evaluation summary for a conversation turn, including its recorded conversation, message and profile attribution. Model reference: [TraceSummary](/api/models/schema-1k4mjul65u#response). **traceId** `string` Identifier of the evaluation trace. **name** `string` Name recorded for the evaluation trace. **timestamp** `string(date-time)` Timestamp associated with the evaluation trace. **inputJson** `string` Evaluation input serialized as JSON. **outputJson** `string` Evaluation output serialized as JSON. **latencySeconds** `any` Elapsed observation latency, in seconds. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **totalCost** `any` Total cost reported for the evaluated generation or aggregate. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **environment** `string` Environment label attached to the evaluation record. **tags** `array[string]` Labels associated with the resource for organization or filtering. Type: `string` **metadataJson** `string` Additional attributes serialized as a JSON object. **bookmarked** `boolean` Whether the evaluation object is bookmarked. **version** `string` Version of the resource represented by this message. **release** `string` Application release identifier attached to the trace. **userId** `string` Identifier of the user associated with the operation. **sessionId** `string` Identifier of the evaluation session grouping related traces. **observationCount** `string(int64)` Number of observations reported for the evaluation object. Pattern: ^-?\d+$ **conversationId** `string` Identifier of the conversation associated with the trace. **sourceUserMessageId** `string` Identifier of the user message that opened the evaluated generation turn. **profileId** `string` Identifier of the agent profile associated with the generation. **configHash** `string` Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation results. Other settings are excluded; this is not an immutable profile revision. **inputTokens** `string(int64)` Input-token usage reported for the evaluated generation. Pattern: ^-?\d+$ **outputTokens** `string(int64)` Output-token usage reported for the evaluated generation. Pattern: ^-?\d+$ **totalTokens** `string(int64)` Total token usage reported for the evaluated generation or aggregate. Pattern: ^-?\d+$ **errorCount** `string(int64)` Number of observations reported at error level. Pattern: ^-?\d+$ **warningCount** `string(int64)` Number of observations reported at warning level. Pattern: ^-?\d+$ **defaultCount** `string(int64)` Number of observations reported at the default level. Pattern: ^-?\d+$ **debugCount** `string(int64)` Number of observations reported at debug level. Pattern: ^-?\d+$ **scores** `array[llm_v1_services_eval_v1_Score]` Evaluation scores returned for the selected objects or query. Evaluation score with its value, source, target identity, and generation attribution. Model reference: [Score](/api/models/schema-1jm5lo00e7#response). **scoreId** `string` Identifier of the evaluation score. **targetType** `any` Kind of evaluation object to which the score applies. Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_TARGET_TYPE_TRACE` | 0 | Canonical | A complete trace identified by its trace identifier. | | `EVAL_TARGET_TYPE_OBSERVATION` | 1 | Canonical | A specific observation within a trace. | | `EVAL_TARGET_TYPE_DATASET_RUN` | 2 | Canonical | An evaluation run over a dataset. | | `EVAL_TARGET_TYPE_SESSION` | 3 | Canonical | A session grouping multiple traces. The evaluation harness attaches session-scoped judge scores directly; the provider does not expose a session-level evaluator target. |
Exactly one of: Variant 1: Type: `string` Enum: `EVAL_TARGET_TYPE_TRACE`, `EVAL_TARGET_TYPE_OBSERVATION`, `EVAL_TARGET_TYPE_DATASET_RUN`, `EVAL_TARGET_TYPE_SESSION` Variant 2: Type: `integer(int32)` **targetId** `string` Identifier of the evaluation object to which the score applies. **name** `string` Metric name identifying the recorded evaluation score. **dataType** `any` Value type used to interpret numeric, categorical, Boolean, or text score values. Scores Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_DATA_TYPE_NUMERIC` | 0 | Canonical | A numeric measurement or rating. | | `SCORE_DATA_TYPE_CATEGORICAL` | 1 | Canonical | A value chosen from a named set of categories. | | `SCORE_DATA_TYPE_BOOLEAN` | 2 | Canonical | A true-or-false evaluation result. | | `SCORE_DATA_TYPE_TEXT` | 3 | Canonical | Free-form text supplied by an evaluator or reviewer. The provider supports text values on score definitions and scores; support through this API depends on the operation. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_DATA_TYPE_NUMERIC`, `SCORE_DATA_TYPE_CATEGORICAL`, `SCORE_DATA_TYPE_BOOLEAN`, `SCORE_DATA_TYPE_TEXT` Variant 2: Type: `integer(int32)` **numericValue** `any` Numeric score value reported by the evaluator. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stringValue** `string` Category label recorded for a categorical evaluation score. **booleanValue** `boolean` Boolean value recorded for a Boolean evaluation score. **source** `any` Source classification reported for the evaluation score. Platform classification of who produced an evaluation score. The provider source label retains its original vocabulary: writes accept API or ANNOTATION, while EVAL is reserved for the provider's internal evaluators and is rejected through its public API. SCORE\_SOURCE\_HUMAN maps to ANNOTATION. SCORE\_SOURCE\_USER, SCORE\_SOURCE\_JUDGE and SCORE\_SOURCE\_HARNESS map to API. Reviewer and end-user scores also use separate name namespaces: reviewer scores do not use names beginning with user-feedback-.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_SOURCE_JUDGE` | 0 | Canonical | A score produced by an automated judge. | | `SCORE_SOURCE_HUMAN` | 1 | Canonical | A score entered by a human reviewer through the annotation path. | | `SCORE_SOURCE_USER` | 2 | Canonical | Feedback supplied by an end user. | | `SCORE_SOURCE_HARNESS` | 3 | Canonical | A score written by an evaluation harness or another API-based producer. | | `SCORE_SOURCE_EVAL` | 4 | Canonical | A read-only score produced by the evaluation provider's managed evaluators; it cannot be written through the public score API. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_SOURCE_JUDGE`, `SCORE_SOURCE_HUMAN`, `SCORE_SOURCE_USER`, `SCORE_SOURCE_HARNESS`, `SCORE_SOURCE_EVAL` Variant 2: Type: `integer(int32)` **comment** `string` Explanatory text attached to the evaluation score. **createdAt** `string(date-time)` Time when this record was created. **textValue** `string` Text value of the evaluation score. **authorUserId** `string` Identifier recorded for the user who authored the score. A stored author identifier alone does not attest to verified human provenance. **configId** `string` Identifier of the score configuration defining the score’s value domain. **queueId** `string` Identifier of the annotation queue. **traceId** `string` Identifier of the evaluation trace. **observationId** `string` Identifier of the evaluation observation. **sessionId** `string` Identifier of the evaluation session grouping related traces. **datasetRunId** `string` Identifier of the dataset run associated with the score. **environment** `string` Environment label attached to the evaluation record. **metadataJson** `string` Additional attributes serialized as a JSON object. **updatedAt** `string(date-time)` Time when this record was last updated. **timestamp** `string(date-time)` Timestamp associated with the evaluation score. **traceName** `string` Trace name included with the score for display in score listings. **userId** `string` User identifier recorded with the evaluation score. **sourceLabel** `string` Original evaluation-provider source label, such as API, ANNOTATION or EVAL. Interpret it alongside source and authorship: API alone does not distinguish an end-user rating from a harness, and a source label does not independently prove verified human provenance. **conversationId** `string` Conversation identifier recorded in the score’s own metadata. Scores authored directly in the evaluation store can lack platform attribution; an empty link is not repaired by retrying. **messageId** `string` Identifier of the conversation message associated with the evaluation record. **messageSequence** `string(int64)` Sequence number of the evaluated message within its conversation. Pattern: ^-?\d+$ **profileId** `string` Identifier of the agent profile associated with the generation. **configHash** `string` Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation results. Other settings are excluded; this is not an immutable profile revision. **commentCount** `string(int64)` Number of comments reported on the evaluation object. Pattern: ^-?\d+$ **contentRedacted** `boolean` Whether sensitive evaluation content has been removed from the returned view. #### evals-getSession-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "session": { "summary": { "sessionId": "example_123", "durationSeconds": 1, "environment": "example", "userIds": [ "example_123" ], "traceCount": 1, "totalCost": 1, "inputTokens": "1", "outputTokens": "1", "totalTokens": "1", "traceTags": [ "example" ], "commentCount": 1, "metadataJson": "{}", "bookmarked": true, "conversationIds": [ "example_123" ] }, "traces": [ { "traceId": "example_123", "name": "example", "inputJson": "{}", "outputJson": "{}", "latencySeconds": 1, "totalCost": 1, "environment": "example", "tags": [ "example" ], "metadataJson": "{}", "bookmarked": true, "version": "example", "release": "example", "userId": "example_123", "sessionId": "example_123", "observationCount": 1, "conversationId": "example_123", "sourceUserMessageId": "example_123", "profileId": "example_123", "configHash": "example", "inputTokens": "1", "outputTokens": "1", "totalTokens": "1", "errorCount": 1, "warningCount": 1, "defaultCount": 1, "debugCount": 1, "commentCount": 1 } ] }, "contentRedacted": true } ``` Document ID: `DOC-IS-evaluation-api-getSession`. [Section identities and revisions](/documentation-manifest.json). - Get a session: `DOC-IS-evaluation-api-getSession#overview` - Request: `DOC-IS-evaluation-api-getSession#request` - Responses: `DOC-IS-evaluation-api-getSession#responses` --- # Get a trace URL: https://docs.travila.ai/api/evals/get-trace **POST** `/api/v1/evals/get-trace` Fetch one trace with its observations expanded. When addressing a turn, `conversationId` accepts a bare thread id and is qualified with your verified tenant. The assistant message or rating event carries the source user-message identity needed to find that turn. Observation/score expansion is capped at 20 upstream pages of 100 without a partial-result flag; large detail responses do not establish a complete evaluation cohort. If the expected step is missing, continue with [observation search](/insights/evaluation/reading#observations-across-traces) rather than claiming the turn ended there. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Find out why a customer’s reply was slow](/insights/evaluation/reading) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for retrieving an evaluation trace with its recorded generation details. Supply exactly one address: trace\_id, or both conversation\_id and source\_user\_message\_id. **traceId** `string` Identifier of the evaluation trace. **conversationId** `string` Identifier of the conversation associated with the evaluation record. Maximum length: 256 **sourceUserMessageId** `string` Identifier of the user message that started the evaluated turn, not the assistant reply's message identifier. Supply it together with conversation\_id when addressing by turn. Maximum length: 256 #### evals-getTrace-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "traceId": "trace_123" } ``` #### cookbook-insights-evaluation-reading-02-request Guide request for Locate the slow or failed step. Replace example resource identifiers with your own authorized values. ```json { "conversationId": "conv_123", "sourceUserMessageId": "msg_abc" } ``` ## Responses ### 200 — OK Content type: `application/json` Result of retrieving an evaluation trace with its recorded generation details. **trace** `any` Evaluation trace details returned by the lookup. All of: Variant 1: Evaluation trace summary together with its observations and attached scores. Model reference: [TraceDetail](/api/models/schema-pha7gtif3l#response). **summary** `any` Summary information for the evaluation trace. All of: Variant 1: Evaluation summary for a conversation turn, including its recorded conversation, message and profile attribution. Model reference: [TraceSummary](/api/models/schema-1k4mjul65u#response). **traceId** `string` Identifier of the evaluation trace. **name** `string` Name recorded for the evaluation trace. **timestamp** `string(date-time)` Timestamp associated with the evaluation trace. **inputJson** `string` Evaluation input serialized as JSON. **outputJson** `string` Evaluation output serialized as JSON. **latencySeconds** `any` Elapsed observation latency, in seconds. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **totalCost** `any` Total cost reported for the evaluated generation or aggregate. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **environment** `string` Environment label attached to the evaluation record. **tags** `array[string]` Labels associated with the resource for organization or filtering. Type: `string` **metadataJson** `string` Additional attributes serialized as a JSON object. **bookmarked** `boolean` Whether the evaluation object is bookmarked. **version** `string` Version of the resource represented by this message. **release** `string` Application release identifier attached to the trace. **userId** `string` Identifier of the user associated with the operation. **sessionId** `string` Identifier of the evaluation session grouping related traces. **observationCount** `string(int64)` Number of observations reported for the evaluation object. Pattern: ^-?\d+$ **conversationId** `string` Identifier of the conversation associated with the trace. **sourceUserMessageId** `string` Identifier of the user message that opened the evaluated generation turn. **profileId** `string` Identifier of the agent profile associated with the generation. **configHash** `string` Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation results. Other settings are excluded; this is not an immutable profile revision. **inputTokens** `string(int64)` Input-token usage reported for the evaluated generation. Pattern: ^-?\d+$ **outputTokens** `string(int64)` Output-token usage reported for the evaluated generation. Pattern: ^-?\d+$ **totalTokens** `string(int64)` Total token usage reported for the evaluated generation or aggregate. Pattern: ^-?\d+$ **errorCount** `string(int64)` Number of observations reported at error level. Pattern: ^-?\d+$ **warningCount** `string(int64)` Number of observations reported at warning level. Pattern: ^-?\d+$ **defaultCount** `string(int64)` Number of observations reported at the default level. Pattern: ^-?\d+$ **debugCount** `string(int64)` Number of observations reported at debug level. Pattern: ^-?\d+$ **scores** `array[llm_v1_services_eval_v1_Score]` Evaluation scores returned for the selected objects or query. Evaluation score with its value, source, target identity, and generation attribution. Model reference: [Score](/api/models/schema-1jm5lo00e7#response). **scoreId** `string` Identifier of the evaluation score. **targetType** `any` Kind of evaluation object to which the score applies. Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_TARGET_TYPE_TRACE` | 0 | Canonical | A complete trace identified by its trace identifier. | | `EVAL_TARGET_TYPE_OBSERVATION` | 1 | Canonical | A specific observation within a trace. | | `EVAL_TARGET_TYPE_DATASET_RUN` | 2 | Canonical | An evaluation run over a dataset. | | `EVAL_TARGET_TYPE_SESSION` | 3 | Canonical | A session grouping multiple traces. The evaluation harness attaches session-scoped judge scores directly; the provider does not expose a session-level evaluator target. |
Exactly one of: Variant 1: Type: `string` Enum: `EVAL_TARGET_TYPE_TRACE`, `EVAL_TARGET_TYPE_OBSERVATION`, `EVAL_TARGET_TYPE_DATASET_RUN`, `EVAL_TARGET_TYPE_SESSION` Variant 2: Type: `integer(int32)` **targetId** `string` Identifier of the evaluation object to which the score applies. **name** `string` Metric name identifying the recorded evaluation score. **dataType** `any` Value type used to interpret numeric, categorical, Boolean, or text score values. Scores Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_DATA_TYPE_NUMERIC` | 0 | Canonical | A numeric measurement or rating. | | `SCORE_DATA_TYPE_CATEGORICAL` | 1 | Canonical | A value chosen from a named set of categories. | | `SCORE_DATA_TYPE_BOOLEAN` | 2 | Canonical | A true-or-false evaluation result. | | `SCORE_DATA_TYPE_TEXT` | 3 | Canonical | Free-form text supplied by an evaluator or reviewer. The provider supports text values on score definitions and scores; support through this API depends on the operation. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_DATA_TYPE_NUMERIC`, `SCORE_DATA_TYPE_CATEGORICAL`, `SCORE_DATA_TYPE_BOOLEAN`, `SCORE_DATA_TYPE_TEXT` Variant 2: Type: `integer(int32)` **numericValue** `any` Numeric score value reported by the evaluator. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stringValue** `string` Category label recorded for a categorical evaluation score. **booleanValue** `boolean` Boolean value recorded for a Boolean evaluation score. **source** `any` Source classification reported for the evaluation score. Platform classification of who produced an evaluation score. The provider source label retains its original vocabulary: writes accept API or ANNOTATION, while EVAL is reserved for the provider's internal evaluators and is rejected through its public API. SCORE\_SOURCE\_HUMAN maps to ANNOTATION. SCORE\_SOURCE\_USER, SCORE\_SOURCE\_JUDGE and SCORE\_SOURCE\_HARNESS map to API. Reviewer and end-user scores also use separate name namespaces: reviewer scores do not use names beginning with user-feedback-.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_SOURCE_JUDGE` | 0 | Canonical | A score produced by an automated judge. | | `SCORE_SOURCE_HUMAN` | 1 | Canonical | A score entered by a human reviewer through the annotation path. | | `SCORE_SOURCE_USER` | 2 | Canonical | Feedback supplied by an end user. | | `SCORE_SOURCE_HARNESS` | 3 | Canonical | A score written by an evaluation harness or another API-based producer. | | `SCORE_SOURCE_EVAL` | 4 | Canonical | A read-only score produced by the evaluation provider's managed evaluators; it cannot be written through the public score API. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_SOURCE_JUDGE`, `SCORE_SOURCE_HUMAN`, `SCORE_SOURCE_USER`, `SCORE_SOURCE_HARNESS`, `SCORE_SOURCE_EVAL` Variant 2: Type: `integer(int32)` **comment** `string` Explanatory text attached to the evaluation score. **createdAt** `string(date-time)` Time when this record was created. **textValue** `string` Text value of the evaluation score. **authorUserId** `string` Identifier recorded for the user who authored the score. A stored author identifier alone does not attest to verified human provenance. **configId** `string` Identifier of the score configuration defining the score’s value domain. **queueId** `string` Identifier of the annotation queue. **traceId** `string` Identifier of the evaluation trace. **observationId** `string` Identifier of the evaluation observation. **sessionId** `string` Identifier of the evaluation session grouping related traces. **datasetRunId** `string` Identifier of the dataset run associated with the score. **environment** `string` Environment label attached to the evaluation record. **metadataJson** `string` Additional attributes serialized as a JSON object. **updatedAt** `string(date-time)` Time when this record was last updated. **timestamp** `string(date-time)` Timestamp associated with the evaluation score. **traceName** `string` Trace name included with the score for display in score listings. **userId** `string` User identifier recorded with the evaluation score. **sourceLabel** `string` Original evaluation-provider source label, such as API, ANNOTATION or EVAL. Interpret it alongside source and authorship: API alone does not distinguish an end-user rating from a harness, and a source label does not independently prove verified human provenance. **conversationId** `string` Conversation identifier recorded in the score’s own metadata. Scores authored directly in the evaluation store can lack platform attribution; an empty link is not repaired by retrying. **messageId** `string` Identifier of the conversation message associated with the evaluation record. **messageSequence** `string(int64)` Sequence number of the evaluated message within its conversation. Pattern: ^-?\d+$ **profileId** `string` Identifier of the agent profile associated with the generation. **configHash** `string` Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation results. Other settings are excluded; this is not an immutable profile revision. **commentCount** `string(int64)` Number of comments reported on the evaluation object. Pattern: ^-?\d+$ **observations** `array[llm_v1_services_eval_v1_Observation]` Observations associated with the evaluation trace. Timed evaluation span or generation record with model usage, inputs, outputs, and scores. A generation observation originates the profile and configuration attribution promoted to its trace; callers can read those links directly on either record. Model reference: [Observation](/api/models/schema-1ju9tclufp#response). **observationId** `string` Identifier of the evaluation observation. **traceId** `string` Identifier of the evaluation trace. **parentObservationId** `string` Identifier of the parent observation within the trace. **type** `any` Observation kind reported by the evaluation provider. Semantic category of a trace observation, including categories accepted from upstream even when the platform does not emit them. Current emitters produce GENERATION, TOOL, RETRIEVER and SPAN; the other declared categories can still describe upstream observations.
| Value | No. | Form | Meaning | |---|---|---|---| | `OBSERVATION_TYPE_SPAN` | 0 | Canonical | A timed unit of work represented as a span. | | `OBSERVATION_TYPE_GENERATION` | 1 | Canonical | A model-generation operation and its recorded inputs, outputs and usage. | | `OBSERVATION_TYPE_EVENT` | 2 | Canonical | A point-in-time event rather than a timed operation. | | `OBSERVATION_TYPE_TOOL` | 3 | Canonical | Execution of a tool call. | | `OBSERVATION_TYPE_RETRIEVER` | 4 | Canonical | Retrieval of supporting documents or other context. | | `OBSERVATION_TYPE_AGENT` | 5 | Canonical | An agent-level operation reported in the trace. | | `OBSERVATION_TYPE_CHAIN` | 6 | Canonical | A sequence or chain of related processing steps. | | `OBSERVATION_TYPE_EMBEDDING` | 7 | Canonical | Computation of vector embeddings. | | `OBSERVATION_TYPE_EVALUATOR` | 8 | Canonical | An evaluator operation that assesses another result. | | `OBSERVATION_TYPE_GUARDRAIL` | 9 | Canonical | A guardrail check on inputs, outputs or processing. |
Exactly one of: Variant 1: Type: `string` Enum: `OBSERVATION_TYPE_SPAN`, `OBSERVATION_TYPE_GENERATION`, `OBSERVATION_TYPE_EVENT`, `OBSERVATION_TYPE_TOOL`, `OBSERVATION_TYPE_RETRIEVER`, `OBSERVATION_TYPE_AGENT`, `OBSERVATION_TYPE_CHAIN`, `OBSERVATION_TYPE_EMBEDDING`, `OBSERVATION_TYPE_EVALUATOR`, `OBSERVATION_TYPE_GUARDRAIL` Variant 2: Type: `integer(int32)` **name** `string` Operation name recorded for the evaluation observation. **level** `any` Observation log level reported by the evaluation provider. Diagnostic severity attached to an evaluation observation.
| Value | No. | Form | Meaning | |---|---|---|---| | `OBSERVATION_LEVEL_DEBUG` | 0 | Canonical | Detailed diagnostic information intended for debugging. | | `OBSERVATION_LEVEL_DEFAULT` | 1 | Canonical | Ordinary observation information without an elevated warning or error level. | | `OBSERVATION_LEVEL_WARNING` | 2 | Canonical | A condition reported at warning severity. | | `OBSERVATION_LEVEL_ERROR` | 3 | Canonical | A condition reported at error severity. |
Exactly one of: Variant 1: Type: `string` Enum: `OBSERVATION_LEVEL_DEBUG`, `OBSERVATION_LEVEL_DEFAULT`, `OBSERVATION_LEVEL_WARNING`, `OBSERVATION_LEVEL_ERROR` Variant 2: Type: `integer(int32)` **statusMessage** `string` Diagnostic text explaining the reported state. **startTime** `string(date-time)` Beginning of the time interval represented by this operation. **endTime** `string(date-time)` End of the time interval represented by this operation. **completionStartTime** `string(date-time)` Time to first token, generations only. **latencySeconds** `any` Elapsed observation latency, in seconds. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **inputJson** `string` Evaluation input serialized as JSON. **outputJson** `string` Evaluation output serialized as JSON. **metadataJson** `string` Additional attributes serialized as a JSON object. **model** `string` Model identifier recorded for the evaluated generation. **modelParametersJson** `string` Model parameters recorded as a serialized JSON object. **inputTokens** `string(int64)` Input-token usage reported for the evaluated generation. Pattern: ^-?\d+$ **outputTokens** `string(int64)` Output-token usage reported for the evaluated generation. Pattern: ^-?\d+$ **totalTokens** `string(int64)` Total token usage reported for the evaluated generation or aggregate. Pattern: ^-?\d+$ **inputCost** `any` Cost attributed to model input by the evaluation provider. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **outputCost** `any` Cost attributed to model output by the evaluation provider. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **totalCost** `any` Total cost reported for the evaluated generation or aggregate. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **environment** `string` Environment label attached to the evaluation record. **version** `string` Version of the resource represented by this message. **promptName** `string` Name of the versioned prompt associated with the generation. **promptVersion** `string(int64)` Version of the prompt associated with the generation. Pattern: ^-?\d+$ **scores** `array[llm_v1_services_eval_v1_Score]` Evaluation scores returned for the selected objects or query. Evaluation score with its value, source, target identity, and generation attribution. Model reference: [Score](/api/models/schema-1jm5lo00e7#response). **scoreId** `string` Identifier of the evaluation score. **targetType** `any` Kind of evaluation object to which the score applies. Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_TARGET_TYPE_TRACE` | 0 | Canonical | A complete trace identified by its trace identifier. | | `EVAL_TARGET_TYPE_OBSERVATION` | 1 | Canonical | A specific observation within a trace. | | `EVAL_TARGET_TYPE_DATASET_RUN` | 2 | Canonical | An evaluation run over a dataset. | | `EVAL_TARGET_TYPE_SESSION` | 3 | Canonical | A session grouping multiple traces. The evaluation harness attaches session-scoped judge scores directly; the provider does not expose a session-level evaluator target. |
Exactly one of: Variant 1: Type: `string` Enum: `EVAL_TARGET_TYPE_TRACE`, `EVAL_TARGET_TYPE_OBSERVATION`, `EVAL_TARGET_TYPE_DATASET_RUN`, `EVAL_TARGET_TYPE_SESSION` Variant 2: Type: `integer(int32)` **targetId** `string` Identifier of the evaluation object to which the score applies. **name** `string` Metric name identifying the recorded evaluation score. **dataType** `any` Value type used to interpret numeric, categorical, Boolean, or text score values. Scores Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_DATA_TYPE_NUMERIC` | 0 | Canonical | A numeric measurement or rating. | | `SCORE_DATA_TYPE_CATEGORICAL` | 1 | Canonical | A value chosen from a named set of categories. | | `SCORE_DATA_TYPE_BOOLEAN` | 2 | Canonical | A true-or-false evaluation result. | | `SCORE_DATA_TYPE_TEXT` | 3 | Canonical | Free-form text supplied by an evaluator or reviewer. The provider supports text values on score definitions and scores; support through this API depends on the operation. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_DATA_TYPE_NUMERIC`, `SCORE_DATA_TYPE_CATEGORICAL`, `SCORE_DATA_TYPE_BOOLEAN`, `SCORE_DATA_TYPE_TEXT` Variant 2: Type: `integer(int32)` **numericValue** `any` Numeric score value reported by the evaluator. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stringValue** `string` Category label recorded for a categorical evaluation score. **booleanValue** `boolean` Boolean value recorded for a Boolean evaluation score. **source** `any` Source classification reported for the evaluation score. Platform classification of who produced an evaluation score. The provider source label retains its original vocabulary: writes accept API or ANNOTATION, while EVAL is reserved for the provider's internal evaluators and is rejected through its public API. SCORE\_SOURCE\_HUMAN maps to ANNOTATION. SCORE\_SOURCE\_USER, SCORE\_SOURCE\_JUDGE and SCORE\_SOURCE\_HARNESS map to API. Reviewer and end-user scores also use separate name namespaces: reviewer scores do not use names beginning with user-feedback-.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_SOURCE_JUDGE` | 0 | Canonical | A score produced by an automated judge. | | `SCORE_SOURCE_HUMAN` | 1 | Canonical | A score entered by a human reviewer through the annotation path. | | `SCORE_SOURCE_USER` | 2 | Canonical | Feedback supplied by an end user. | | `SCORE_SOURCE_HARNESS` | 3 | Canonical | A score written by an evaluation harness or another API-based producer. | | `SCORE_SOURCE_EVAL` | 4 | Canonical | A read-only score produced by the evaluation provider's managed evaluators; it cannot be written through the public score API. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_SOURCE_JUDGE`, `SCORE_SOURCE_HUMAN`, `SCORE_SOURCE_USER`, `SCORE_SOURCE_HARNESS`, `SCORE_SOURCE_EVAL` Variant 2: Type: `integer(int32)` **comment** `string` Explanatory text attached to the evaluation score. **createdAt** `string(date-time)` Time when this record was created. **textValue** `string` Text value of the evaluation score. **authorUserId** `string` Identifier recorded for the user who authored the score. A stored author identifier alone does not attest to verified human provenance. **configId** `string` Identifier of the score configuration defining the score’s value domain. **queueId** `string` Identifier of the annotation queue. **traceId** `string` Identifier of the evaluation trace. **observationId** `string` Identifier of the evaluation observation. **sessionId** `string` Identifier of the evaluation session grouping related traces. **datasetRunId** `string` Identifier of the dataset run associated with the score. **environment** `string` Environment label attached to the evaluation record. **metadataJson** `string` Additional attributes serialized as a JSON object. **updatedAt** `string(date-time)` Time when this record was last updated. **timestamp** `string(date-time)` Timestamp associated with the evaluation score. **traceName** `string` Trace name included with the score for display in score listings. **userId** `string` User identifier recorded with the evaluation score. **sourceLabel** `string` Original evaluation-provider source label, such as API, ANNOTATION or EVAL. Interpret it alongside source and authorship: API alone does not distinguish an end-user rating from a harness, and a source label does not independently prove verified human provenance. **conversationId** `string` Conversation identifier recorded in the score’s own metadata. Scores authored directly in the evaluation store can lack platform attribution; an empty link is not repaired by retrying. **messageId** `string` Identifier of the conversation message associated with the evaluation record. **messageSequence** `string(int64)` Sequence number of the evaluated message within its conversation. Pattern: ^-?\d+$ **profileId** `string` Identifier of the agent profile associated with the generation. **configHash** `string` Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation results. Other settings are excluded; this is not an immutable profile revision. **commentCount** `string(int64)` Number of comments reported on the evaluation object. Pattern: ^-?\d+$ **conversationId** `string` Identifier of the conversation associated with this evaluation observation, when recorded. **sourceUserMessageId** `string` Identifier of the user message that opened the evaluated generation turn. **profileId** `string` Identifier of the agent profile associated with the generation. **configHash** `string` Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation results. Other settings are excluded; this is not an immutable profile revision. **scores** `array[llm_v1_services_eval_v1_Score]` Evaluation scores returned for the selected objects or query. Evaluation score with its value, source, target identity, and generation attribution. Model reference: [Score](/api/models/schema-1jm5lo00e7#response). **scoreId** `string` Identifier of the evaluation score. **targetType** `any` Kind of evaluation object to which the score applies. Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_TARGET_TYPE_TRACE` | 0 | Canonical | A complete trace identified by its trace identifier. | | `EVAL_TARGET_TYPE_OBSERVATION` | 1 | Canonical | A specific observation within a trace. | | `EVAL_TARGET_TYPE_DATASET_RUN` | 2 | Canonical | An evaluation run over a dataset. | | `EVAL_TARGET_TYPE_SESSION` | 3 | Canonical | A session grouping multiple traces. The evaluation harness attaches session-scoped judge scores directly; the provider does not expose a session-level evaluator target. |
Exactly one of: Variant 1: Type: `string` Enum: `EVAL_TARGET_TYPE_TRACE`, `EVAL_TARGET_TYPE_OBSERVATION`, `EVAL_TARGET_TYPE_DATASET_RUN`, `EVAL_TARGET_TYPE_SESSION` Variant 2: Type: `integer(int32)` **targetId** `string` Identifier of the evaluation object to which the score applies. **name** `string` Metric name identifying the recorded evaluation score. **dataType** `any` Value type used to interpret numeric, categorical, Boolean, or text score values. Scores Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_DATA_TYPE_NUMERIC` | 0 | Canonical | A numeric measurement or rating. | | `SCORE_DATA_TYPE_CATEGORICAL` | 1 | Canonical | A value chosen from a named set of categories. | | `SCORE_DATA_TYPE_BOOLEAN` | 2 | Canonical | A true-or-false evaluation result. | | `SCORE_DATA_TYPE_TEXT` | 3 | Canonical | Free-form text supplied by an evaluator or reviewer. The provider supports text values on score definitions and scores; support through this API depends on the operation. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_DATA_TYPE_NUMERIC`, `SCORE_DATA_TYPE_CATEGORICAL`, `SCORE_DATA_TYPE_BOOLEAN`, `SCORE_DATA_TYPE_TEXT` Variant 2: Type: `integer(int32)` **numericValue** `any` Numeric score value reported by the evaluator. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stringValue** `string` Category label recorded for a categorical evaluation score. **booleanValue** `boolean` Boolean value recorded for a Boolean evaluation score. **source** `any` Source classification reported for the evaluation score. Platform classification of who produced an evaluation score. The provider source label retains its original vocabulary: writes accept API or ANNOTATION, while EVAL is reserved for the provider's internal evaluators and is rejected through its public API. SCORE\_SOURCE\_HUMAN maps to ANNOTATION. SCORE\_SOURCE\_USER, SCORE\_SOURCE\_JUDGE and SCORE\_SOURCE\_HARNESS map to API. Reviewer and end-user scores also use separate name namespaces: reviewer scores do not use names beginning with user-feedback-.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_SOURCE_JUDGE` | 0 | Canonical | A score produced by an automated judge. | | `SCORE_SOURCE_HUMAN` | 1 | Canonical | A score entered by a human reviewer through the annotation path. | | `SCORE_SOURCE_USER` | 2 | Canonical | Feedback supplied by an end user. | | `SCORE_SOURCE_HARNESS` | 3 | Canonical | A score written by an evaluation harness or another API-based producer. | | `SCORE_SOURCE_EVAL` | 4 | Canonical | A read-only score produced by the evaluation provider's managed evaluators; it cannot be written through the public score API. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_SOURCE_JUDGE`, `SCORE_SOURCE_HUMAN`, `SCORE_SOURCE_USER`, `SCORE_SOURCE_HARNESS`, `SCORE_SOURCE_EVAL` Variant 2: Type: `integer(int32)` **comment** `string` Explanatory text attached to the evaluation score. **createdAt** `string(date-time)` Time when this record was created. **textValue** `string` Text value of the evaluation score. **authorUserId** `string` Identifier recorded for the user who authored the score. A stored author identifier alone does not attest to verified human provenance. **configId** `string` Identifier of the score configuration defining the score’s value domain. **queueId** `string` Identifier of the annotation queue. **traceId** `string` Identifier of the evaluation trace. **observationId** `string` Identifier of the evaluation observation. **sessionId** `string` Identifier of the evaluation session grouping related traces. **datasetRunId** `string` Identifier of the dataset run associated with the score. **environment** `string` Environment label attached to the evaluation record. **metadataJson** `string` Additional attributes serialized as a JSON object. **updatedAt** `string(date-time)` Time when this record was last updated. **timestamp** `string(date-time)` Timestamp associated with the evaluation score. **traceName** `string` Trace name included with the score for display in score listings. **userId** `string` User identifier recorded with the evaluation score. **sourceLabel** `string` Original evaluation-provider source label, such as API, ANNOTATION or EVAL. Interpret it alongside source and authorship: API alone does not distinguish an end-user rating from a harness, and a source label does not independently prove verified human provenance. **conversationId** `string` Conversation identifier recorded in the score’s own metadata. Scores authored directly in the evaluation store can lack platform attribution; an empty link is not repaired by retrying. **messageId** `string` Identifier of the conversation message associated with the evaluation record. **messageSequence** `string(int64)` Sequence number of the evaluated message within its conversation. Pattern: ^-?\d+$ **profileId** `string` Identifier of the agent profile associated with the generation. **configHash** `string` Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation results. Other settings are excluded; this is not an immutable profile revision. **contentRedacted** `boolean` Whether returned trace content is redacted. Redaction occurs before the trace is recorded, so its text is not a faithful copy of the conversation store. #### evals-getTrace-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "trace": { "summary": { "traceId": "example_123", "name": "example", "inputJson": "{}", "outputJson": "{}", "latencySeconds": 1, "totalCost": 1, "environment": "example", "tags": [ "example" ], "metadataJson": "{}", "bookmarked": true, "version": "example", "release": "example", "userId": "example_123", "sessionId": "example_123", "observationCount": 1, "conversationId": "example_123", "sourceUserMessageId": "example_123", "profileId": "example_123", "configHash": "example", "inputTokens": "1", "outputTokens": "1", "totalTokens": "1", "errorCount": 1, "warningCount": 1, "defaultCount": 1, "debugCount": 1, "commentCount": 1 }, "observations": [ { "observationId": "example_123", "traceId": "example_123", "parentObservationId": "example_123", "type": "OBSERVATION_TYPE_SPAN", "name": "example", "level": "OBSERVATION_LEVEL_DEBUG", "statusMessage": "example", "latencySeconds": 1, "inputJson": "{}", "outputJson": "{}", "metadataJson": "{}", "model": "example", "modelParametersJson": "{}", "inputTokens": "1", "outputTokens": "1", "totalTokens": "1", "inputCost": 1, "outputCost": 1, "totalCost": 1, "environment": "example", "version": "example", "promptName": "Example text", "promptVersion": 1, "commentCount": 1, "conversationId": "example_123", "sourceUserMessageId": "example_123", "profileId": "example_123", "configHash": "example" } ], "scores": [ { "scoreId": "example_123", "targetType": "EVAL_TARGET_TYPE_TRACE", "targetId": "example_123", "name": "example", "dataType": "SCORE_DATA_TYPE_NUMERIC", "numericValue": 1, "stringValue": "example", "booleanValue": true, "source": "SCORE_SOURCE_JUDGE", "comment": "example", "textValue": "Example text", "authorUserId": "example_123", "configId": "example_123", "queueId": "example_123", "traceId": "example_123", "observationId": "example_123", "sessionId": "example_123", "datasetRunId": "example_123", "environment": "example", "metadataJson": "{}", "traceName": "example", "userId": "example_123", "sourceLabel": "example", "conversationId": "example_123", "messageId": "example_123", "messageSequence": "1", "profileId": "example_123", "configHash": "example" } ] }, "contentRedacted": true } ``` Document ID: `DOC-IS-evaluation-api-getTrace`. [Section identities and revisions](/documentation-manifest.json). - Get a trace: `DOC-IS-evaluation-api-getTrace#overview` - Request: `DOC-IS-evaluation-api-getTrace#request` - Responses: `DOC-IS-evaluation-api-getTrace#responses` --- # List annotation queue items URL: https://docs.travila.ai/api/evals/list-annotation-queue-items **POST** `/api/v1/evals/list-annotation-queue-items` Lists annotation queue items. ### Reading an item For a trace item, pass [`objectId`](/api/models/schema-ovc35nr9td#response-field-objectid) to [get-trace](/api/evals/get-trace). Other target kinds need their matching read operation. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Review and score turns](/insights/evaluation/review) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for listing evaluation objects in an annotation queue. **queueId** `string` **required** Identifier of the evaluation annotation queue. Minimum length: 1 **page** `string(int64)` Page number requested from the backing service. Pattern: ^-?\d+$ **pageSize** `string(int64)` Requested maximum number of entries in a result page. Pattern: ^-?\d+$ **status** `any` Annotation state used to restrict the queue listing. Omit to include both pending and completed items. Progress of a work item in a human annotation queue.
| Value | No. | Form | Meaning | |---|---|---|---| | `ANNOTATION_QUEUE_ITEM_STATUS_PENDING` | 0 | Canonical | The item is waiting for its annotation to be completed. | | `ANNOTATION_QUEUE_ITEM_STATUS_COMPLETED` | 1 | Canonical | Annotation of the queue item has been completed. |
Exactly one of: Variant 1: Type: `string` Enum: `ANNOTATION_QUEUE_ITEM_STATUS_PENDING`, `ANNOTATION_QUEUE_ITEM_STATUS_COMPLETED` Variant 2: Type: `integer(int32)` #### evals-listAnnotationQueueItems-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "queueId": "example_123" } ``` #### cookbook-insights-evaluation-review-04-request Guide request for Pull the worklist. Replace example resource identifiers with your own authorized values. ```json { "queueId": "q_weekly", "status": "ANNOTATION_QUEUE_ITEM_STATUS_PENDING", "page": 1, "pageSize": 20 } ``` ## Responses ### 200 — OK Content type: `application/json` Result of listing evaluation objects in an annotation queue. **items** `array[llm_v1_services_eval_v1_AnnotationQueueItem]` Evaluation annotation queue items in this page. Evaluation object assigned to an annotation queue with completion state and attribution. Model reference: [AnnotationQueueItem](/api/models/schema-ovc35nr9td#response). **itemId** `string` Identifier of the annotation queue item. **queueId** `string` Identifier of the annotation queue. **objectId** `string` Identifier of the evaluation object addressed by the annotation queue item. **objectType** `any` Kind of evaluation object addressed by the annotation queue item. Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_TARGET_TYPE_TRACE` | 0 | Canonical | A complete trace identified by its trace identifier. | | `EVAL_TARGET_TYPE_OBSERVATION` | 1 | Canonical | A specific observation within a trace. | | `EVAL_TARGET_TYPE_DATASET_RUN` | 2 | Canonical | An evaluation run over a dataset. | | `EVAL_TARGET_TYPE_SESSION` | 3 | Canonical | A session grouping multiple traces. The evaluation harness attaches session-scoped judge scores directly; the provider does not expose a session-level evaluator target. |
Exactly one of: Variant 1: Type: `string` Enum: `EVAL_TARGET_TYPE_TRACE`, `EVAL_TARGET_TYPE_OBSERVATION`, `EVAL_TARGET_TYPE_DATASET_RUN`, `EVAL_TARGET_TYPE_SESSION` Variant 2: Type: `integer(int32)` **status** `any` Completion state of the annotation queue item. Progress of a work item in a human annotation queue.
| Value | No. | Form | Meaning | |---|---|---|---| | `ANNOTATION_QUEUE_ITEM_STATUS_PENDING` | 0 | Canonical | The item is waiting for its annotation to be completed. | | `ANNOTATION_QUEUE_ITEM_STATUS_COMPLETED` | 1 | Canonical | Annotation of the queue item has been completed. |
Exactly one of: Variant 1: Type: `string` Enum: `ANNOTATION_QUEUE_ITEM_STATUS_PENDING`, `ANNOTATION_QUEUE_ITEM_STATUS_COMPLETED` Variant 2: Type: `integer(int32)` **completedAt** `string(date-time)` Time when the operation was marked complete. **completedBy** `string` Identifier of the user who completed the annotation queue item. **createdAt** `string(date-time)` Time when this record was created. **page** `any` Page number, page size, and result totals returned by the evaluation provider. All of: Variant 1: One-based offset-pagination position, page size and result totals. Model reference: [EvaluationPageInfo](/api/models/schema-oi3nhojaso#response). **page** `string(int64)` One-based page number. Pattern: ^-?\d+$ **limit** `string(int64)` Maximum number of entries requested from the listing. Pattern: ^-?\d+$ **totalItems** `string(int64)` Total item count reported for the current query. Pattern: ^-?\d+$ **totalPages** `string(int64)` Total number of pages reported for the current query. Pattern: ^-?\d+$ #### evals-listAnnotationQueueItems-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "items": [ { "itemId": "example_123", "queueId": "example_123", "objectId": "example_123", "objectType": "EVAL_TARGET_TYPE_TRACE", "status": "ANNOTATION_QUEUE_ITEM_STATUS_PENDING", "completedAt": "2026-09-16T12:00:00Z", "completedBy": "example", "createdAt": "2026-09-16T12:00:00Z" } ], "page": { "page": 1, "limit": 1, "totalItems": 1, "totalPages": 1 } } ``` #### cookbook-insights-evaluation-review-json-01-response Illustrative response for Pull the worklist. Replace example resource identifiers with your own authorized values. ```json { "items": [ { "itemId": "qi_001", "queueId": "q_weekly", "objectType": "EVAL_TARGET_TYPE_TRACE", "objectId": "trc_a1b2c3", "status": "ANNOTATION_QUEUE_ITEM_STATUS_PENDING", "createdAt": "2026-08-12T17:00:00Z" } ], "page": { "page": 1, "limit": 20, "totalItems": 34, "totalPages": 2 } } ``` Document ID: `DOC-IS-evaluation-api-listAnnotationQueueItems`. [Section identities and revisions](/documentation-manifest.json). - List annotation queue items: `DOC-IS-evaluation-api-listAnnotationQueueItems#overview` - Request: `DOC-IS-evaluation-api-listAnnotationQueueItems#request` - Responses: `DOC-IS-evaluation-api-listAnnotationQueueItems#responses` --- # List annotation queues URL: https://docs.travila.ai/api/evals/list-annotation-queues **POST** `/api/v1/evals/list-annotation-queues` Lists the review queues defined for this tenant. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Review and score turns](/insights/evaluation/review) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for listing queues of evaluation objects awaiting annotation. **page** `string(int64)` Page number requested from the backing service. Pattern: ^-?\d+$ **pageSize** `string(int64)` Requested maximum number of entries in a result page. Pattern: ^-?\d+$ #### evals-listAnnotationQueues-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json {} ``` ## Responses ### 200 — OK Content type: `application/json` Result of listing queues of evaluation objects awaiting annotation. **queues** `array[llm_v1_services_eval_v1_AnnotationQueue]` Evaluation annotation queues included in this result page. Named work queue assigning score configurations to human annotation items. Model reference: [AnnotationQueue](/api/models/schema-1j9496mkdg#response). **queueId** `string` Identifier of the annotation queue. **name** `string` Display name of the annotation work queue. **description** `string` Human-readable description of the resource. **scoreConfigIds** `array[string]` Score configurations available when annotating items in this queue. At least one configuration is required. Type: `string` **createdAt** `string(date-time)` Time when this record was created. **updatedAt** `string(date-time)` Time when this record was last updated. **pendingCount** `string(int64)` Number of queue items awaiting annotation. Pattern: ^-?\d+$ **completedCount** `string(int64)` Number of queue items reported completed. Pattern: ^-?\d+$ **page** `any` Page number, page size, and result totals returned by the evaluation provider. All of: Variant 1: One-based offset-pagination position, page size and result totals. Model reference: [EvaluationPageInfo](/api/models/schema-oi3nhojaso#response). **page** `string(int64)` One-based page number. Pattern: ^-?\d+$ **limit** `string(int64)` Maximum number of entries requested from the listing. Pattern: ^-?\d+$ **totalItems** `string(int64)` Total item count reported for the current query. Pattern: ^-?\d+$ **totalPages** `string(int64)` Total number of pages reported for the current query. Pattern: ^-?\d+$ #### evals-listAnnotationQueues-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "queues": [ { "queueId": "example_123", "name": "example", "description": "example", "scoreConfigIds": [ "example_123" ], "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z", "pendingCount": 1, "completedCount": 1 } ], "page": { "page": 1, "limit": 1, "totalItems": 1, "totalPages": 1 } } ``` Document ID: `DOC-IS-evaluation-api-listAnnotationQueues`. [Section identities and revisions](/documentation-manifest.json). - List annotation queues: `DOC-IS-evaluation-api-listAnnotationQueues#overview` - Request: `DOC-IS-evaluation-api-listAnnotationQueues#request` - Responses: `DOC-IS-evaluation-api-listAnnotationQueues#responses` --- # List comments URL: https://docs.travila.ai/api/evals/list-comments **POST** `/api/v1/evals/list-comments` Lists the comments on one object. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Review and score turns](/insights/evaluation/review) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for listing comments attached to evaluation objects. **objectType** `any` Kind of evaluation object to which the comment belongs. Kind of evaluation object to which a reviewer comment is attached.
| Value | No. | Form | Meaning | |---|---|---|---| | `COMMENT_OBJECT_TYPE_TRACE` | 0 | Canonical | Attach the comment to a trace. | | `COMMENT_OBJECT_TYPE_OBSERVATION` | 1 | Canonical | Attach the comment to a particular observation. | | `COMMENT_OBJECT_TYPE_SESSION` | 2 | Canonical | Attach the comment to a session. | | `COMMENT_OBJECT_TYPE_PROMPT` | 3 | Canonical | Attach the comment to a specific prompt version using that version's UUID, not the prompt name. A comment on one version does not appear on later versions. |
Exactly one of: Variant 1: Type: `string` Enum: `COMMENT_OBJECT_TYPE_TRACE`, `COMMENT_OBJECT_TYPE_OBSERVATION`, `COMMENT_OBJECT_TYPE_SESSION`, `COMMENT_OBJECT_TYPE_PROMPT` Variant 2: Type: `integer(int32)` **objectId** `string` Identifier of the evaluation object to which the comment belongs. **page** `string(int64)` Page number requested from the backing service. Pattern: ^-?\d+$ **pageSize** `string(int64)` Requested maximum number of entries in a result page. Pattern: ^-?\d+$ #### evals-listComments-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json {} ``` ## Responses ### 200 — OK Content type: `application/json` Result of listing comments attached to evaluation objects. **comments** `array[llm_v1_services_eval_v1_Comment]` Evaluation comments included in this result page. Authored text attached to a trace, observation, or other evaluation object. Model reference: [Comment](/api/models/schema-ove4pre5lb#response). **commentId** `string` Identifier of the evaluation comment. **objectType** `any` Kind of evaluation object addressed by the comment. Kind of evaluation object to which a reviewer comment is attached.
| Value | No. | Form | Meaning | |---|---|---|---| | `COMMENT_OBJECT_TYPE_TRACE` | 0 | Canonical | Attach the comment to a trace. | | `COMMENT_OBJECT_TYPE_OBSERVATION` | 1 | Canonical | Attach the comment to a particular observation. | | `COMMENT_OBJECT_TYPE_SESSION` | 2 | Canonical | Attach the comment to a session. | | `COMMENT_OBJECT_TYPE_PROMPT` | 3 | Canonical | Attach the comment to a specific prompt version using that version's UUID, not the prompt name. A comment on one version does not appear on later versions. |
Exactly one of: Variant 1: Type: `string` Enum: `COMMENT_OBJECT_TYPE_TRACE`, `COMMENT_OBJECT_TYPE_OBSERVATION`, `COMMENT_OBJECT_TYPE_SESSION`, `COMMENT_OBJECT_TYPE_PROMPT` Variant 2: Type: `integer(int32)` **objectId** `string` Identifier of the evaluation object addressed by the comment. **content** `string` Text content of the evaluation comment. **authorUserId** `string` Identifier recorded for the user who authored the comment. A stored author identifier alone does not attest to verified human provenance. **createdAt** `string(date-time)` Time when this record was created. **updatedAt** `string(date-time)` Time when this record was last updated. **page** `any` Page number, page size, and result totals returned by the evaluation provider. All of: Variant 1: One-based offset-pagination position, page size and result totals. Model reference: [EvaluationPageInfo](/api/models/schema-oi3nhojaso#response). **page** `string(int64)` One-based page number. Pattern: ^-?\d+$ **limit** `string(int64)` Maximum number of entries requested from the listing. Pattern: ^-?\d+$ **totalItems** `string(int64)` Total item count reported for the current query. Pattern: ^-?\d+$ **totalPages** `string(int64)` Total number of pages reported for the current query. Pattern: ^-?\d+$ #### evals-listComments-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "comments": [ { "commentId": "example_123", "objectType": "COMMENT_OBJECT_TYPE_TRACE", "objectId": "example_123", "content": "Example text", "authorUserId": "example_123", "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z" } ], "page": { "page": 1, "limit": 1, "totalItems": 1, "totalPages": 1 } } ``` Document ID: `DOC-IS-evaluation-api-listComments`. [Section identities and revisions](/documentation-manifest.json). - List comments: `DOC-IS-evaluation-api-listComments#overview` - Request: `DOC-IS-evaluation-api-listComments#request` - Responses: `DOC-IS-evaluation-api-listComments#responses` --- # List dataset items URL: https://docs.travila.ai/api/evals/list-dataset-items **POST** `/api/v1/evals/list-dataset-items` Lists items in a dataset. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Replay datasets and runs](/insights/evaluation/datasets-and-runs) · [Dataset identity and run provenance](/api/evals/datasets) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for listing input and expected-output pairs in an evaluation dataset. **datasetId** `string` Identifier of the evaluation dataset. **datasetName** `string` Name used to address the evaluation dataset. **page** `string(int64)` Page number requested from the backing service. Pattern: ^-?\d+$ **pageSize** `string(int64)` Requested maximum number of entries in a result page. Pattern: ^-?\d+$ **sourceTraceId** `string` Identifier of the trace used as the source for the dataset item. **onlyMissingExpectedOutput** `boolean` Backs the curation list: items still lacking ground truth. #### evals-listDatasetItems-request List items from an existing dataset by name. ```json { "datasetName": "support-answers", "page": 1, "pageSize": 20 } ``` #### cookbook-insights-evaluation-datasets-and-runs-03-request Guide request for 3. Define what an acceptable answer must do. Replace example resource identifiers with your own authorized values. ```json { "datasetName": "support-assistant-regressions", "onlyMissingExpectedOutput": true } ``` ## Responses ### 200 — OK Content type: `application/json` Result of listing input and expected-output pairs in an evaluation dataset. **items** `array[llm_v1_services_eval_v1_DatasetItem]` Evaluation dataset items in this page. One evaluation input with its expected output and source trace references. Model reference: [DatasetItem](/api/models/schema-1jcdgbb5sm#response). **itemId** `string` Identifier of the evaluation dataset item. **datasetId** `string` Identifier of the evaluation dataset. **datasetName** `string` Name of the evaluation dataset. **inputJson** `string` Evaluation input serialized as JSON. **expectedOutputJson** `string` Expected output serialized as JSON. Empty until a curator supplies an expected result. **metadataJson** `string` Additional attributes serialized as a JSON object. **sourceTraceId** `string` Identifier of the trace from which the dataset item originated. **sourceObservationId** `string` Identifier of the observation from which the dataset item originated. **status** `any` State controlling whether the dataset item participates in evaluation. Whether a dataset item is active or retained as archived content.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATASET_ITEM_STATUS_ACTIVE` | 0 | Canonical | The dataset item is active. | | `DATASET_ITEM_STATUS_ARCHIVED` | 1 | Canonical | The dataset item is archived and retained as historical content. |
Exactly one of: Variant 1: Type: `string` Enum: `DATASET_ITEM_STATUS_ACTIVE`, `DATASET_ITEM_STATUS_ARCHIVED` Variant 2: Type: `integer(int32)` **createdAt** `string(date-time)` Time when this record was created. **updatedAt** `string(date-time)` Time when this record was last updated. **page** `any` Page number, page size, and result totals returned by the evaluation provider. All of: Variant 1: One-based offset-pagination position, page size and result totals. Model reference: [EvaluationPageInfo](/api/models/schema-oi3nhojaso#response). **page** `string(int64)` One-based page number. Pattern: ^-?\d+$ **limit** `string(int64)` Maximum number of entries requested from the listing. Pattern: ^-?\d+$ **totalItems** `string(int64)` Total item count reported for the current query. Pattern: ^-?\d+$ **totalPages** `string(int64)` Total number of pages reported for the current query. Pattern: ^-?\d+$ #### evals-listDatasetItems-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "items": [ { "itemId": "example_123", "datasetId": "example_123", "datasetName": "example", "inputJson": "{}", "expectedOutputJson": "{}", "metadataJson": "{}", "sourceTraceId": "example_123", "sourceObservationId": "example_123", "status": "DATASET_ITEM_STATUS_ACTIVE", "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z" } ], "page": { "page": 1, "limit": 1, "totalItems": 1, "totalPages": 1 } } ``` Document ID: `DOC-IS-evaluation-api-listDatasetItems`. [Section identities and revisions](/documentation-manifest.json). - List dataset items: `DOC-IS-evaluation-api-listDatasetItems#overview` - Request: `DOC-IS-evaluation-api-listDatasetItems#request` - Responses: `DOC-IS-evaluation-api-listDatasetItems#responses` --- # List dataset runs URL: https://docs.travila.ai/api/evals/list-dataset-runs **POST** `/api/v1/evals/list-dataset-runs` Lists past runs against a dataset. Uses cursorPage. Dataset-name resolution currently searches only the first dataset page. Item-count enrichment is bounded and can leave zero after failure; a zero count does not prove that no items ran. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Replay datasets and runs](/insights/evaluation/datasets-and-runs) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for listing recorded runs against an evaluation dataset. **datasetName** `string` **required** Name used to address the evaluation dataset. Minimum length: 1 **pageSize** `string(int64)` Requested maximum number of entries in a result page. Pattern: ^-?\d+$ **cursor** `string` Opaque cursor from the previous response’s cursor\_page.next\_cursor. Leave empty for the first page. Maximum length: 4096 #### evals-listDatasetRuns-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "datasetName": "example" } ``` #### cookbook-insights-evaluation-datasets-and-runs-06-request Guide request for 5. Decide whether the change fixes the problem without regressions. Replace example resource identifiers with your own authorized values. ```json { "datasetName": "support-assistant-regressions", "pageSize": 25 } ``` ## Responses ### 200 — OK Content type: `application/json` Result of listing recorded runs against an evaluation dataset. **runs** `array[llm_v1_services_eval_v1_DatasetRun]` Evaluation dataset runs included in this result page. Metadata describing one execution of an evaluation dataset. Model reference: [DatasetRun](/api/models/schema-1jehhpchdc#response). **runId** `string` Identifier of the evaluation dataset run. **datasetId** `string` Identifier of the evaluation dataset. **name** `string` Name assigned to this execution of the evaluation dataset. **description** `string` Human-readable description of the resource. **metadataJson** `string` Additional attributes serialized as a JSON object. **itemCount** `string(int64)` Number of dataset items reported for this run. Pattern: ^-?\d+$ **createdAt** `string(date-time)` Time when this record was created. **cursorPage** `any` Cursor pagination details accompanying this result page. All of: Variant 1: Opaque-cursor pagination details. A cursor is used to request the next page; arbitrary page-number seeking is not supported. Model reference: [CursorPageInfo](/api/models/schema-oi1c4l4i8b#response). **nextCursor** `string` Pass back as the request's `cursor` for the next page. Empty on the last page. **limit** `string(int64)` Maximum number of entries requested from the listing. Pattern: ^-?\d+$ **totalItems** `string(int64)` Total number of matching items when it can be counted exactly. Absent when the selected filters do not support an exact total. Pattern: ^-?\d+$ #### evals-listDatasetRuns-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "runs": [ { "runId": "example_123", "datasetId": "example_123", "name": "example", "description": "example", "metadataJson": "{}", "itemCount": 1, "createdAt": "2026-09-16T12:00:00Z" } ], "cursorPage": { "nextCursor": "example", "limit": 1, "totalItems": 1 } } ``` #### cookbook-insights-evaluation-datasets-and-runs-json-01-response Illustrative response for 5. Decide whether the change fixes the problem without regressions. Replace example resource identifiers with your own authorized values. ```json { "runs": [ { "runId": "run_0912", "name": "2026-08-12-candidate", "datasetId": "ds_771", "description": "profile revision and qualified model recorded in manifest", "itemCount": 120, "createdAt": "2026-08-12T18:00:00Z" } ], "cursorPage": { "limit": 25 } } ``` Document ID: `DOC-IS-evaluation-api-listDatasetRuns`. [Section identities and revisions](/documentation-manifest.json). - List dataset runs: `DOC-IS-evaluation-api-listDatasetRuns#overview` - Request: `DOC-IS-evaluation-api-listDatasetRuns#request` - Responses: `DOC-IS-evaluation-api-listDatasetRuns#responses` --- # List datasets URL: https://docs.travila.ai/api/evals/list-datasets **POST** `/api/v1/evals/list-datasets` Lists the evaluation datasets defined for this tenant. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Replay datasets and runs](/insights/evaluation/datasets-and-runs) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for listing evaluation datasets. **page** `string(int64)` Page number requested from the backing service. Pattern: ^-?\d+$ **pageSize** `string(int64)` Requested maximum number of entries in a result page. Pattern: ^-?\d+$ #### evals-listDatasets-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json {} ``` #### cookbook-insights-evaluation-datasets-and-runs-08-request Guide request for Browse the datasets. Replace example resource identifiers with your own authorized values. ```json { "page": 1, "pageSize": 25 } ``` ## Responses ### 200 — OK Content type: `application/json` Result of listing evaluation datasets. **datasets** `array[llm_v1_services_eval_v1_Dataset]` Evaluation datasets included in this result page. Evaluation dataset metadata, item counts, run history, and input/output schemas. Model reference: [Dataset](/api/models/schema-1ja63aqvqo#response). **datasetId** `string` Identifier of the evaluation dataset. **name** `string` Name identifying the evaluation dataset. **description** `string` Human-readable description of the resource. **metadataJson** `string` Additional attributes serialized as a JSON object. **itemCount** `string(int64)` Number of dataset items reported for the dataset. Pattern: ^-?\d+$ **runCount** `string(int64)` Number of runs reported for the evaluation dataset. Pattern: ^-?\d+$ **createdAt** `string(date-time)` Time when this record was created. **lastRunAt** `string(date-time)` Time when the dataset was most recently evaluated. **inputSchemaJson** `string` JSON Schema describing dataset input values. **expectedOutputSchemaJson** `string` JSON Schema describing expected dataset output values. **page** `any` Page number, page size, and result totals returned by the evaluation provider. All of: Variant 1: One-based offset-pagination position, page size and result totals. Model reference: [EvaluationPageInfo](/api/models/schema-oi3nhojaso#response). **page** `string(int64)` One-based page number. Pattern: ^-?\d+$ **limit** `string(int64)` Maximum number of entries requested from the listing. Pattern: ^-?\d+$ **totalItems** `string(int64)` Total item count reported for the current query. Pattern: ^-?\d+$ **totalPages** `string(int64)` Total number of pages reported for the current query. Pattern: ^-?\d+$ #### evals-listDatasets-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "datasets": [ { "datasetId": "example_123", "name": "example", "description": "example", "metadataJson": "{}", "itemCount": 1, "runCount": 1, "createdAt": "2026-09-16T12:00:00Z", "lastRunAt": "2026-09-16T12:00:00Z", "inputSchemaJson": "{}", "expectedOutputSchemaJson": "{}" } ], "page": { "page": 1, "limit": 1, "totalItems": 1, "totalPages": 1 } } ``` #### cookbook-insights-evaluation-datasets-and-runs-json-03-response Illustrative response for Browse the datasets. Replace example resource identifiers with your own authorized values. ```json { "datasets": [ { "datasetId": "ds_771", "name": "support-assistant-regressions", "description": "Turns a reviewer marked as wrong", "itemCount": 120, "runCount": 8, "lastRunAt": "2026-08-12T18:00:00Z", "createdAt": "2026-06-02T10:00:00Z" } ], "page": { "page": 1, "limit": 25, "totalItems": 3, "totalPages": 1 } } ``` Document ID: `DOC-IS-evaluation-api-listDatasets`. [Section identities and revisions](/documentation-manifest.json). - List datasets: `DOC-IS-evaluation-api-listDatasets#overview` - Request: `DOC-IS-evaluation-api-listDatasets#request` - Responses: `DOC-IS-evaluation-api-listDatasets#responses` --- # List observations URL: https://docs.travila.ai/api/evals/list-observations **POST** `/api/v1/evals/list-observations` Lists the individual spans, generations and events inside traces. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Find out why a customer’s reply was slow](/insights/evaluation/reading) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for listing observations recorded within evaluation traces. **pageSize** `string(int64)` Requested maximum number of entries in a result page. Pattern: ^-?\d+$ **traceId** `string` Identifier of the evaluation trace. **type** `any` Observation type used to restrict the evaluation query. Semantic category of a trace observation, including categories accepted from upstream even when the platform does not emit them. Current emitters produce GENERATION, TOOL, RETRIEVER and SPAN; the other declared categories can still describe upstream observations.
| Value | No. | Form | Meaning | |---|---|---|---| | `OBSERVATION_TYPE_SPAN` | 0 | Canonical | A timed unit of work represented as a span. | | `OBSERVATION_TYPE_GENERATION` | 1 | Canonical | A model-generation operation and its recorded inputs, outputs and usage. | | `OBSERVATION_TYPE_EVENT` | 2 | Canonical | A point-in-time event rather than a timed operation. | | `OBSERVATION_TYPE_TOOL` | 3 | Canonical | Execution of a tool call. | | `OBSERVATION_TYPE_RETRIEVER` | 4 | Canonical | Retrieval of supporting documents or other context. | | `OBSERVATION_TYPE_AGENT` | 5 | Canonical | An agent-level operation reported in the trace. | | `OBSERVATION_TYPE_CHAIN` | 6 | Canonical | A sequence or chain of related processing steps. | | `OBSERVATION_TYPE_EMBEDDING` | 7 | Canonical | Computation of vector embeddings. | | `OBSERVATION_TYPE_EVALUATOR` | 8 | Canonical | An evaluator operation that assesses another result. | | `OBSERVATION_TYPE_GUARDRAIL` | 9 | Canonical | A guardrail check on inputs, outputs or processing. |
Exactly one of: Variant 1: Type: `string` Enum: `OBSERVATION_TYPE_SPAN`, `OBSERVATION_TYPE_GENERATION`, `OBSERVATION_TYPE_EVENT`, `OBSERVATION_TYPE_TOOL`, `OBSERVATION_TYPE_RETRIEVER`, `OBSERVATION_TYPE_AGENT`, `OBSERVATION_TYPE_CHAIN`, `OBSERVATION_TYPE_EMBEDDING`, `OBSERVATION_TYPE_EVALUATOR`, `OBSERVATION_TYPE_GUARDRAIL` Variant 2: Type: `integer(int32)` **level** `any` Severity level used to restrict evaluation observations or traces. Diagnostic severity attached to an evaluation observation.
| Value | No. | Form | Meaning | |---|---|---|---| | `OBSERVATION_LEVEL_DEBUG` | 0 | Canonical | Detailed diagnostic information intended for debugging. | | `OBSERVATION_LEVEL_DEFAULT` | 1 | Canonical | Ordinary observation information without an elevated warning or error level. | | `OBSERVATION_LEVEL_WARNING` | 2 | Canonical | A condition reported at warning severity. | | `OBSERVATION_LEVEL_ERROR` | 3 | Canonical | A condition reported at error severity. |
Exactly one of: Variant 1: Type: `string` Enum: `OBSERVATION_LEVEL_DEBUG`, `OBSERVATION_LEVEL_DEFAULT`, `OBSERVATION_LEVEL_WARNING`, `OBSERVATION_LEVEL_ERROR` Variant 2: Type: `integer(int32)` **parentObservationId** `string` Identifier of the parent observation used to select child observations. **userId** `string` Identifier of the end user associated with this operation or record. Maximum length: 256 **name** `string` Name used to restrict the evaluation record listing. Maximum length: 256 **environment** `string` Environment label used to select evaluation records. Maximum length: 256 **fromTime** `string(date-time)` Beginning of the time range used to select evaluation records. **toTime** `string(date-time)` End of the time range used to select evaluation records. **filters** `array[llm_v1_services_eval_v1_EvalFilter]` Structured filters applied to the evaluation record query. Typed comparison operand and column selector for querying evaluation-provider records. The filter type selects which single value field is meaningful. ### Input constraints ### type Select a listed comparison type. Model reference: [EvalFilter](/api/models/schema-ovg7lvels1#request). **type** `any` **required** Discriminator selecting the evaluation filter’s operand type. Operand shape and comparison vocabulary for an evaluation-record filter. Types and operators follow the provider's v3.224.1 filter vocabulary, including keyed object variants.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_FILTER_TYPE_DATETIME` | 0 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_STRING` | 1 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_NUMBER` | 2 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_STRING_OPTIONS` | 3 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_CATEGORY_OPTIONS` | 4 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_ARRAY_OPTIONS` | 5 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_BOOLEAN` | 6 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_NULL` | 7 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_STRING_OBJECT` | 8 | Canonical | Compare a string-valued member identified by a key, such as a metadata property. STRING\_OBJECT supports metadata filtering; NUMBER\_OBJECT and BOOLEAN\_OBJECT support score filtering keyed by score name. | | `EVAL_FILTER_TYPE_NUMBER_OBJECT` | 9 | Canonical | Compare a numeric member identified by a key, such as a named score. | | `EVAL_FILTER_TYPE_BOOLEAN_OBJECT` | 10 | Canonical | Compare a boolean member identified by a key. | **`EVAL_FILTER_TYPE_DATETIME`** Compare a date-time value using ordered comparisons. \> \< >= \<= **`EVAL_FILTER_TYPE_STRING`** Compare text using equality or supported substring and prefix or suffix operators. \= contains does not contain starts with ends with **`EVAL_FILTER_TYPE_NUMBER`** Compare a numeric value using equality or ordered comparisons. \= > \< >= \<= **`EVAL_FILTER_TYPE_STRING_OPTIONS`** Match a string against a set of allowed or excluded choices. any of none of **`EVAL_FILTER_TYPE_CATEGORY_OPTIONS`** Match a category against a set of allowed or excluded choices. any of none of **`EVAL_FILTER_TYPE_ARRAY_OPTIONS`** Match array contents using any-of, none-of or all-of selection. any of none of all of **`EVAL_FILTER_TYPE_BOOLEAN`** Compare a boolean value for equality or inequality. \= \<> **`EVAL_FILTER_TYPE_NULL`** Test whether the selected property is null or non-null. is null is not null
Exactly one of: Variant 1: Type: `string` Enum: `EVAL_FILTER_TYPE_DATETIME`, `EVAL_FILTER_TYPE_STRING`, `EVAL_FILTER_TYPE_NUMBER`, `EVAL_FILTER_TYPE_STRING_OPTIONS`, `EVAL_FILTER_TYPE_CATEGORY_OPTIONS`, `EVAL_FILTER_TYPE_ARRAY_OPTIONS`, `EVAL_FILTER_TYPE_BOOLEAN`, `EVAL_FILTER_TYPE_NULL`, `EVAL_FILTER_TYPE_STRING_OBJECT`, `EVAL_FILTER_TYPE_NUMBER_OBJECT`, `EVAL_FILTER_TYPE_BOOLEAN_OBJECT` Variant 2: Type: `integer(int32)` Enum: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10` **column** `string` **required** Evaluation filter column identifier, for example traceName, scores\_avg, metadata or level. Minimum length: 1 **operator** `string` **required** Operator accepted for the selected filter type, for example contains, any of or >=. Minimum length: 1 **key** `string` Set only for the \*\_OBJECT types: the metadata key or score name. **stringValue** `string` Text operand used by a text-valued evaluation filter. **numberValue** `any` Numeric operand used by the evaluation filter. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **booleanValue** `boolean` Boolean operand used by the selected evaluation filter type. **stringValues** `array[string]` Text values used by the \*\_OPTIONS comparison types. Type: `string` **timeValue** `string(date-time)` Timestamp operand used by the evaluation filter. **cursor** `string` Opaque cursor from the previous response’s cursor\_page.next\_cursor. Leave empty for the first page. Maximum length: 4096 #### evals-listObservations-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json {} ``` #### cookbook-insights-evaluation-reading-04-request Guide request for Check whether the same tool keeps failing. Replace example resource identifiers with your own authorized values. ```json { "filters": [ { "column": "level", "operator": "=", "type": "EVAL_FILTER_TYPE_STRING", "stringValue": "ERROR" } ], "pageSize": 50 } ``` ## Responses ### 200 — OK Content type: `application/json` Result of listing observations recorded within evaluation traces. **observations** `array[llm_v1_services_eval_v1_Observation]` Evaluation observations included in this result page. Timed evaluation span or generation record with model usage, inputs, outputs, and scores. A generation observation originates the profile and configuration attribution promoted to its trace; callers can read those links directly on either record. Model reference: [Observation](/api/models/schema-1ju9tclufp#response). **observationId** `string` Identifier of the evaluation observation. **traceId** `string` Identifier of the evaluation trace. **parentObservationId** `string` Identifier of the parent observation within the trace. **type** `any` Observation kind reported by the evaluation provider. Semantic category of a trace observation, including categories accepted from upstream even when the platform does not emit them. Current emitters produce GENERATION, TOOL, RETRIEVER and SPAN; the other declared categories can still describe upstream observations.
| Value | No. | Form | Meaning | |---|---|---|---| | `OBSERVATION_TYPE_SPAN` | 0 | Canonical | A timed unit of work represented as a span. | | `OBSERVATION_TYPE_GENERATION` | 1 | Canonical | A model-generation operation and its recorded inputs, outputs and usage. | | `OBSERVATION_TYPE_EVENT` | 2 | Canonical | A point-in-time event rather than a timed operation. | | `OBSERVATION_TYPE_TOOL` | 3 | Canonical | Execution of a tool call. | | `OBSERVATION_TYPE_RETRIEVER` | 4 | Canonical | Retrieval of supporting documents or other context. | | `OBSERVATION_TYPE_AGENT` | 5 | Canonical | An agent-level operation reported in the trace. | | `OBSERVATION_TYPE_CHAIN` | 6 | Canonical | A sequence or chain of related processing steps. | | `OBSERVATION_TYPE_EMBEDDING` | 7 | Canonical | Computation of vector embeddings. | | `OBSERVATION_TYPE_EVALUATOR` | 8 | Canonical | An evaluator operation that assesses another result. | | `OBSERVATION_TYPE_GUARDRAIL` | 9 | Canonical | A guardrail check on inputs, outputs or processing. |
Exactly one of: Variant 1: Type: `string` Enum: `OBSERVATION_TYPE_SPAN`, `OBSERVATION_TYPE_GENERATION`, `OBSERVATION_TYPE_EVENT`, `OBSERVATION_TYPE_TOOL`, `OBSERVATION_TYPE_RETRIEVER`, `OBSERVATION_TYPE_AGENT`, `OBSERVATION_TYPE_CHAIN`, `OBSERVATION_TYPE_EMBEDDING`, `OBSERVATION_TYPE_EVALUATOR`, `OBSERVATION_TYPE_GUARDRAIL` Variant 2: Type: `integer(int32)` **name** `string` Operation name recorded for the evaluation observation. **level** `any` Observation log level reported by the evaluation provider. Diagnostic severity attached to an evaluation observation.
| Value | No. | Form | Meaning | |---|---|---|---| | `OBSERVATION_LEVEL_DEBUG` | 0 | Canonical | Detailed diagnostic information intended for debugging. | | `OBSERVATION_LEVEL_DEFAULT` | 1 | Canonical | Ordinary observation information without an elevated warning or error level. | | `OBSERVATION_LEVEL_WARNING` | 2 | Canonical | A condition reported at warning severity. | | `OBSERVATION_LEVEL_ERROR` | 3 | Canonical | A condition reported at error severity. |
Exactly one of: Variant 1: Type: `string` Enum: `OBSERVATION_LEVEL_DEBUG`, `OBSERVATION_LEVEL_DEFAULT`, `OBSERVATION_LEVEL_WARNING`, `OBSERVATION_LEVEL_ERROR` Variant 2: Type: `integer(int32)` **statusMessage** `string` Diagnostic text explaining the reported state. **startTime** `string(date-time)` Beginning of the time interval represented by this operation. **endTime** `string(date-time)` End of the time interval represented by this operation. **completionStartTime** `string(date-time)` Time to first token, generations only. **latencySeconds** `any` Elapsed observation latency, in seconds. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **inputJson** `string` Evaluation input serialized as JSON. **outputJson** `string` Evaluation output serialized as JSON. **metadataJson** `string` Additional attributes serialized as a JSON object. **model** `string` Model identifier recorded for the evaluated generation. **modelParametersJson** `string` Model parameters recorded as a serialized JSON object. **inputTokens** `string(int64)` Input-token usage reported for the evaluated generation. Pattern: ^-?\d+$ **outputTokens** `string(int64)` Output-token usage reported for the evaluated generation. Pattern: ^-?\d+$ **totalTokens** `string(int64)` Total token usage reported for the evaluated generation or aggregate. Pattern: ^-?\d+$ **inputCost** `any` Cost attributed to model input by the evaluation provider. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **outputCost** `any` Cost attributed to model output by the evaluation provider. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **totalCost** `any` Total cost reported for the evaluated generation or aggregate. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **environment** `string` Environment label attached to the evaluation record. **version** `string` Version of the resource represented by this message. **promptName** `string` Name of the versioned prompt associated with the generation. **promptVersion** `string(int64)` Version of the prompt associated with the generation. Pattern: ^-?\d+$ **scores** `array[llm_v1_services_eval_v1_Score]` Evaluation scores returned for the selected objects or query. Evaluation score with its value, source, target identity, and generation attribution. Model reference: [Score](/api/models/schema-1jm5lo00e7#response). **scoreId** `string` Identifier of the evaluation score. **targetType** `any` Kind of evaluation object to which the score applies. Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_TARGET_TYPE_TRACE` | 0 | Canonical | A complete trace identified by its trace identifier. | | `EVAL_TARGET_TYPE_OBSERVATION` | 1 | Canonical | A specific observation within a trace. | | `EVAL_TARGET_TYPE_DATASET_RUN` | 2 | Canonical | An evaluation run over a dataset. | | `EVAL_TARGET_TYPE_SESSION` | 3 | Canonical | A session grouping multiple traces. The evaluation harness attaches session-scoped judge scores directly; the provider does not expose a session-level evaluator target. |
Exactly one of: Variant 1: Type: `string` Enum: `EVAL_TARGET_TYPE_TRACE`, `EVAL_TARGET_TYPE_OBSERVATION`, `EVAL_TARGET_TYPE_DATASET_RUN`, `EVAL_TARGET_TYPE_SESSION` Variant 2: Type: `integer(int32)` **targetId** `string` Identifier of the evaluation object to which the score applies. **name** `string` Metric name identifying the recorded evaluation score. **dataType** `any` Value type used to interpret numeric, categorical, Boolean, or text score values. Scores Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_DATA_TYPE_NUMERIC` | 0 | Canonical | A numeric measurement or rating. | | `SCORE_DATA_TYPE_CATEGORICAL` | 1 | Canonical | A value chosen from a named set of categories. | | `SCORE_DATA_TYPE_BOOLEAN` | 2 | Canonical | A true-or-false evaluation result. | | `SCORE_DATA_TYPE_TEXT` | 3 | Canonical | Free-form text supplied by an evaluator or reviewer. The provider supports text values on score definitions and scores; support through this API depends on the operation. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_DATA_TYPE_NUMERIC`, `SCORE_DATA_TYPE_CATEGORICAL`, `SCORE_DATA_TYPE_BOOLEAN`, `SCORE_DATA_TYPE_TEXT` Variant 2: Type: `integer(int32)` **numericValue** `any` Numeric score value reported by the evaluator. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stringValue** `string` Category label recorded for a categorical evaluation score. **booleanValue** `boolean` Boolean value recorded for a Boolean evaluation score. **source** `any` Source classification reported for the evaluation score. Platform classification of who produced an evaluation score. The provider source label retains its original vocabulary: writes accept API or ANNOTATION, while EVAL is reserved for the provider's internal evaluators and is rejected through its public API. SCORE\_SOURCE\_HUMAN maps to ANNOTATION. SCORE\_SOURCE\_USER, SCORE\_SOURCE\_JUDGE and SCORE\_SOURCE\_HARNESS map to API. Reviewer and end-user scores also use separate name namespaces: reviewer scores do not use names beginning with user-feedback-.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_SOURCE_JUDGE` | 0 | Canonical | A score produced by an automated judge. | | `SCORE_SOURCE_HUMAN` | 1 | Canonical | A score entered by a human reviewer through the annotation path. | | `SCORE_SOURCE_USER` | 2 | Canonical | Feedback supplied by an end user. | | `SCORE_SOURCE_HARNESS` | 3 | Canonical | A score written by an evaluation harness or another API-based producer. | | `SCORE_SOURCE_EVAL` | 4 | Canonical | A read-only score produced by the evaluation provider's managed evaluators; it cannot be written through the public score API. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_SOURCE_JUDGE`, `SCORE_SOURCE_HUMAN`, `SCORE_SOURCE_USER`, `SCORE_SOURCE_HARNESS`, `SCORE_SOURCE_EVAL` Variant 2: Type: `integer(int32)` **comment** `string` Explanatory text attached to the evaluation score. **createdAt** `string(date-time)` Time when this record was created. **textValue** `string` Text value of the evaluation score. **authorUserId** `string` Identifier recorded for the user who authored the score. A stored author identifier alone does not attest to verified human provenance. **configId** `string` Identifier of the score configuration defining the score’s value domain. **queueId** `string` Identifier of the annotation queue. **traceId** `string` Identifier of the evaluation trace. **observationId** `string` Identifier of the evaluation observation. **sessionId** `string` Identifier of the evaluation session grouping related traces. **datasetRunId** `string` Identifier of the dataset run associated with the score. **environment** `string` Environment label attached to the evaluation record. **metadataJson** `string` Additional attributes serialized as a JSON object. **updatedAt** `string(date-time)` Time when this record was last updated. **timestamp** `string(date-time)` Timestamp associated with the evaluation score. **traceName** `string` Trace name included with the score for display in score listings. **userId** `string` User identifier recorded with the evaluation score. **sourceLabel** `string` Original evaluation-provider source label, such as API, ANNOTATION or EVAL. Interpret it alongside source and authorship: API alone does not distinguish an end-user rating from a harness, and a source label does not independently prove verified human provenance. **conversationId** `string` Conversation identifier recorded in the score’s own metadata. Scores authored directly in the evaluation store can lack platform attribution; an empty link is not repaired by retrying. **messageId** `string` Identifier of the conversation message associated with the evaluation record. **messageSequence** `string(int64)` Sequence number of the evaluated message within its conversation. Pattern: ^-?\d+$ **profileId** `string` Identifier of the agent profile associated with the generation. **configHash** `string` Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation results. Other settings are excluded; this is not an immutable profile revision. **commentCount** `string(int64)` Number of comments reported on the evaluation object. Pattern: ^-?\d+$ **conversationId** `string` Identifier of the conversation associated with this evaluation observation, when recorded. **sourceUserMessageId** `string` Identifier of the user message that opened the evaluated generation turn. **profileId** `string` Identifier of the agent profile associated with the generation. **configHash** `string` Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation results. Other settings are excluded; this is not an immutable profile revision. **contentRedacted** `boolean` Whether sensitive evaluation content has been removed from the returned view. **cursorPage** `any` Cursor pagination details accompanying this result page. All of: Variant 1: Opaque-cursor pagination details. A cursor is used to request the next page; arbitrary page-number seeking is not supported. Model reference: [CursorPageInfo](/api/models/schema-oi1c4l4i8b#response). **nextCursor** `string` Pass back as the request's `cursor` for the next page. Empty on the last page. **limit** `string(int64)` Maximum number of entries requested from the listing. Pattern: ^-?\d+$ **totalItems** `string(int64)` Total number of matching items when it can be counted exactly. Absent when the selected filters do not support an exact total. Pattern: ^-?\d+$ #### evals-listObservations-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "observations": [ { "observationId": "example_123", "traceId": "example_123", "parentObservationId": "example_123", "type": "OBSERVATION_TYPE_SPAN", "name": "example", "level": "OBSERVATION_LEVEL_DEBUG", "statusMessage": "example", "startTime": "2026-09-16T12:00:00Z", "endTime": "2026-09-16T12:00:00Z", "completionStartTime": "2026-09-16T12:00:00Z", "latencySeconds": 1, "inputJson": "{}", "outputJson": "{}", "metadataJson": "{}", "model": "example", "modelParametersJson": "{}", "inputTokens": "1", "outputTokens": "1", "totalTokens": "1", "inputCost": 1, "outputCost": 1, "totalCost": 1, "environment": "example", "version": "example", "promptName": "Example text", "promptVersion": 1, "scores": [ { "scoreId": "example_123", "targetType": "EVAL_TARGET_TYPE_TRACE", "targetId": "example_123", "name": "example", "dataType": "SCORE_DATA_TYPE_NUMERIC", "numericValue": 1, "stringValue": "example", "booleanValue": true, "source": "SCORE_SOURCE_JUDGE", "comment": "example", "textValue": "Example text", "authorUserId": "example_123", "configId": "example_123", "queueId": "example_123", "traceId": "example_123", "observationId": "example_123", "sessionId": "example_123", "datasetRunId": "example_123", "environment": "example", "metadataJson": "{}", "traceName": "example", "userId": "example_123", "sourceLabel": "example", "conversationId": "example_123", "messageId": "example_123", "messageSequence": "1", "profileId": "example_123", "configHash": "example" } ], "commentCount": 1, "conversationId": "example_123", "sourceUserMessageId": "example_123", "profileId": "example_123", "configHash": "example" } ], "contentRedacted": true, "cursorPage": { "nextCursor": "example", "limit": 1, "totalItems": 1 } } ``` #### cookbook-insights-evaluation-reading-json-02-response Illustrative response for Check whether the same tool keeps failing. Replace example resource identifiers with your own authorized values. ```json { "observations": [ { "observationId": "obs_9", "traceId": "trc_a1b2c3", "parentObservationId": "obs_2", "name": "get_weather", "level": "OBSERVATION_LEVEL_ERROR", "statusMessage": "upstream timeout", "latencySeconds": 30 } ], "cursorPage": { "limit": 50 }, "contentRedacted": true } ``` Document ID: `DOC-IS-evaluation-api-listObservations`. [Section identities and revisions](/documentation-manifest.json). - List observations: `DOC-IS-evaluation-api-listObservations#overview` - Request: `DOC-IS-evaluation-api-listObservations#request` - Responses: `DOC-IS-evaluation-api-listObservations#responses` --- # List score configs URL: https://docs.travila.ai/api/evals/list-score-configs **POST** `/api/v1/evals/list-score-configs` Lists the rating scales defined for this tenant. Use this list to select a compatible scale before recording a score. Archived configs remain readable for historical interpretation but are not offered for new ratings. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Review and score turns](/insights/evaluation/review) · [Feedback and score attribution](/api/evals/scoring) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for listing definitions and allowed values of evaluation scores. **page** `string(int64)` Page number requested from the backing service. Pattern: ^-?\d+$ **pageSize** `string(int64)` Requested maximum number of entries in a result page. Pattern: ^-?\d+$ **includeArchived** `boolean` Whether archived score configurations are included in the listing. They are excluded when this field is omitted or false. #### evals-listScoreConfigs-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json {} ``` ## Responses ### 200 — OK Content type: `application/json` Result of listing definitions and allowed values of evaluation scores. **configs** `array[llm_v1_services_eval_v1_ScoreConfig]` Evaluation score configurations included in this result page. Score definition specifying its value type, bounds, and allowed categories. Model reference: [ScoreConfig](/api/models/schema-1k2h0fdd77#response). **configId** `string` Identifier of the score configuration defining the score’s value domain. **name** `string` Name identifying the score definition. **dataType** `any` Value type used to interpret numeric, categorical, Boolean, or text score values. Scores Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_DATA_TYPE_NUMERIC` | 0 | Canonical | A numeric measurement or rating. | | `SCORE_DATA_TYPE_CATEGORICAL` | 1 | Canonical | A value chosen from a named set of categories. | | `SCORE_DATA_TYPE_BOOLEAN` | 2 | Canonical | A true-or-false evaluation result. | | `SCORE_DATA_TYPE_TEXT` | 3 | Canonical | Free-form text supplied by an evaluator or reviewer. The provider supports text values on score definitions and scores; support through this API depends on the operation. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_DATA_TYPE_NUMERIC`, `SCORE_DATA_TYPE_CATEGORICAL`, `SCORE_DATA_TYPE_BOOLEAN`, `SCORE_DATA_TYPE_TEXT` Variant 2: Type: `integer(int32)` **description** `string` Human-readable description of the resource. **minValue** `any` Minimum numeric score value allowed by the score configuration. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxValue** `any` Maximum numeric score value allowed by the score configuration. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **categories** `array[llm_v1_services_eval_v1_ScoreConfigCategory]` Named score categories defined by the score configuration. Named category and associated numeric value in a categorical score definition. Model reference: [ScoreConfigCategory](/api/models/schema-1k0g6fhhqd#response). **label** `string` Label identifying this score category. **value** `any` Numeric score value associated with this named category. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **isArchived** `boolean` Whether the score configuration is archived. Archived configurations are retained so historical scores remain interpretable. **createdAt** `string(date-time)` Time when this record was created. **updatedAt** `string(date-time)` Time when this record was last updated. **page** `any` Page number, page size, and result totals returned by the evaluation provider. All of: Variant 1: One-based offset-pagination position, page size and result totals. Model reference: [EvaluationPageInfo](/api/models/schema-oi3nhojaso#response). **page** `string(int64)` One-based page number. Pattern: ^-?\d+$ **limit** `string(int64)` Maximum number of entries requested from the listing. Pattern: ^-?\d+$ **totalItems** `string(int64)` Total item count reported for the current query. Pattern: ^-?\d+$ **totalPages** `string(int64)` Total number of pages reported for the current query. Pattern: ^-?\d+$ #### evals-listScoreConfigs-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "configs": [ { "configId": "example_123", "name": "example", "dataType": "SCORE_DATA_TYPE_NUMERIC", "description": "example", "minValue": 1, "maxValue": 1, "categories": [ { "label": "example", "value": 1 } ], "isArchived": true, "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z" } ], "page": { "page": 1, "limit": 1, "totalItems": 1, "totalPages": 1 } } ``` Document ID: `DOC-IS-evaluation-api-listScoreConfigs`. [Section identities and revisions](/documentation-manifest.json). - List score configs: `DOC-IS-evaluation-api-listScoreConfigs#overview` - Request: `DOC-IS-evaluation-api-listScoreConfigs#request` - Responses: `DOC-IS-evaluation-api-listScoreConfigs#responses` --- # List scores URL: https://docs.travila.ai/api/evals/list-scores **POST** `/api/v1/evals/list-scores` Lists recorded scores across their sources and evaluation targets. ### Filtering by what the rating is about `conversationId` and `profileId` answer "every rating on this conversation" and "every rating on turns this agent profile produced". Each is decided per score — on the score's own metadata, or on the trace it scores when the metadata does not say — and combining them is an intersection. `conversationId` accepts a bare thread id and qualifies it with your verified tenant. ### Reading the result honestly **`filterNarrowed`** matters when you paginate. Some filters cannot be applied by the underlying store, so rows are removed after they are fetched: `conversationId`, `profileId`, `userId`, the platform `source` values the store does not distinguish, and the rows of the `filters` array. The response sets `filterNarrowed: true` only when at least one row was removed from the pages fetched for this response. It can remain false or be omitted even when these filters were evaluated. A page may be shorter than `pageSize` or empty while `cursorPage.nextCursor` still leads to more matches — keep following the cursor until it is omitted rather than stopping at a short page. A false or omitted flag is not a complete-history or consistent-snapshot guarantee. There is no total. Deduplicate IDs across pages when collecting a report. ### Score filters and result coverage Current min/max score filters treat zero as unset; to apply a zero bound, collect the relevant permitted pages and filter in your application. See [list-scores](/api/evals/list-scores) for supported filters. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Find out why a customer’s reply was slow](/insights/evaluation/reading) · [Feedback and score attribution](/api/evals/scoring) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for listing scores attached to evaluation objects. **pageSize** `string(int64)` Requested maximum number of entries in a result page. Pattern: ^-?\d+$ **targetType** `any` Kind of evaluation object targeted by the score or annotation. Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_TARGET_TYPE_TRACE` | 0 | Canonical | A complete trace identified by its trace identifier. | | `EVAL_TARGET_TYPE_OBSERVATION` | 1 | Canonical | A specific observation within a trace. | | `EVAL_TARGET_TYPE_DATASET_RUN` | 2 | Canonical | An evaluation run over a dataset. | | `EVAL_TARGET_TYPE_SESSION` | 3 | Canonical | A session grouping multiple traces. The evaluation harness attaches session-scoped judge scores directly; the provider does not expose a session-level evaluator target. |
Exactly one of: Variant 1: Type: `string` Enum: `EVAL_TARGET_TYPE_TRACE`, `EVAL_TARGET_TYPE_OBSERVATION`, `EVAL_TARGET_TYPE_DATASET_RUN`, `EVAL_TARGET_TYPE_SESSION` Variant 2: Type: `integer(int32)` **targetId** `string` Identifier of the evaluation object targeted by the score or annotation. **name** `string` Name used to restrict the evaluation record listing. Maximum length: 256 **source** `any` Origin of the evaluation scores selected by this query. Platform classification of who produced an evaluation score. The provider source label retains its original vocabulary: writes accept API or ANNOTATION, while EVAL is reserved for the provider's internal evaluators and is rejected through its public API. SCORE\_SOURCE\_HUMAN maps to ANNOTATION. SCORE\_SOURCE\_USER, SCORE\_SOURCE\_JUDGE and SCORE\_SOURCE\_HARNESS map to API. Reviewer and end-user scores also use separate name namespaces: reviewer scores do not use names beginning with user-feedback-.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_SOURCE_JUDGE` | 0 | Canonical | A score produced by an automated judge. | | `SCORE_SOURCE_HUMAN` | 1 | Canonical | A score entered by a human reviewer through the annotation path. | | `SCORE_SOURCE_USER` | 2 | Canonical | Feedback supplied by an end user. | | `SCORE_SOURCE_HARNESS` | 3 | Canonical | A score written by an evaluation harness or another API-based producer. | | `SCORE_SOURCE_EVAL` | 4 | Canonical | A read-only score produced by the evaluation provider's managed evaluators; it cannot be written through the public score API. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_SOURCE_JUDGE`, `SCORE_SOURCE_HUMAN`, `SCORE_SOURCE_USER`, `SCORE_SOURCE_HARNESS`, `SCORE_SOURCE_EVAL` Variant 2: Type: `integer(int32)` **fromTime** `string(date-time)` Beginning of the time range used to select evaluation records. **toTime** `string(date-time)` End of the time range used to select evaluation records. **userId** `string` Identifier of the end user associated with this operation or record. Maximum length: 256 **profileId** `string` Identifier of the agent profile associated with the operation or generation. Maximum length: 256 **minValue** `any` Lower numeric bound for the score range. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxValue** `any` Upper numeric bound for the score range. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **conversationId** `string` Identifier of the conversation associated with the evaluation record. Maximum length: 256 **sessionId** `string` Identifier of the evaluation session grouping related traces. Maximum length: 256 **dataType** `any` Value type used to interpret the evaluation score. Scores Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_DATA_TYPE_NUMERIC` | 0 | Canonical | A numeric measurement or rating. | | `SCORE_DATA_TYPE_CATEGORICAL` | 1 | Canonical | A value chosen from a named set of categories. | | `SCORE_DATA_TYPE_BOOLEAN` | 2 | Canonical | A true-or-false evaluation result. | | `SCORE_DATA_TYPE_TEXT` | 3 | Canonical | Free-form text supplied by an evaluator or reviewer. The provider supports text values on score definitions and scores; support through this API depends on the operation. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_DATA_TYPE_NUMERIC`, `SCORE_DATA_TYPE_CATEGORICAL`, `SCORE_DATA_TYPE_BOOLEAN`, `SCORE_DATA_TYPE_TEXT` Variant 2: Type: `integer(int32)` **traceId** `string` Identifier of the evaluation trace. **filters** `array[llm_v1_services_eval_v1_EvalFilter]` Structured filters applied to the evaluation record query. Typed comparison operand and column selector for querying evaluation-provider records. The filter type selects which single value field is meaningful. ### Input constraints ### type Select a listed comparison type. Model reference: [EvalFilter](/api/models/schema-ovg7lvels1#request). **type** `any` **required** Discriminator selecting the evaluation filter’s operand type. Operand shape and comparison vocabulary for an evaluation-record filter. Types and operators follow the provider's v3.224.1 filter vocabulary, including keyed object variants.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_FILTER_TYPE_DATETIME` | 0 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_STRING` | 1 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_NUMBER` | 2 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_STRING_OPTIONS` | 3 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_CATEGORY_OPTIONS` | 4 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_ARRAY_OPTIONS` | 5 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_BOOLEAN` | 6 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_NULL` | 7 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_STRING_OBJECT` | 8 | Canonical | Compare a string-valued member identified by a key, such as a metadata property. STRING\_OBJECT supports metadata filtering; NUMBER\_OBJECT and BOOLEAN\_OBJECT support score filtering keyed by score name. | | `EVAL_FILTER_TYPE_NUMBER_OBJECT` | 9 | Canonical | Compare a numeric member identified by a key, such as a named score. | | `EVAL_FILTER_TYPE_BOOLEAN_OBJECT` | 10 | Canonical | Compare a boolean member identified by a key. | **`EVAL_FILTER_TYPE_DATETIME`** Compare a date-time value using ordered comparisons. \> \< >= \<= **`EVAL_FILTER_TYPE_STRING`** Compare text using equality or supported substring and prefix or suffix operators. \= contains does not contain starts with ends with **`EVAL_FILTER_TYPE_NUMBER`** Compare a numeric value using equality or ordered comparisons. \= > \< >= \<= **`EVAL_FILTER_TYPE_STRING_OPTIONS`** Match a string against a set of allowed or excluded choices. any of none of **`EVAL_FILTER_TYPE_CATEGORY_OPTIONS`** Match a category against a set of allowed or excluded choices. any of none of **`EVAL_FILTER_TYPE_ARRAY_OPTIONS`** Match array contents using any-of, none-of or all-of selection. any of none of all of **`EVAL_FILTER_TYPE_BOOLEAN`** Compare a boolean value for equality or inequality. \= \<> **`EVAL_FILTER_TYPE_NULL`** Test whether the selected property is null or non-null. is null is not null
Exactly one of: Variant 1: Type: `string` Enum: `EVAL_FILTER_TYPE_DATETIME`, `EVAL_FILTER_TYPE_STRING`, `EVAL_FILTER_TYPE_NUMBER`, `EVAL_FILTER_TYPE_STRING_OPTIONS`, `EVAL_FILTER_TYPE_CATEGORY_OPTIONS`, `EVAL_FILTER_TYPE_ARRAY_OPTIONS`, `EVAL_FILTER_TYPE_BOOLEAN`, `EVAL_FILTER_TYPE_NULL`, `EVAL_FILTER_TYPE_STRING_OBJECT`, `EVAL_FILTER_TYPE_NUMBER_OBJECT`, `EVAL_FILTER_TYPE_BOOLEAN_OBJECT` Variant 2: Type: `integer(int32)` Enum: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10` **column** `string` **required** Evaluation filter column identifier, for example traceName, scores\_avg, metadata or level. Minimum length: 1 **operator** `string` **required** Operator accepted for the selected filter type, for example contains, any of or >=. Minimum length: 1 **key** `string` Set only for the \*\_OBJECT types: the metadata key or score name. **stringValue** `string` Text operand used by a text-valued evaluation filter. **numberValue** `any` Numeric operand used by the evaluation filter. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **booleanValue** `boolean` Boolean operand used by the selected evaluation filter type. **stringValues** `array[string]` Text values used by the \*\_OPTIONS comparison types. Type: `string` **timeValue** `string(date-time)` Timestamp operand used by the evaluation filter. **cursor** `string` Opaque cursor from the previous response’s cursor\_page.next\_cursor. Leave empty for the first page. Maximum length: 4096 #### evals-listScores-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json {} ``` #### cookbook-insights-evaluation-reading-03-request Guide request for Read judgments about that same reply. Replace example resource identifiers with your own authorized values. ```json { "conversationId": "conv_123", "dataType": "SCORE_DATA_TYPE_NUMERIC", "pageSize": 50 } ``` ## Responses ### 200 — OK Content type: `application/json` Result of listing scores attached to evaluation objects. **scores** `array[llm_v1_services_eval_v1_Score]` Evaluation scores included in this result page. Evaluation score with its value, source, target identity, and generation attribution. Model reference: [Score](/api/models/schema-1jm5lo00e7#response). **scoreId** `string` Identifier of the evaluation score. **targetType** `any` Kind of evaluation object to which the score applies. Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_TARGET_TYPE_TRACE` | 0 | Canonical | A complete trace identified by its trace identifier. | | `EVAL_TARGET_TYPE_OBSERVATION` | 1 | Canonical | A specific observation within a trace. | | `EVAL_TARGET_TYPE_DATASET_RUN` | 2 | Canonical | An evaluation run over a dataset. | | `EVAL_TARGET_TYPE_SESSION` | 3 | Canonical | A session grouping multiple traces. The evaluation harness attaches session-scoped judge scores directly; the provider does not expose a session-level evaluator target. |
Exactly one of: Variant 1: Type: `string` Enum: `EVAL_TARGET_TYPE_TRACE`, `EVAL_TARGET_TYPE_OBSERVATION`, `EVAL_TARGET_TYPE_DATASET_RUN`, `EVAL_TARGET_TYPE_SESSION` Variant 2: Type: `integer(int32)` **targetId** `string` Identifier of the evaluation object to which the score applies. **name** `string` Metric name identifying the recorded evaluation score. **dataType** `any` Value type used to interpret numeric, categorical, Boolean, or text score values. Scores Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_DATA_TYPE_NUMERIC` | 0 | Canonical | A numeric measurement or rating. | | `SCORE_DATA_TYPE_CATEGORICAL` | 1 | Canonical | A value chosen from a named set of categories. | | `SCORE_DATA_TYPE_BOOLEAN` | 2 | Canonical | A true-or-false evaluation result. | | `SCORE_DATA_TYPE_TEXT` | 3 | Canonical | Free-form text supplied by an evaluator or reviewer. The provider supports text values on score definitions and scores; support through this API depends on the operation. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_DATA_TYPE_NUMERIC`, `SCORE_DATA_TYPE_CATEGORICAL`, `SCORE_DATA_TYPE_BOOLEAN`, `SCORE_DATA_TYPE_TEXT` Variant 2: Type: `integer(int32)` **numericValue** `any` Numeric score value reported by the evaluator. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stringValue** `string` Category label recorded for a categorical evaluation score. **booleanValue** `boolean` Boolean value recorded for a Boolean evaluation score. **source** `any` Source classification reported for the evaluation score. Platform classification of who produced an evaluation score. The provider source label retains its original vocabulary: writes accept API or ANNOTATION, while EVAL is reserved for the provider's internal evaluators and is rejected through its public API. SCORE\_SOURCE\_HUMAN maps to ANNOTATION. SCORE\_SOURCE\_USER, SCORE\_SOURCE\_JUDGE and SCORE\_SOURCE\_HARNESS map to API. Reviewer and end-user scores also use separate name namespaces: reviewer scores do not use names beginning with user-feedback-.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_SOURCE_JUDGE` | 0 | Canonical | A score produced by an automated judge. | | `SCORE_SOURCE_HUMAN` | 1 | Canonical | A score entered by a human reviewer through the annotation path. | | `SCORE_SOURCE_USER` | 2 | Canonical | Feedback supplied by an end user. | | `SCORE_SOURCE_HARNESS` | 3 | Canonical | A score written by an evaluation harness or another API-based producer. | | `SCORE_SOURCE_EVAL` | 4 | Canonical | A read-only score produced by the evaluation provider's managed evaluators; it cannot be written through the public score API. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_SOURCE_JUDGE`, `SCORE_SOURCE_HUMAN`, `SCORE_SOURCE_USER`, `SCORE_SOURCE_HARNESS`, `SCORE_SOURCE_EVAL` Variant 2: Type: `integer(int32)` **comment** `string` Explanatory text attached to the evaluation score. **createdAt** `string(date-time)` Time when this record was created. **textValue** `string` Text value of the evaluation score. **authorUserId** `string` Identifier recorded for the user who authored the score. A stored author identifier alone does not attest to verified human provenance. **configId** `string` Identifier of the score configuration defining the score’s value domain. **queueId** `string` Identifier of the annotation queue. **traceId** `string` Identifier of the evaluation trace. **observationId** `string` Identifier of the evaluation observation. **sessionId** `string` Identifier of the evaluation session grouping related traces. **datasetRunId** `string` Identifier of the dataset run associated with the score. **environment** `string` Environment label attached to the evaluation record. **metadataJson** `string` Additional attributes serialized as a JSON object. **updatedAt** `string(date-time)` Time when this record was last updated. **timestamp** `string(date-time)` Timestamp associated with the evaluation score. **traceName** `string` Trace name included with the score for display in score listings. **userId** `string` User identifier recorded with the evaluation score. **sourceLabel** `string` Original evaluation-provider source label, such as API, ANNOTATION or EVAL. Interpret it alongside source and authorship: API alone does not distinguish an end-user rating from a harness, and a source label does not independently prove verified human provenance. **conversationId** `string` Conversation identifier recorded in the score’s own metadata. Scores authored directly in the evaluation store can lack platform attribution; an empty link is not repaired by retrying. **messageId** `string` Identifier of the conversation message associated with the evaluation record. **messageSequence** `string(int64)` Sequence number of the evaluated message within its conversation. Pattern: ^-?\d+$ **profileId** `string` Identifier of the agent profile associated with the generation. **configHash** `string` Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation results. Other settings are excluded; this is not an immutable profile revision. **filterNarrowed** `boolean` Whether additional filtering removed rows from this page. A narrowed page can contain fewer than page\_size results while cursor\_page.next\_cursor still identifies another page. **cursorPage** `any` Cursor pagination details accompanying this result page. All of: Variant 1: Opaque-cursor pagination details. A cursor is used to request the next page; arbitrary page-number seeking is not supported. Model reference: [CursorPageInfo](/api/models/schema-oi1c4l4i8b#response). **nextCursor** `string` Pass back as the request's `cursor` for the next page. Empty on the last page. **limit** `string(int64)` Maximum number of entries requested from the listing. Pattern: ^-?\d+$ **totalItems** `string(int64)` Total number of matching items when it can be counted exactly. Absent when the selected filters do not support an exact total. Pattern: ^-?\d+$ #### evals-listScores-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "scores": [ { "scoreId": "example_123", "targetType": "EVAL_TARGET_TYPE_TRACE", "targetId": "example_123", "name": "example", "dataType": "SCORE_DATA_TYPE_NUMERIC", "numericValue": 1, "stringValue": "example", "booleanValue": true, "source": "SCORE_SOURCE_JUDGE", "comment": "example", "createdAt": "2026-09-16T12:00:00Z", "textValue": "Example text", "authorUserId": "example_123", "configId": "example_123", "queueId": "example_123", "traceId": "example_123", "observationId": "example_123", "sessionId": "example_123", "datasetRunId": "example_123", "environment": "example", "metadataJson": "{}", "updatedAt": "2026-09-16T12:00:00Z", "timestamp": "2026-09-16T12:00:00Z", "traceName": "example", "userId": "example_123", "sourceLabel": "example", "conversationId": "example_123", "messageId": "example_123", "messageSequence": "1", "profileId": "example_123", "configHash": "example" } ], "filterNarrowed": true, "cursorPage": { "nextCursor": "example", "limit": 1, "totalItems": 1 } } ``` #### cookbook-insights-evaluation-reading-json-01-response Illustrative response for Read judgments about that same reply. Replace example resource identifiers with your own authorized values. ```json { "scores": [ { "scoreId": "scr_7788", "name": "helpfulness", "dataType": "SCORE_DATA_TYPE_NUMERIC", "numericValue": 4, "source": "SCORE_SOURCE_HUMAN", "authorUserId": "reviewer_9", "configId": "cfg_help", "traceId": "trc_a1b2c3", "createdAt": "2026-08-12T16:20:00Z", "comment": "Answered, but buried the actual number." } ], "cursorPage": { "limit": 50 }, "filterNarrowed": true } ``` Document ID: `DOC-IS-evaluation-api-listScores`. [Section identities and revisions](/documentation-manifest.json). - List scores: `DOC-IS-evaluation-api-listScores#overview` - Request: `DOC-IS-evaluation-api-listScores#request` - Responses: `DOC-IS-evaluation-api-listScores#responses` --- # List sessions URL: https://docs.travila.ai/api/evals/list-sessions **POST** `/api/v1/evals/list-sessions` Lists sessions for the authenticated tenant. The `filters` array accepts the session columns `id` (the session id), `userIds`, `traceTags`, `createdAt`, `environment` and `metadata`. Columns aggregated over a session — duration, trace count, tokens, scores, comments — cannot be filtered and are rejected with HTTP 400. There is no free-text search. Reads are bounded. A session can repeat at an equal-timestamp cursor boundary. Summary activity can extend outside the list window; unavailable rollup data can appear as zero. Do not treat these summaries as a complete frozen cohort. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Find out why a customer’s reply was slow](/insights/evaluation/reading) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for listing evaluation sessions grouping related traces. **pageSize** `string(int64)` Requested maximum number of entries in a result page. Pattern: ^-?\d+$ **fromTime** `string(date-time)` Beginning of the time range used to select evaluation records. **toTime** `string(date-time)` End of the time range used to select evaluation records. **environment** `string` Environment label used to select evaluation records. Maximum length: 256 **userId** `string` Identifier of the end user associated with this operation or record. Maximum length: 256 **filters** `array[llm_v1_services_eval_v1_EvalFilter]` Structured filters applied to the evaluation record query. Typed comparison operand and column selector for querying evaluation-provider records. The filter type selects which single value field is meaningful. ### Input constraints ### type Select a listed comparison type. Model reference: [EvalFilter](/api/models/schema-ovg7lvels1#request). **type** `any` **required** Discriminator selecting the evaluation filter’s operand type. Operand shape and comparison vocabulary for an evaluation-record filter. Types and operators follow the provider's v3.224.1 filter vocabulary, including keyed object variants.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_FILTER_TYPE_DATETIME` | 0 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_STRING` | 1 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_NUMBER` | 2 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_STRING_OPTIONS` | 3 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_CATEGORY_OPTIONS` | 4 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_ARRAY_OPTIONS` | 5 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_BOOLEAN` | 6 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_NULL` | 7 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_STRING_OBJECT` | 8 | Canonical | Compare a string-valued member identified by a key, such as a metadata property. STRING\_OBJECT supports metadata filtering; NUMBER\_OBJECT and BOOLEAN\_OBJECT support score filtering keyed by score name. | | `EVAL_FILTER_TYPE_NUMBER_OBJECT` | 9 | Canonical | Compare a numeric member identified by a key, such as a named score. | | `EVAL_FILTER_TYPE_BOOLEAN_OBJECT` | 10 | Canonical | Compare a boolean member identified by a key. | **`EVAL_FILTER_TYPE_DATETIME`** Compare a date-time value using ordered comparisons. \> \< >= \<= **`EVAL_FILTER_TYPE_STRING`** Compare text using equality or supported substring and prefix or suffix operators. \= contains does not contain starts with ends with **`EVAL_FILTER_TYPE_NUMBER`** Compare a numeric value using equality or ordered comparisons. \= > \< >= \<= **`EVAL_FILTER_TYPE_STRING_OPTIONS`** Match a string against a set of allowed or excluded choices. any of none of **`EVAL_FILTER_TYPE_CATEGORY_OPTIONS`** Match a category against a set of allowed or excluded choices. any of none of **`EVAL_FILTER_TYPE_ARRAY_OPTIONS`** Match array contents using any-of, none-of or all-of selection. any of none of all of **`EVAL_FILTER_TYPE_BOOLEAN`** Compare a boolean value for equality or inequality. \= \<> **`EVAL_FILTER_TYPE_NULL`** Test whether the selected property is null or non-null. is null is not null
Exactly one of: Variant 1: Type: `string` Enum: `EVAL_FILTER_TYPE_DATETIME`, `EVAL_FILTER_TYPE_STRING`, `EVAL_FILTER_TYPE_NUMBER`, `EVAL_FILTER_TYPE_STRING_OPTIONS`, `EVAL_FILTER_TYPE_CATEGORY_OPTIONS`, `EVAL_FILTER_TYPE_ARRAY_OPTIONS`, `EVAL_FILTER_TYPE_BOOLEAN`, `EVAL_FILTER_TYPE_NULL`, `EVAL_FILTER_TYPE_STRING_OBJECT`, `EVAL_FILTER_TYPE_NUMBER_OBJECT`, `EVAL_FILTER_TYPE_BOOLEAN_OBJECT` Variant 2: Type: `integer(int32)` Enum: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10` **column** `string` **required** Evaluation filter column identifier, for example traceName, scores\_avg, metadata or level. Minimum length: 1 **operator** `string` **required** Operator accepted for the selected filter type, for example contains, any of or >=. Minimum length: 1 **key** `string` Set only for the \*\_OBJECT types: the metadata key or score name. **stringValue** `string` Text operand used by a text-valued evaluation filter. **numberValue** `any` Numeric operand used by the evaluation filter. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **booleanValue** `boolean` Boolean operand used by the selected evaluation filter type. **stringValues** `array[string]` Text values used by the \*\_OPTIONS comparison types. Type: `string` **timeValue** `string(date-time)` Timestamp operand used by the evaluation filter. **cursor** `string` Opaque cursor from the previous response’s cursor\_page.next\_cursor. Leave empty for the first page. Maximum length: 4096 #### evals-listSessions-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json {} ``` ## Responses ### 200 — OK Content type: `application/json` Result of listing evaluation sessions grouping related traces. **sessions** `array[llm_v1_services_eval_v1_SessionSummary]` Evaluation session summaries included in this result page. Aggregated trace, usage, and score information for an evaluation session. Model reference: [SessionSummary](/api/models/schema-pbibjr8tih#response). **sessionId** `string` Identifier of the evaluation session grouping related traces. **createdAt** `string(date-time)` Time when this record was created. **durationSeconds** `any` Elapsed session duration, in seconds. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **environment** `string` Environment label attached to the evaluation record. **userIds** `array[string]` User identifiers recorded for this evaluation session. Type: `string` **traceCount** `string(int64)` Number of traces represented by this session summary. Pattern: ^-?\d+$ **totalCost** `any` Total cost reported for the evaluated generation or aggregate. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **inputTokens** `string(int64)` Input-token usage reported for the evaluated generation. Pattern: ^-?\d+$ **outputTokens** `string(int64)` Output-token usage reported for the evaluated generation. Pattern: ^-?\d+$ **totalTokens** `string(int64)` Total token usage reported for the evaluated generation or aggregate. Pattern: ^-?\d+$ **traceTags** `array[string]` Labels collected from the session’s evaluation traces. Type: `string` **scores** `array[llm_v1_services_eval_v1_Score]` Evaluation scores returned for the selected objects or query. Evaluation score with its value, source, target identity, and generation attribution. Model reference: [Score](/api/models/schema-1jm5lo00e7#response). **scoreId** `string` Identifier of the evaluation score. **targetType** `any` Kind of evaluation object to which the score applies. Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_TARGET_TYPE_TRACE` | 0 | Canonical | A complete trace identified by its trace identifier. | | `EVAL_TARGET_TYPE_OBSERVATION` | 1 | Canonical | A specific observation within a trace. | | `EVAL_TARGET_TYPE_DATASET_RUN` | 2 | Canonical | An evaluation run over a dataset. | | `EVAL_TARGET_TYPE_SESSION` | 3 | Canonical | A session grouping multiple traces. The evaluation harness attaches session-scoped judge scores directly; the provider does not expose a session-level evaluator target. |
Exactly one of: Variant 1: Type: `string` Enum: `EVAL_TARGET_TYPE_TRACE`, `EVAL_TARGET_TYPE_OBSERVATION`, `EVAL_TARGET_TYPE_DATASET_RUN`, `EVAL_TARGET_TYPE_SESSION` Variant 2: Type: `integer(int32)` **targetId** `string` Identifier of the evaluation object to which the score applies. **name** `string` Metric name identifying the recorded evaluation score. **dataType** `any` Value type used to interpret numeric, categorical, Boolean, or text score values. Scores Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_DATA_TYPE_NUMERIC` | 0 | Canonical | A numeric measurement or rating. | | `SCORE_DATA_TYPE_CATEGORICAL` | 1 | Canonical | A value chosen from a named set of categories. | | `SCORE_DATA_TYPE_BOOLEAN` | 2 | Canonical | A true-or-false evaluation result. | | `SCORE_DATA_TYPE_TEXT` | 3 | Canonical | Free-form text supplied by an evaluator or reviewer. The provider supports text values on score definitions and scores; support through this API depends on the operation. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_DATA_TYPE_NUMERIC`, `SCORE_DATA_TYPE_CATEGORICAL`, `SCORE_DATA_TYPE_BOOLEAN`, `SCORE_DATA_TYPE_TEXT` Variant 2: Type: `integer(int32)` **numericValue** `any` Numeric score value reported by the evaluator. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stringValue** `string` Category label recorded for a categorical evaluation score. **booleanValue** `boolean` Boolean value recorded for a Boolean evaluation score. **source** `any` Source classification reported for the evaluation score. Platform classification of who produced an evaluation score. The provider source label retains its original vocabulary: writes accept API or ANNOTATION, while EVAL is reserved for the provider's internal evaluators and is rejected through its public API. SCORE\_SOURCE\_HUMAN maps to ANNOTATION. SCORE\_SOURCE\_USER, SCORE\_SOURCE\_JUDGE and SCORE\_SOURCE\_HARNESS map to API. Reviewer and end-user scores also use separate name namespaces: reviewer scores do not use names beginning with user-feedback-.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_SOURCE_JUDGE` | 0 | Canonical | A score produced by an automated judge. | | `SCORE_SOURCE_HUMAN` | 1 | Canonical | A score entered by a human reviewer through the annotation path. | | `SCORE_SOURCE_USER` | 2 | Canonical | Feedback supplied by an end user. | | `SCORE_SOURCE_HARNESS` | 3 | Canonical | A score written by an evaluation harness or another API-based producer. | | `SCORE_SOURCE_EVAL` | 4 | Canonical | A read-only score produced by the evaluation provider's managed evaluators; it cannot be written through the public score API. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_SOURCE_JUDGE`, `SCORE_SOURCE_HUMAN`, `SCORE_SOURCE_USER`, `SCORE_SOURCE_HARNESS`, `SCORE_SOURCE_EVAL` Variant 2: Type: `integer(int32)` **comment** `string` Explanatory text attached to the evaluation score. **createdAt** `string(date-time)` Time when this record was created. **textValue** `string` Text value of the evaluation score. **authorUserId** `string` Identifier recorded for the user who authored the score. A stored author identifier alone does not attest to verified human provenance. **configId** `string` Identifier of the score configuration defining the score’s value domain. **queueId** `string` Identifier of the annotation queue. **traceId** `string` Identifier of the evaluation trace. **observationId** `string` Identifier of the evaluation observation. **sessionId** `string` Identifier of the evaluation session grouping related traces. **datasetRunId** `string` Identifier of the dataset run associated with the score. **environment** `string` Environment label attached to the evaluation record. **metadataJson** `string` Additional attributes serialized as a JSON object. **updatedAt** `string(date-time)` Time when this record was last updated. **timestamp** `string(date-time)` Timestamp associated with the evaluation score. **traceName** `string` Trace name included with the score for display in score listings. **userId** `string` User identifier recorded with the evaluation score. **sourceLabel** `string` Original evaluation-provider source label, such as API, ANNOTATION or EVAL. Interpret it alongside source and authorship: API alone does not distinguish an end-user rating from a harness, and a source label does not independently prove verified human provenance. **conversationId** `string` Conversation identifier recorded in the score’s own metadata. Scores authored directly in the evaluation store can lack platform attribution; an empty link is not repaired by retrying. **messageId** `string` Identifier of the conversation message associated with the evaluation record. **messageSequence** `string(int64)` Sequence number of the evaluated message within its conversation. Pattern: ^-?\d+$ **profileId** `string` Identifier of the agent profile associated with the generation. **configHash** `string` Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation results. Other settings are excluded; this is not an immutable profile revision. **commentCount** `string(int64)` Number of comments reported on the evaluation object. Pattern: ^-?\d+$ **metadataJson** `string` Additional attributes serialized as a JSON object. **bookmarked** `boolean` Whether the evaluation object is bookmarked. **conversationIds** `array[string]` Conversation identifiers observed on the session’s traces; a session may span multiple conversations. Type: `string` **cursorPage** `any` Cursor pagination details accompanying this result page. All of: Variant 1: Opaque-cursor pagination details. A cursor is used to request the next page; arbitrary page-number seeking is not supported. Model reference: [CursorPageInfo](/api/models/schema-oi1c4l4i8b#response). **nextCursor** `string` Pass back as the request's `cursor` for the next page. Empty on the last page. **limit** `string(int64)` Maximum number of entries requested from the listing. Pattern: ^-?\d+$ **totalItems** `string(int64)` Total number of matching items when it can be counted exactly. Absent when the selected filters do not support an exact total. Pattern: ^-?\d+$ #### evals-listSessions-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "sessions": [ { "sessionId": "example_123", "createdAt": "2026-09-16T12:00:00Z", "durationSeconds": 1, "environment": "example", "userIds": [ "example_123" ], "traceCount": 1, "totalCost": 1, "inputTokens": "1", "outputTokens": "1", "totalTokens": "1", "traceTags": [ "example" ], "scores": [ { "scoreId": "example_123", "targetType": "EVAL_TARGET_TYPE_TRACE", "targetId": "example_123", "name": "example", "dataType": "SCORE_DATA_TYPE_NUMERIC", "numericValue": 1, "stringValue": "example", "booleanValue": true, "source": "SCORE_SOURCE_JUDGE", "comment": "example", "textValue": "Example text", "authorUserId": "example_123", "configId": "example_123", "queueId": "example_123", "traceId": "example_123", "observationId": "example_123", "sessionId": "example_123", "datasetRunId": "example_123", "environment": "example", "metadataJson": "{}", "traceName": "example", "userId": "example_123", "sourceLabel": "example", "conversationId": "example_123", "messageId": "example_123", "messageSequence": "1", "profileId": "example_123", "configHash": "example" } ], "commentCount": 1, "metadataJson": "{}", "bookmarked": true, "conversationIds": [ "example_123" ] } ], "cursorPage": { "nextCursor": "example", "limit": 1, "totalItems": 1 } } ``` Document ID: `DOC-IS-evaluation-api-listSessions`. [Section identities and revisions](/documentation-manifest.json). - List sessions: `DOC-IS-evaluation-api-listSessions#overview` - Request: `DOC-IS-evaluation-api-listSessions#request` - Responses: `DOC-IS-evaluation-api-listSessions#responses` --- # List traces URL: https://docs.travila.ai/api/evals/list-traces **POST** `/api/v1/evals/list-traces` Lists traces for the authenticated tenant, newest first — the only ordering, so an `orderBy` other than `timestamp.desc` is rejected with HTTP 400. One trace is one conversation turn. ### Filtering by entity `conversationId`, `profileId`, `userId` and `sessionId` are applied at the source, not over the returned page. Repeated entity filters intersect: `conversationId` + `profileId` returns turns in that conversation produced by that profile, not the union. `cursorPage.totalItems` is the only total any cursor-paged operation returns, and it is omitted whenever a profile, config-hash or level filter is set — that total cannot be counted exactly — or the count is unavailable. `conversationId` accepts the bare thread id — it is qualified with your verified tenant server-side, so an id held by a product surface works without the caller reconstructing the tenant-prefixed form. The `filters` array is the general filter-builder vocabulary. Entity columns there (`conversationId`, `profileId`, `configHash`, `sourceUserMessageId`) accept an exact `=` match or `any of` a set. A `level` row matches traces with at least one observation at that level. Latency, token and cost columns are aggregates over a trace and cannot be filtered here (use `list-observations`). A filter row the underlying store cannot express — an inexact operator on an entity column, an aggregate column, or an unsupported column — is rejected with HTTP 400 rather than applied to the returned page. Historical untagged traces can remain absent from entity-filtered results. The legacy tag-backfill operation has been removed; do not infer absence of a conversation from an empty tag query. ### Trace query support A profile filter cannot be combined with [`level`](/api/evals/list-traces#request-field-level), and free-text search is not implemented. Narrow the supported profile/time query instead of relying on an ignored search setting. For aggregate analysis, use supported observation-level filters to investigate one step or analyze an explicitly collected dataset. Keep the unit clear: one observation's cost is not the entire turn's cost. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Find out why a customer’s reply was slow](/insights/evaluation/reading) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for listing evaluation trace records. **pageSize** `string(int64)` Requested maximum number of entries in a result page. Pattern: ^-?\d+$ **conversationId** `string` Identifier of the conversation associated with the evaluation record. Maximum length: 256 **profileId** `string` Identifier of the agent profile associated with the operation or generation. Maximum length: 256 **userId** `string` Identifier of the end user associated with this operation or record. Maximum length: 256 **sessionId** `string` Identifier of the evaluation session grouping related traces. Maximum length: 256 **name** `string` Name used to restrict the evaluation record listing. Maximum length: 256 **environment** `string` Environment label used to select evaluation records. Maximum length: 256 **version** `string` Version label used to select evaluation records. Maximum length: 256 **release** `string` Application release label attached to evaluation records. Maximum length: 256 **tags** `array[string]` Tags used to classify or filter the evaluation record. Type: `string` **fromTime** `string(date-time)` Beginning of the time range used to select evaluation records. **toTime** `string(date-time)` End of the time range used to select evaluation records. **level** `any` Severity level used to restrict evaluation observations or traces. Diagnostic severity attached to an evaluation observation.
| Value | No. | Form | Meaning | |---|---|---|---| | `OBSERVATION_LEVEL_DEBUG` | 0 | Canonical | Detailed diagnostic information intended for debugging. | | `OBSERVATION_LEVEL_DEFAULT` | 1 | Canonical | Ordinary observation information without an elevated warning or error level. | | `OBSERVATION_LEVEL_WARNING` | 2 | Canonical | A condition reported at warning severity. | | `OBSERVATION_LEVEL_ERROR` | 3 | Canonical | A condition reported at error severity. |
Exactly one of: Variant 1: Type: `string` Enum: `OBSERVATION_LEVEL_DEBUG`, `OBSERVATION_LEVEL_DEFAULT`, `OBSERVATION_LEVEL_WARNING`, `OBSERVATION_LEVEL_ERROR` Variant 2: Type: `integer(int32)` **orderBy** `string` Ordering expression passed to the evaluation record query. Maximum length: 64 **filters** `array[llm_v1_services_eval_v1_EvalFilter]` Structured filters applied to the evaluation record query. Typed comparison operand and column selector for querying evaluation-provider records. The filter type selects which single value field is meaningful. ### Input constraints ### type Select a listed comparison type. Model reference: [EvalFilter](/api/models/schema-ovg7lvels1#request). **type** `any` **required** Discriminator selecting the evaluation filter’s operand type. Operand shape and comparison vocabulary for an evaluation-record filter. Types and operators follow the provider's v3.224.1 filter vocabulary, including keyed object variants.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_FILTER_TYPE_DATETIME` | 0 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_STRING` | 1 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_NUMBER` | 2 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_STRING_OPTIONS` | 3 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_CATEGORY_OPTIONS` | 4 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_ARRAY_OPTIONS` | 5 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_BOOLEAN` | 6 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_NULL` | 7 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_STRING_OBJECT` | 8 | Canonical | Compare a string-valued member identified by a key, such as a metadata property. STRING\_OBJECT supports metadata filtering; NUMBER\_OBJECT and BOOLEAN\_OBJECT support score filtering keyed by score name. | | `EVAL_FILTER_TYPE_NUMBER_OBJECT` | 9 | Canonical | Compare a numeric member identified by a key, such as a named score. | | `EVAL_FILTER_TYPE_BOOLEAN_OBJECT` | 10 | Canonical | Compare a boolean member identified by a key. | **`EVAL_FILTER_TYPE_DATETIME`** Compare a date-time value using ordered comparisons. \> \< >= \<= **`EVAL_FILTER_TYPE_STRING`** Compare text using equality or supported substring and prefix or suffix operators. \= contains does not contain starts with ends with **`EVAL_FILTER_TYPE_NUMBER`** Compare a numeric value using equality or ordered comparisons. \= > \< >= \<= **`EVAL_FILTER_TYPE_STRING_OPTIONS`** Match a string against a set of allowed or excluded choices. any of none of **`EVAL_FILTER_TYPE_CATEGORY_OPTIONS`** Match a category against a set of allowed or excluded choices. any of none of **`EVAL_FILTER_TYPE_ARRAY_OPTIONS`** Match array contents using any-of, none-of or all-of selection. any of none of all of **`EVAL_FILTER_TYPE_BOOLEAN`** Compare a boolean value for equality or inequality. \= \<> **`EVAL_FILTER_TYPE_NULL`** Test whether the selected property is null or non-null. is null is not null
Exactly one of: Variant 1: Type: `string` Enum: `EVAL_FILTER_TYPE_DATETIME`, `EVAL_FILTER_TYPE_STRING`, `EVAL_FILTER_TYPE_NUMBER`, `EVAL_FILTER_TYPE_STRING_OPTIONS`, `EVAL_FILTER_TYPE_CATEGORY_OPTIONS`, `EVAL_FILTER_TYPE_ARRAY_OPTIONS`, `EVAL_FILTER_TYPE_BOOLEAN`, `EVAL_FILTER_TYPE_NULL`, `EVAL_FILTER_TYPE_STRING_OBJECT`, `EVAL_FILTER_TYPE_NUMBER_OBJECT`, `EVAL_FILTER_TYPE_BOOLEAN_OBJECT` Variant 2: Type: `integer(int32)` Enum: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10` **column** `string` **required** Evaluation filter column identifier, for example traceName, scores\_avg, metadata or level. Minimum length: 1 **operator** `string` **required** Operator accepted for the selected filter type, for example contains, any of or >=. Minimum length: 1 **key** `string` Set only for the \*\_OBJECT types: the metadata key or score name. **stringValue** `string` Text operand used by a text-valued evaluation filter. **numberValue** `any` Numeric operand used by the evaluation filter. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **booleanValue** `boolean` Boolean operand used by the selected evaluation filter type. **stringValues** `array[string]` Text values used by the \*\_OPTIONS comparison types. Type: `string` **timeValue** `string(date-time)` Timestamp operand used by the evaluation filter. **searchQuery** `string` Text searched within evaluation trace records. Maximum length: 512 **searchType** `string` Search mode applied to the evaluation trace query. Maximum length: 32 **cursor** `string` Opaque cursor from the previous response’s cursor\_page.next\_cursor. Leave empty for the first page. Maximum length: 4096 #### evals-listTraces-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json {} ``` #### cookbook-insights-evaluation-reading-01-request Guide request for Find the reply the customer reported. Replace example resource identifiers with your own authorized values. ```json { "profileId": "nutrition_coach", "fromTime": "2026-08-01T00:00:00Z", "toTime": "2026-08-14T00:00:00Z", "pageSize": 25 } ``` ## Responses ### 200 — OK Content type: `application/json` Result of listing evaluation trace records. **traces** `array[llm_v1_services_eval_v1_TraceSummary]` Evaluation trace summaries included in this result page. Evaluation summary for a conversation turn, including its recorded conversation, message and profile attribution. Model reference: [TraceSummary](/api/models/schema-1k4mjul65u#response). **traceId** `string` Identifier of the evaluation trace. **name** `string` Name recorded for the evaluation trace. **timestamp** `string(date-time)` Timestamp associated with the evaluation trace. **inputJson** `string` Evaluation input serialized as JSON. **outputJson** `string` Evaluation output serialized as JSON. **latencySeconds** `any` Elapsed observation latency, in seconds. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **totalCost** `any` Total cost reported for the evaluated generation or aggregate. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **environment** `string` Environment label attached to the evaluation record. **tags** `array[string]` Labels associated with the resource for organization or filtering. Type: `string` **metadataJson** `string` Additional attributes serialized as a JSON object. **bookmarked** `boolean` Whether the evaluation object is bookmarked. **version** `string` Version of the resource represented by this message. **release** `string` Application release identifier attached to the trace. **userId** `string` Identifier of the user associated with the operation. **sessionId** `string` Identifier of the evaluation session grouping related traces. **observationCount** `string(int64)` Number of observations reported for the evaluation object. Pattern: ^-?\d+$ **conversationId** `string` Identifier of the conversation associated with the trace. **sourceUserMessageId** `string` Identifier of the user message that opened the evaluated generation turn. **profileId** `string` Identifier of the agent profile associated with the generation. **configHash** `string` Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation results. Other settings are excluded; this is not an immutable profile revision. **inputTokens** `string(int64)` Input-token usage reported for the evaluated generation. Pattern: ^-?\d+$ **outputTokens** `string(int64)` Output-token usage reported for the evaluated generation. Pattern: ^-?\d+$ **totalTokens** `string(int64)` Total token usage reported for the evaluated generation or aggregate. Pattern: ^-?\d+$ **errorCount** `string(int64)` Number of observations reported at error level. Pattern: ^-?\d+$ **warningCount** `string(int64)` Number of observations reported at warning level. Pattern: ^-?\d+$ **defaultCount** `string(int64)` Number of observations reported at the default level. Pattern: ^-?\d+$ **debugCount** `string(int64)` Number of observations reported at debug level. Pattern: ^-?\d+$ **scores** `array[llm_v1_services_eval_v1_Score]` Evaluation scores returned for the selected objects or query. Evaluation score with its value, source, target identity, and generation attribution. Model reference: [Score](/api/models/schema-1jm5lo00e7#response). **scoreId** `string` Identifier of the evaluation score. **targetType** `any` Kind of evaluation object to which the score applies. Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_TARGET_TYPE_TRACE` | 0 | Canonical | A complete trace identified by its trace identifier. | | `EVAL_TARGET_TYPE_OBSERVATION` | 1 | Canonical | A specific observation within a trace. | | `EVAL_TARGET_TYPE_DATASET_RUN` | 2 | Canonical | An evaluation run over a dataset. | | `EVAL_TARGET_TYPE_SESSION` | 3 | Canonical | A session grouping multiple traces. The evaluation harness attaches session-scoped judge scores directly; the provider does not expose a session-level evaluator target. |
Exactly one of: Variant 1: Type: `string` Enum: `EVAL_TARGET_TYPE_TRACE`, `EVAL_TARGET_TYPE_OBSERVATION`, `EVAL_TARGET_TYPE_DATASET_RUN`, `EVAL_TARGET_TYPE_SESSION` Variant 2: Type: `integer(int32)` **targetId** `string` Identifier of the evaluation object to which the score applies. **name** `string` Metric name identifying the recorded evaluation score. **dataType** `any` Value type used to interpret numeric, categorical, Boolean, or text score values. Scores Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_DATA_TYPE_NUMERIC` | 0 | Canonical | A numeric measurement or rating. | | `SCORE_DATA_TYPE_CATEGORICAL` | 1 | Canonical | A value chosen from a named set of categories. | | `SCORE_DATA_TYPE_BOOLEAN` | 2 | Canonical | A true-or-false evaluation result. | | `SCORE_DATA_TYPE_TEXT` | 3 | Canonical | Free-form text supplied by an evaluator or reviewer. The provider supports text values on score definitions and scores; support through this API depends on the operation. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_DATA_TYPE_NUMERIC`, `SCORE_DATA_TYPE_CATEGORICAL`, `SCORE_DATA_TYPE_BOOLEAN`, `SCORE_DATA_TYPE_TEXT` Variant 2: Type: `integer(int32)` **numericValue** `any` Numeric score value reported by the evaluator. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stringValue** `string` Category label recorded for a categorical evaluation score. **booleanValue** `boolean` Boolean value recorded for a Boolean evaluation score. **source** `any` Source classification reported for the evaluation score. Platform classification of who produced an evaluation score. The provider source label retains its original vocabulary: writes accept API or ANNOTATION, while EVAL is reserved for the provider's internal evaluators and is rejected through its public API. SCORE\_SOURCE\_HUMAN maps to ANNOTATION. SCORE\_SOURCE\_USER, SCORE\_SOURCE\_JUDGE and SCORE\_SOURCE\_HARNESS map to API. Reviewer and end-user scores also use separate name namespaces: reviewer scores do not use names beginning with user-feedback-.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_SOURCE_JUDGE` | 0 | Canonical | A score produced by an automated judge. | | `SCORE_SOURCE_HUMAN` | 1 | Canonical | A score entered by a human reviewer through the annotation path. | | `SCORE_SOURCE_USER` | 2 | Canonical | Feedback supplied by an end user. | | `SCORE_SOURCE_HARNESS` | 3 | Canonical | A score written by an evaluation harness or another API-based producer. | | `SCORE_SOURCE_EVAL` | 4 | Canonical | A read-only score produced by the evaluation provider's managed evaluators; it cannot be written through the public score API. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_SOURCE_JUDGE`, `SCORE_SOURCE_HUMAN`, `SCORE_SOURCE_USER`, `SCORE_SOURCE_HARNESS`, `SCORE_SOURCE_EVAL` Variant 2: Type: `integer(int32)` **comment** `string` Explanatory text attached to the evaluation score. **createdAt** `string(date-time)` Time when this record was created. **textValue** `string` Text value of the evaluation score. **authorUserId** `string` Identifier recorded for the user who authored the score. A stored author identifier alone does not attest to verified human provenance. **configId** `string` Identifier of the score configuration defining the score’s value domain. **queueId** `string` Identifier of the annotation queue. **traceId** `string` Identifier of the evaluation trace. **observationId** `string` Identifier of the evaluation observation. **sessionId** `string` Identifier of the evaluation session grouping related traces. **datasetRunId** `string` Identifier of the dataset run associated with the score. **environment** `string` Environment label attached to the evaluation record. **metadataJson** `string` Additional attributes serialized as a JSON object. **updatedAt** `string(date-time)` Time when this record was last updated. **timestamp** `string(date-time)` Timestamp associated with the evaluation score. **traceName** `string` Trace name included with the score for display in score listings. **userId** `string` User identifier recorded with the evaluation score. **sourceLabel** `string` Original evaluation-provider source label, such as API, ANNOTATION or EVAL. Interpret it alongside source and authorship: API alone does not distinguish an end-user rating from a harness, and a source label does not independently prove verified human provenance. **conversationId** `string` Conversation identifier recorded in the score’s own metadata. Scores authored directly in the evaluation store can lack platform attribution; an empty link is not repaired by retrying. **messageId** `string` Identifier of the conversation message associated with the evaluation record. **messageSequence** `string(int64)` Sequence number of the evaluated message within its conversation. Pattern: ^-?\d+$ **profileId** `string` Identifier of the agent profile associated with the generation. **configHash** `string` Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation results. Other settings are excluded; this is not an immutable profile revision. **commentCount** `string(int64)` Number of comments reported on the evaluation object. Pattern: ^-?\d+$ **contentRedacted** `boolean` Whether returned trace content is redacted. Redaction occurs before the trace is recorded, so its text is not a faithful copy of the conversation store. **cursorPage** `any` Cursor pagination details accompanying this result page. All of: Variant 1: Opaque-cursor pagination details. A cursor is used to request the next page; arbitrary page-number seeking is not supported. Model reference: [CursorPageInfo](/api/models/schema-oi1c4l4i8b#response). **nextCursor** `string` Pass back as the request's `cursor` for the next page. Empty on the last page. **limit** `string(int64)` Maximum number of entries requested from the listing. Pattern: ^-?\d+$ **totalItems** `string(int64)` Total number of matching items when it can be counted exactly. Absent when the selected filters do not support an exact total. Pattern: ^-?\d+$ #### evals-listTraces-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "traces": [ { "traceId": "example_123", "name": "example", "timestamp": "2026-09-16T12:00:00Z", "inputJson": "{}", "outputJson": "{}", "latencySeconds": 1, "totalCost": 1, "environment": "example", "tags": [ "example" ], "metadataJson": "{}", "bookmarked": true, "version": "example", "release": "example", "userId": "example_123", "sessionId": "example_123", "observationCount": 1, "conversationId": "example_123", "sourceUserMessageId": "example_123", "profileId": "example_123", "configHash": "example", "inputTokens": "1", "outputTokens": "1", "totalTokens": "1", "errorCount": 1, "warningCount": 1, "defaultCount": 1, "debugCount": 1, "scores": [ { "scoreId": "example_123", "targetType": "EVAL_TARGET_TYPE_TRACE", "targetId": "example_123", "name": "example", "dataType": "SCORE_DATA_TYPE_NUMERIC", "numericValue": 1, "stringValue": "example", "booleanValue": true, "source": "SCORE_SOURCE_JUDGE", "comment": "example", "textValue": "Example text", "authorUserId": "example_123", "configId": "example_123", "queueId": "example_123", "traceId": "example_123", "observationId": "example_123", "sessionId": "example_123", "datasetRunId": "example_123", "environment": "example", "metadataJson": "{}", "traceName": "example", "userId": "example_123", "sourceLabel": "example", "conversationId": "example_123", "messageId": "example_123", "messageSequence": "1", "profileId": "example_123", "configHash": "example" } ], "commentCount": 1 } ], "contentRedacted": true, "cursorPage": { "nextCursor": "example", "limit": 1, "totalItems": 1 } } ``` Document ID: `DOC-IS-evaluation-api-listTraces`. [Section identities and revisions](/documentation-manifest.json). - List traces: `DOC-IS-evaluation-api-listTraces#overview` - Request: `DOC-IS-evaluation-api-listTraces#request` - Responses: `DOC-IS-evaluation-api-listTraces#responses` --- # Record a score URL: https://docs.travila.ai/api/evals/record-score **POST** `/api/v1/evals/record-score` Records a tenant-side reviewer/operator score. ### Resolving the rated turn Turn addressing is trace-only. A bare conversation ID is qualified with trusted tenant context. Messages without the required historical addressing metadata can be rejected; use an independently verified trace ID in that case. The API assigns human-source classification and derives rater context from trusted credentials, not the body. A machine key does not identify a human reviewer. A deterministic per-rater/target/name score ID supports replacing a rating, but the current delete operation does not enforce author ownership. ### Supported ratings Use a trace target with numeric or boolean values. The current API maps the resolved target into `traceId`; categorical/text values and observation/session/dataset-run targets in the schema are not faithfully supported. Use the supported trace/value combinations shown here. ### Examples The request examples below show a numeric score of 0.9 for a trace target and a configured helpfulness rating with an explanatory comment. Use your verified trace target and applicable score configuration; the example identifiers are illustrative. ### Re-rating and withdrawing A stable per-rater/target/name score ID does not alone guarantee one current record across dates. The current API omits the original creation timestamp needed for cross-day replacement. Verify read-back after retries or re-rating. Withdrawal must check creator and scope; delete-score currently lacks that creator check and must remain restricted to trusted operators. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Review and score turns](/insights/evaluation/review) · [Feedback and score attribution](/api/evals/scoring) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for recording an evaluation score. Supply exactly one target address: target\_id, message\_id, or both conversation\_id and source\_user\_message\_id. Authorship comes from the authenticated caller; the score source is assigned for this reviewer operation rather than selected by the request. **targetType** `any` **required** Kind of evaluation object to which the score applies. Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_TARGET_TYPE_TRACE` | 0 | Canonical | A complete trace identified by its trace identifier. | | `EVAL_TARGET_TYPE_OBSERVATION` | 1 | Canonical | A specific observation within a trace. | | `EVAL_TARGET_TYPE_DATASET_RUN` | 2 | Canonical | An evaluation run over a dataset. | | `EVAL_TARGET_TYPE_SESSION` | 3 | Canonical | A session grouping multiple traces. The evaluation harness attaches session-scoped judge scores directly; the provider does not expose a session-level evaluator target. |
Exactly one of: Variant 1: Type: `string` Enum: `EVAL_TARGET_TYPE_TRACE`, `EVAL_TARGET_TYPE_OBSERVATION`, `EVAL_TARGET_TYPE_DATASET_RUN`, `EVAL_TARGET_TYPE_SESSION` Variant 2: Type: `integer(int32)` Enum: `0`, `1`, `2`, `3` **targetId** `string` Not required — a caller may address by message or by turn instead. **name** `string` **required** Name identifying the scoring dimension recorded for the evaluation target. Minimum length: 1 **dataType** `any` **required** Value type used to interpret the evaluation score. Scores Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_DATA_TYPE_NUMERIC` | 0 | Canonical | A numeric measurement or rating. | | `SCORE_DATA_TYPE_CATEGORICAL` | 1 | Canonical | A value chosen from a named set of categories. | | `SCORE_DATA_TYPE_BOOLEAN` | 2 | Canonical | A true-or-false evaluation result. | | `SCORE_DATA_TYPE_TEXT` | 3 | Canonical | Free-form text supplied by an evaluator or reviewer. The provider supports text values on score definitions and scores; support through this API depends on the operation. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_DATA_TYPE_NUMERIC`, `SCORE_DATA_TYPE_CATEGORICAL`, `SCORE_DATA_TYPE_BOOLEAN`, `SCORE_DATA_TYPE_TEXT` Variant 2: Type: `integer(int32)` Enum: `0`, `1`, `2`, `3` **numericValue** `any` Numeric score value for a numeric score configuration. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **stringValue** `string` Category value for a categorical evaluation score. **booleanValue** `boolean` Boolean value for a boolean evaluation score. **textValue** `string` Free-text value for a text evaluation score. **comment** `string` Explanatory note accompanying the evaluation score. **configId** `string` Score configuration selected from ListScoreConfigs. Required for this reviewer operation; a missing configuration is rejected. **profileId** `string` Identifier of the agent profile associated with the operation or generation. **messageId** `string` Identifier of the conversation message to score. Supply this instead of target\_id or a conversation\_id and source\_user\_message\_id pair. Maximum length: 256 **conversationId** `string` Identifier of the conversation associated with the evaluation record. Maximum length: 256 **sourceUserMessageId** `string` Identifier of the user message that originated the evaluated generation. Maximum length: 256 #### evals-recordScore-request Score an existing trace as an authenticated rater; this numeric example records 0.9. ```json { "targetType": "EVAL_TARGET_TYPE_TRACE", "targetId": "trace_123", "name": "answer-quality", "dataType": "SCORE_DATA_TYPE_NUMERIC", "numericValue": 0.9 } ``` #### cookbook-insights-evaluation-review-05-request Guide request for 3. Record the rating. Replace example resource identifiers with your own authorized values. ```json { "targetType": "EVAL_TARGET_TYPE_TRACE", "targetId": "…", "name": "helpfulness", "dataType": "SCORE_DATA_TYPE_NUMERIC", "numericValue": 4, "configId": "cfg_helpfulness", "comment": "Accurate, but buried the answer in three paragraphs." } ``` ## Responses ### 200 — OK Content type: `application/json` Result of recording a score attached to an evaluation object. **scoreId** `string` Identifier of the recorded evaluation score. **targetId** `string` Resolved evaluation-object identifier, returned so a caller that addressed a message can use the object identity in later requests. **targetType** `any` Kind of evaluation object targeted by the score. Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_TARGET_TYPE_TRACE` | 0 | Canonical | A complete trace identified by its trace identifier. | | `EVAL_TARGET_TYPE_OBSERVATION` | 1 | Canonical | A specific observation within a trace. | | `EVAL_TARGET_TYPE_DATASET_RUN` | 2 | Canonical | An evaluation run over a dataset. | | `EVAL_TARGET_TYPE_SESSION` | 3 | Canonical | A session grouping multiple traces. The evaluation harness attaches session-scoped judge scores directly; the provider does not expose a session-level evaluator target. |
Exactly one of: Variant 1: Type: `string` Enum: `EVAL_TARGET_TYPE_TRACE`, `EVAL_TARGET_TYPE_OBSERVATION`, `EVAL_TARGET_TYPE_DATASET_RUN`, `EVAL_TARGET_TYPE_SESSION` Variant 2: Type: `integer(int32)` #### evals-recordScore-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "scoreId": "example_123", "targetId": "example_123", "targetType": "EVAL_TARGET_TYPE_TRACE" } ``` Document ID: `DOC-IS-evaluation-api-recordScore`. [Section identities and revisions](/documentation-manifest.json). - Record a score: `DOC-IS-evaluation-api-recordScore#overview` - Request: `DOC-IS-evaluation-api-recordScore#request` - Responses: `DOC-IS-evaluation-api-recordScore#responses` --- # Update a dataset item URL: https://docs.travila.ai/api/evals/update-dataset-item **POST** `/api/v1/evals/update-dataset-item` Edits an item — typically to fill in `expectedOutputJson` after review. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Replay datasets and runs](/insights/evaluation/datasets-and-runs) · [Dataset identity and run provenance](/api/evals/datasets) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for updating an input and expected-output pair in an evaluation dataset. **itemId** `string` **required** Identifier of the evaluation dataset item being updated. Minimum length: 1 **datasetId** `string` **required** Identifier of the evaluation dataset. Minimum length: 1 **inputJson** `string` Dataset item input serialized as JSON text. **expectedOutputJson** `string` Expected dataset item output serialized as JSON text. **metadataJson** `string` Additional evaluation metadata serialized as JSON text. **status** `any` Whether the evaluation dataset item is active or archived. Whether a dataset item is active or retained as archived content.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATASET_ITEM_STATUS_ACTIVE` | 0 | Canonical | The dataset item is active. | | `DATASET_ITEM_STATUS_ARCHIVED` | 1 | Canonical | The dataset item is archived and retained as historical content. |
Exactly one of: Variant 1: Type: `string` Enum: `DATASET_ITEM_STATUS_ACTIVE`, `DATASET_ITEM_STATUS_ARCHIVED` Variant 2: Type: `integer(int32)` #### evals-updateDatasetItem-request Replace an existing item using its dataset name; retain the input when revising its expected output. ```json { "itemId": "item_123", "datasetId": "support-answers", "inputJson": "{\"question\":\"How do I reset my password?\"}", "expectedOutputJson": "\"Use the password reset link on the sign-in page.\"" } ``` #### cookbook-insights-evaluation-datasets-and-runs-04-request Guide request for 3. Define what an acceptable answer must do. Replace example resource identifiers with your own authorized values. ```json { "itemId": "…", "datasetId": "support-assistant-regressions", "expectedOutputJson": "{\"answer\": \"…\"}" } ``` ## Responses ### 200 — OK Content type: `application/json` Result of updating an input and expected-output pair in an evaluation dataset. **itemId** `string` Identifier of the evaluation dataset item updated by the operation. #### evals-updateDatasetItem-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "itemId": "example_123" } ``` Document ID: `DOC-IS-evaluation-api-updateDatasetItem`. [Section identities and revisions](/documentation-manifest.json). - Update a dataset item: `DOC-IS-evaluation-api-updateDatasetItem#overview` - Request: `DOC-IS-evaluation-api-updateDatasetItem#request` - Responses: `DOC-IS-evaluation-api-updateDatasetItem#responses` --- # Update a score config URL: https://docs.travila.ai/api/evals/update-score-config **POST** `/api/v1/evals/update-score-config` Edits a score config, and archives one via `isArchived`. Optional fields are omitted rather than zeroed, so leaving a field out means "leave it alone" rather than "set it to zero". The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Review and score turns](/insights/evaluation/review) · [Feedback and score attribution](/api/evals/scoring) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Partial update of a score configuration. Unset fields retain their values; is\_archived changes archival state. The score data type and categories cannot be changed through this request. **configId** `string` **required** Identifier of the evaluation score configuration. Minimum length: 1 **name** `string` Replacement name for the score configuration. Minimum length: 1 **description** `string` Human-readable explanation of the evaluation record. **minValue** `any` Lower numeric bound for the score range. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxValue** `any` Upper numeric bound for the score range. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **isArchived** `boolean` Whether the score configuration is marked as archived. #### evals-updateScoreConfig-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "configId": "example_123", "name": "example" } ``` ## Responses ### 200 — OK Content type: `application/json` Result of updating the definition and allowed values of an evaluation score. **config** `any` Score configuration returned after the update. All of: Variant 1: Score definition specifying its value type, bounds, and allowed categories. Model reference: [ScoreConfig](/api/models/schema-1k2h0fdd77#response). **configId** `string` Identifier of the score configuration defining the score’s value domain. **name** `string` Name identifying the score definition. **dataType** `any` Value type used to interpret numeric, categorical, Boolean, or text score values. Scores Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_DATA_TYPE_NUMERIC` | 0 | Canonical | A numeric measurement or rating. | | `SCORE_DATA_TYPE_CATEGORICAL` | 1 | Canonical | A value chosen from a named set of categories. | | `SCORE_DATA_TYPE_BOOLEAN` | 2 | Canonical | A true-or-false evaluation result. | | `SCORE_DATA_TYPE_TEXT` | 3 | Canonical | Free-form text supplied by an evaluator or reviewer. The provider supports text values on score definitions and scores; support through this API depends on the operation. |
Exactly one of: Variant 1: Type: `string` Enum: `SCORE_DATA_TYPE_NUMERIC`, `SCORE_DATA_TYPE_CATEGORICAL`, `SCORE_DATA_TYPE_BOOLEAN`, `SCORE_DATA_TYPE_TEXT` Variant 2: Type: `integer(int32)` **description** `string` Human-readable description of the resource. **minValue** `any` Minimum numeric score value allowed by the score configuration. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **maxValue** `any` Maximum numeric score value allowed by the score configuration. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **categories** `array[llm_v1_services_eval_v1_ScoreConfigCategory]` Named score categories defined by the score configuration. Named category and associated numeric value in a categorical score definition. Model reference: [ScoreConfigCategory](/api/models/schema-1k0g6fhhqd#response). **label** `string` Label identifying this score category. **value** `any` Numeric score value associated with this named category. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` **isArchived** `boolean` Whether the score configuration is archived. Archived configurations are retained so historical scores remain interpretable. **createdAt** `string(date-time)` Time when this record was created. **updatedAt** `string(date-time)` Time when this record was last updated. #### evals-updateScoreConfig-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "config": { "configId": "example_123", "name": "example", "dataType": "SCORE_DATA_TYPE_NUMERIC", "description": "example", "minValue": 1, "maxValue": 1, "categories": [ { "label": "example", "value": 1 } ], "isArchived": true, "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z" } } ``` Document ID: `DOC-IS-evaluation-api-updateScoreConfig`. [Section identities and revisions](/documentation-manifest.json). - Update a score config: `DOC-IS-evaluation-api-updateScoreConfig#overview` - Request: `DOC-IS-evaluation-api-updateScoreConfig#request` - Responses: `DOC-IS-evaluation-api-updateScoreConfig#responses` --- # LLMMessagePublishedEvent {#overview} URL: https://docs.travila.ai/api/events/u1s768tpmf Domain event published when a new assistant/tool message is produced. Use this in a guide: [Event catalog](/api/events) · [Automate recurring agent work](/core-platform/scheduling/build-scheduled-agents) ## Payload {#payload} Payload fields: [LLMMessagePublishedEvent](/api/models/schema-po1qsocerv). ## Payload examples {#examples} These are illustrations of the selected payload Schema, not complete delivery envelopes. Transport metadata is supplied by the platform. ### event-llm-message-published {#example-event-llm-message-published} Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event. API JSON uses JSON field names (camelCase). ```json { "message": { "role": "ROLE_ASSISTANT", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Here is your daily briefing." } ], "messageId": "924ad207-f757-4b1f-bf41-8344ce32dd01", "sequence": "2", "generatedBy": "9d4c2e1f-27b1-4304-ae54-af7fe876df31" } } ``` ## Notes {#notes} In the live conversation view, messages append to the message history. Message sequence identifies each entry; repeated delivery updates the same entry. Event-specific delivery guarantees, ordering, retention and lifecycle status are unspecified. ## Audiences {#audiences} - Audience: Live view Current conversation client projection. - Audience: Tenant webhook Sent to subscribed tenant webhook endpoints. ## Delivery and lifecycle {#declared-intent} - Live write intent: Append ## Live destination meaning {#live-destination-meaning} Conversation message view, with each message addressed by its sequence. ## Live child key meaning {#live-child-key-meaning} Message sequence identifies the entry; repeated delivery updates that same entry. --- # LLMGenerationCompletedEvent {#overview} URL: https://docs.travila.ai/api/events/u1u0sjgmch Event emitted when a generation run reaches a terminal state. The event context identifies the associated conversation. Use this in a guide: [Integrations](/integrations) · [API Reference](/api) · [Event catalog](/api/events) · [Update your backend when an assistant finishes](/integrations/webhooks) ## Payload {#payload} Payload fields: [LLMGenerationCompletedEvent](/api/models/schema-pntuu08p80). ## Payload examples {#examples} These are illustrations of the selected payload Schema, not complete delivery envelopes. Transport metadata is supplied by the platform. ### event-llm-generation-completed {#example-event-llm-generation-completed} Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event. API JSON uses JSON field names (camelCase). ```json { "runId": "9d4c2e1f-27b1-4304-ae54-af7fe876df31", "status": "WORKFLOW_STATUS_COMPLETED", "loopCount": 1, "durationMs": "1250", "usage": { "promptTokens": 412, "completionTokens": 88, "totalTokens": 500 } } ``` ## Notes {#notes} In the live view, this event replaces the status view for the individual generation run within its conversation. Event-specific delivery guarantees, ordering, retention and lifecycle status are unspecified. ## Audiences {#audiences} - Audience: Live view Current conversation client projection. - Audience: Tenant webhook Sent to subscribed tenant webhook endpoints. ## Delivery and lifecycle {#declared-intent} - Live write intent: Replace ## Live destination meaning {#live-destination-meaning} Status view for the individual generation run within its conversation. --- # LLMGenerationStartedEvent {#overview} URL: https://docs.travila.ai/api/events/u20phhssrl Event emitted when a generation run starts. The event context identifies the associated conversation. Use this in a guide: [Event catalog](/api/events) ## Payload {#payload} Payload fields: [LLMGenerationStartedEvent](/api/models/schema-pnv14jb39g). ## Payload examples {#examples} These are illustrations of the selected payload Schema, not complete delivery envelopes. Transport metadata is supplied by the platform. ### event-llm-generation-started {#example-event-llm-generation-started} Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event. API JSON uses JSON field names (camelCase). ```json { "runId": "9d4c2e1f-27b1-4304-ae54-af7fe876df31", "startingSequence": "1" } ``` ## Notes {#notes} In the live view, this event replaces the status view for the individual generation run within its conversation. Event-specific delivery guarantees, ordering, retention and lifecycle status are unspecified. ## Audiences {#audiences} - Audience: Live view Current conversation client projection. - Audience: Tenant webhook Sent to subscribed tenant webhook endpoints. ## Delivery and lifecycle {#declared-intent} - Live write intent: Replace ## Live destination meaning {#live-destination-meaning} Status view for the individual generation run within its conversation. --- # ToolCallStartedEvent {#overview} URL: https://docs.travila.ai/api/events/u22bdqd1kd Event for a tool call that has begun execution or is waiting for human approval. Check the event name and tool-call status to distinguish these cases; the event context identifies the conversation. Use this in a guide: [Event catalog](/api/events) · [Tool policy resolution and lifecycle](/api/tool-execution/policies) ## Payload {#payload} Payload fields: [ToolCallStartedEvent](/api/models/schema-po5rioe4il). ## Payload examples {#examples} These are illustrations of the selected payload Schema, not complete delivery envelopes. Transport metadata is supplied by the platform. ### event-llm-tool-call-started {#example-event-llm-tool-call-started} Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event. API JSON uses JSON field names (camelCase). ```json { "toolCall": { "id": "call_123", "name": "send_briefing", "serverId": "briefing-tools", "argumentsJson": { "conversation_id": "b81d5345-c1f9-4fb9-b558-a6327c75b842" }, "status": "TOOL_EXECUTION_STATUS_EXECUTING" } } ``` ### event-llm-tool-call-approval-required {#example-event-llm-tool-call-approval-required} Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event. API JSON uses JSON field names (camelCase). ```json { "toolCall": { "id": "call_123", "name": "send_briefing", "serverId": "briefing-tools", "argumentsJson": { "conversation_id": "b81d5345-c1f9-4fb9-b558-a6327c75b842" }, "status": "TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION", "requiresApprovalAt": "2026-09-16T12:05:00Z" } } ``` ## Notes {#notes} In the live view, this event replaces the current tool activity view for the conversation. The payload can represent execution starting or a request for human approval; use the event name and tool-call status to distinguish these cases. Event-specific delivery guarantees, ordering, retention and lifecycle status are unspecified. ## Audiences {#audiences} - Audience: Live view Current conversation client projection. - Audience: Tenant webhook Sent to subscribed tenant webhook endpoints. ## Delivery and lifecycle {#declared-intent} - Live write intent: Replace ## Live destination meaning {#live-destination-meaning} Current tool activity view for the conversation. --- # ToolCallCompletedEvent {#overview} URL: https://docs.travila.ai/api/events/u249vf7739 Event emitted when a tool call reaches COMPLETED, FAILED, CANCELLED or TIMED\_OUT, including calls that required human approval. Use this in a guide: [Event catalog](/api/events) ## Payload {#payload} Payload fields: [ToolCallCompletedEvent](/api/models/schema-po3pkfshjg). ## Payload examples {#examples} These are illustrations of the selected payload Schema, not complete delivery envelopes. Transport metadata is supplied by the platform. ### event-llm-tool-call-completed {#example-event-llm-tool-call-completed} Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event. API JSON uses JSON field names (camelCase). ```json { "executionTimeMs": 240, "toolCall": { "id": "call_123", "name": "send_briefing", "serverId": "briefing-tools", "argumentsJson": { "conversation_id": "b81d5345-c1f9-4fb9-b558-a6327c75b842" }, "status": "TOOL_EXECUTION_STATUS_COMPLETED", "resultJson": { "accepted": true } } } ``` ## Notes {#notes} In the live view, this event replaces the current tool activity view for the conversation. Event-specific delivery guarantees, ordering, retention and lifecycle status are unspecified. ## Audiences {#audiences} - Audience: Live view Current conversation client projection. - Audience: Tenant webhook Sent to subscribed tenant webhook endpoints. ## Delivery and lifecycle {#declared-intent} - Live write intent: Replace ## Live destination meaning {#live-destination-meaning} Current tool activity view for the conversation. --- # Register a custom MCP server URL: https://docs.travila.ai/api/mcp-servers/create-custom-mcp-server **POST** `/api/v1/mcp-servers/create` Registers an HTTP MCP server in the caller's project. A duplicate server ID fails with `409`; use [update](/api/mcp-servers/update-custom-mcp-server) to replace the record. Configuration validation and the egress guard run before storage. Invalid configuration, a referenced secret absent from this project, or an attempt to create at the configured project limit (20 servers by default) returns `400`. Concurrent creates can exceed this count-before-create limit. Secret existence is checked at write time so a missing credential is reported before the first tool call. Endpoint restrictions also apply when connecting; an HTTPS URL alone does not establish a safe destination. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for registering a tenant-owned MCP server and its connection configuration. **projectId** `string` Empty → "default" **server** `any` **required** MCP server configuration to register. All of: Variant 1: A project-scoped, HTTP-only MCP server definition, keyed (tenant\_id, project\_id, server\_id). Its wire ID is "custom:\{server\_id}". Credentials must be stored as secret references; inline tokens must not be persisted in this server definition. auth\_type selects the required credential fields. Authenticated modes require auth\_secret\_ref; NONE requires it to be empty. HEADER requires auth\_header\_name and QUERY requires auth\_query\_param; those names must be empty for every other mode. Inconsistent combinations are rejected before storage. Inline credentials are not accepted. ### Input constraints ### server\_id The server\_id must contain one through 63 characters. Its first character must be a lowercase ASCII letter or digit. Every remaining character must be a lowercase ASCII letter, digit, or hyphen. ### auth\_header\_name The auth\_header\_name may be empty text. Otherwise it must contain one through 128 characters, each an ASCII letter, digit, or one of these literal punctuation characters: ! # $ % & ' \* + . ^ \_ \` | \~ -. No other character is accepted. ### auth\_query\_param The auth\_query\_param may be empty text. Otherwise it must contain one through 128 characters, each an ASCII letter, digit, period, underscore, tilde, or hyphen. No other character is accepted. ### request\_timeout The request\_timeout duration must be no greater than 120 seconds. Model reference: [CustomMCPServer](/api/models/schema-p1cuh9jgfq#request). **serverId** `string` **required** Unique within the project. Pattern: ^[a-z0-9][a-z0-9-]{0,62}$ **displayName** `string` Display name used for the registered MCP server. Maximum length: 200 **description** `string` Human-readable description of the resource. Maximum length: 1024 **endpoint** `string(uri)` **required** HTTPS endpoint for Streamable HTTP; local and standard-input/output transports are unsupported. The egress guard also rejects prohibited destinations such as metadata, loopback, private-network and in-cluster addresses. HTTPS alone does not satisfy these destination checks. Maximum length: 2048 Pattern: ^https:// **authType** `any` Authentication mechanism configured for the MCP server. How credentials are attached to requests to a tenant-configured MCP server. Credentials are held by reference; inline credential values are neither accepted nor persisted.
| Value | No. | Form | Meaning | |---|---|---|---| | `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE` | 0 | Canonical | Send requests without attaching a secret for authentication. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER` | 1 | Canonical | See meaning below. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER` | 2 | Canonical | See meaning below. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` | 3 | Canonical | See meaning below. | **`CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER`** Send the secret as a Bearer token in the Authorization header. Authorization: Bearer \ Exactly one of: Variant 1: Type: `string` Enum: `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE`, `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER`, `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER`, `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` Variant 2: Type: `integer(int32)` Enum: `0`, `1`, `2`, `3` **authSecretRef** `any` Required credential reference for BEARER, HEADER and QUERY authentication. Resolves within this server's tenant and project; only the secret name is returned, never its value. All of: Variant 1: Reference to a secret within the same tenant and project as the resource that uses it. Cross-project and cross-tenant secret references are not supported. Secret values are write-only through the project secret API: writes accept a value and return metadata, while read operations return metadata without the value. Resource references name a secret within their own scope rather than carrying its value or an alternate tenant or project. ### Input constraints ### name The name must contain one through 63 characters. Its first character must be a lowercase ASCII letter or digit. Every remaining character must be a lowercase ASCII letter, digit, period, underscore, or hyphen. Model reference: [SecretRef](/api/models/schema-opqho625u2#request). **name** `string` **required** Name identifying the secret within its project. Pattern: ^[a-z0-9][a-z0-9._-]{0,62}$ **authHeaderName** `string` Name of the custom authentication header. The egress guard also rejects protected header names; satisfying the field's character pattern alone does not permit every header. Pattern: ^([A-Za-z0-9!#$%&'*+.^_`|~-]{1,128})?$ **authQueryParam** `string` Required for QUERY auth; the vendor's parameter name (e.g. "tavilyApiKey"). Restricted to RFC 3986 unreserved characters, which is NOT the same set as auth\_header\_name's RFC 7230 tchar: that set contains '&' (would append a second parameter), '#' (would truncate the URL at a fragment), '%' (would open a malformed escape) and '+' (decodes as a space). The query-parameter name uses its own character set. Empty is allowed — populated only for QUERY auth. Pattern: ^([A-Za-z0-9._~-]{1,128})?$ **enabled** `boolean` Whether this configuration is enabled. **requestTimeout** `string` Time allowed for a remote request. Omission or a nonpositive duration uses 30 seconds; positive durations below one second are raised to one second. Long waits can delay the conversation while the remote server is unavailable. Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **version** `string(int64)` Output-only revision assigned by the store and incremented on updates. Ignored on writes. Pattern: ^-?\d+$ **createdBy** `string` Output-only identity of the caller that registered the server. Ignored on writes. **createdAt** `string(date-time)` Output-only creation time assigned by the store. Ignored on writes. **updatedAt** `string(date-time)` Output-only last-update time assigned by the store. Ignored on writes. #### mcp-servers-createCustomMcpServer-request Register an enabled server without authentication; replace the example endpoint with your reachable MCP endpoint. ```json { "server": { "serverId": "product-tools", "displayName": "Product tools", "endpoint": "https://mcp.example.com/mcp", "authType": "CUSTOM_MCP_SERVER_AUTH_TYPE_NONE", "enabled": true } } ``` #### cookbook-integrations-tools-connections-custom-mcp-servers-02-request Guide request for 2. Register the service you want Travila to call. Replace example resource identifiers with your own authorized values. ```json { "server": { "serverId": "firecrawl", "displayName": "Firecrawl", "description": "BYO web scraping MCP", "endpoint": "https://mcp.firecrawl.dev/v2/mcp", "authType": "CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER", "authSecretRef": { "name": "firecrawl-api-key" }, "enabled": true, "requestTimeout": "30s" } } ``` ## Responses ### 200 — Server registered; the stored record is echoed back Content type: `application/json` Result payload for registering a tenant-owned MCP server and its connection configuration. **server** `any` MCP server configuration returned after registration. All of: Variant 1: A project-scoped, HTTP-only MCP server definition, keyed (tenant\_id, project\_id, server\_id). Its wire ID is "custom:\{server\_id}". Credentials must be stored as secret references; inline tokens must not be persisted in this server definition. auth\_type selects the required credential fields. Authenticated modes require auth\_secret\_ref; NONE requires it to be empty. HEADER requires auth\_header\_name and QUERY requires auth\_query\_param; those names must be empty for every other mode. Inconsistent combinations are rejected before storage. Inline credentials are not accepted. ### Input constraints ### server\_id The server\_id must contain one through 63 characters. Its first character must be a lowercase ASCII letter or digit. Every remaining character must be a lowercase ASCII letter, digit, or hyphen. ### auth\_header\_name The auth\_header\_name may be empty text. Otherwise it must contain one through 128 characters, each an ASCII letter, digit, or one of these literal punctuation characters: ! # $ % & ' \* + . ^ \_ \` | \~ -. No other character is accepted. ### auth\_query\_param The auth\_query\_param may be empty text. Otherwise it must contain one through 128 characters, each an ASCII letter, digit, period, underscore, tilde, or hyphen. No other character is accepted. ### request\_timeout The request\_timeout duration must be no greater than 120 seconds. Model reference: [CustomMCPServer](/api/models/schema-p1cuh9jgfq#response). **serverId** `string` Unique within the project. **displayName** `string` Display name used for the registered MCP server. **description** `string` Human-readable description of the resource. **endpoint** `string` HTTPS endpoint for Streamable HTTP; local and standard-input/output transports are unsupported. The egress guard also rejects prohibited destinations such as metadata, loopback, private-network and in-cluster addresses. HTTPS alone does not satisfy these destination checks. **authType** `any` Authentication mechanism configured for the MCP server. How credentials are attached to requests to a tenant-configured MCP server. Credentials are held by reference; inline credential values are neither accepted nor persisted.
| Value | No. | Form | Meaning | |---|---|---|---| | `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE` | 0 | Canonical | Send requests without attaching a secret for authentication. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER` | 1 | Canonical | See meaning below. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER` | 2 | Canonical | See meaning below. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` | 3 | Canonical | See meaning below. | **`CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER`** Send the secret as a Bearer token in the Authorization header. Authorization: Bearer \ Exactly one of: Variant 1: Type: `string` Enum: `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE`, `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER`, `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER`, `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` Variant 2: Type: `integer(int32)` **authSecretRef** `any` Required credential reference for BEARER, HEADER and QUERY authentication. Resolves within this server's tenant and project; only the secret name is returned, never its value. All of: Variant 1: Reference to a secret within the same tenant and project as the resource that uses it. Cross-project and cross-tenant secret references are not supported. Secret values are write-only through the project secret API: writes accept a value and return metadata, while read operations return metadata without the value. Resource references name a secret within their own scope rather than carrying its value or an alternate tenant or project. ### Input constraints ### name The name must contain one through 63 characters. Its first character must be a lowercase ASCII letter or digit. Every remaining character must be a lowercase ASCII letter, digit, period, underscore, or hyphen. Model reference: [SecretRef](/api/models/schema-opqho625u2#response). **name** `string` Name identifying the secret within its project. **authHeaderName** `string` Name of the custom authentication header. The egress guard also rejects protected header names; satisfying the field's character pattern alone does not permit every header. **authQueryParam** `string` Required for QUERY auth; the vendor's parameter name (e.g. "tavilyApiKey"). Restricted to RFC 3986 unreserved characters, which is NOT the same set as auth\_header\_name's RFC 7230 tchar: that set contains '&' (would append a second parameter), '#' (would truncate the URL at a fragment), '%' (would open a malformed escape) and '+' (decodes as a space). The query-parameter name uses its own character set. Empty is allowed — populated only for QUERY auth. **enabled** `boolean` Whether this configuration is enabled. **requestTimeout** `string` Time allowed for a remote request. Omission or a nonpositive duration uses 30 seconds; positive durations below one second are raised to one second. Long waits can delay the conversation while the remote server is unavailable. Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **version** `string(int64)` Output-only revision assigned by the store and incremented on updates. Ignored on writes. Pattern: ^-?\d+$ **createdBy** `string` Output-only identity of the caller that registered the server. Ignored on writes. **createdAt** `string(date-time)` Output-only creation time assigned by the store. Ignored on writes. **updatedAt** `string(date-time)` Output-only last-update time assigned by the store. Ignored on writes. #### mcp-servers-createCustomMcpServer-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "server": { "serverId": "example-id", "displayName": "example", "description": "example", "endpoint": "https://example.com/callback", "authType": "CUSTOM_MCP_SERVER_AUTH_TYPE_NONE", "enabled": true, "requestTimeout": "1s", "version": "1", "createdBy": "example", "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z" } } ``` Document ID: `DOC-IN-tools-connections-servers-api-createCustomMcpServer`. [Section identities and revisions](/documentation-manifest.json). - Register a custom MCP server: `DOC-IN-tools-connections-servers-api-createCustomMcpServer#overview` - Request: `DOC-IN-tools-connections-servers-api-createCustomMcpServer#request` - Responses: `DOC-IN-tools-connections-servers-api-createCustomMcpServer#responses` --- # Delete a custom MCP server URL: https://docs.travila.ai/api/mcp-servers/delete-custom-mcp-server **POST** `/api/v1/mcp-servers/delete` Removes the server record. Deleting an absent server succeeds with `deleted: false`. Conversations and profiles retain references to the deleted ID, so remove those references separately. New resolution fails once deletion is observed; in-flight calls and previously loaded definitions are not recalled. The referenced secret is left in place. To retain the configuration while disabling the server, set `enabled: false` through [update](/api/mcp-servers/update-custom-mcp-server). The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for removing a tenant-owned MCP server registration. **projectId** `string` Identifier of the project associated with the operation. **serverId** `string` **required** Identifier of the MCP server associated with the operation or tool. Minimum length: 1 #### mcp-servers-deleteCustomMcpServer-request Use the unprefixed serverId of a custom server registered in your project. ```json { "serverId": "product-tools" } ``` ## Responses ### 200 — Delete processed Content type: `application/json` Result payload for removing a tenant-owned MCP server registration. **deleted** `boolean` False when the server did not exist; the call still succeeds. #### mcp-servers-deleteCustomMcpServer-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "deleted": true } ``` Document ID: `DOC-IN-tools-connections-servers-api-deleteCustomMcpServer`. [Section identities and revisions](/documentation-manifest.json). - Delete a custom MCP server: `DOC-IN-tools-connections-servers-api-deleteCustomMcpServer#overview` - Request: `DOC-IN-tools-connections-servers-api-deleteCustomMcpServer#request` - Responses: `DOC-IN-tools-connections-servers-api-deleteCustomMcpServer#responses` --- # Get a custom MCP server URL: https://docs.travila.ai/api/mcp-servers/get-custom-mcp-server **POST** `/api/v1/mcp-servers/get` Returns one server record, including disabled ones. An unknown server ID returns `404`. The response does not expose the referenced credential's value. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for reading a tenant-owned MCP server registration. **projectId** `string` Identifier of the project associated with the operation. **serverId** `string` **required** Identifier of the MCP server associated with the operation or tool. Minimum length: 1 #### mcp-servers-getCustomMcpServer-request Use the unprefixed serverId of a custom server registered in your project. ```json { "serverId": "product-tools" } ``` ## Responses ### 200 — Server returned Content type: `application/json` Result payload for reading a tenant-owned MCP server registration. **server** `any` MCP server configuration returned by the lookup. All of: Variant 1: A project-scoped, HTTP-only MCP server definition, keyed (tenant\_id, project\_id, server\_id). Its wire ID is "custom:\{server\_id}". Credentials must be stored as secret references; inline tokens must not be persisted in this server definition. auth\_type selects the required credential fields. Authenticated modes require auth\_secret\_ref; NONE requires it to be empty. HEADER requires auth\_header\_name and QUERY requires auth\_query\_param; those names must be empty for every other mode. Inconsistent combinations are rejected before storage. Inline credentials are not accepted. ### Input constraints ### server\_id The server\_id must contain one through 63 characters. Its first character must be a lowercase ASCII letter or digit. Every remaining character must be a lowercase ASCII letter, digit, or hyphen. ### auth\_header\_name The auth\_header\_name may be empty text. Otherwise it must contain one through 128 characters, each an ASCII letter, digit, or one of these literal punctuation characters: ! # $ % & ' \* + . ^ \_ \` | \~ -. No other character is accepted. ### auth\_query\_param The auth\_query\_param may be empty text. Otherwise it must contain one through 128 characters, each an ASCII letter, digit, period, underscore, tilde, or hyphen. No other character is accepted. ### request\_timeout The request\_timeout duration must be no greater than 120 seconds. Model reference: [CustomMCPServer](/api/models/schema-p1cuh9jgfq#response). **serverId** `string` Unique within the project. **displayName** `string` Display name used for the registered MCP server. **description** `string` Human-readable description of the resource. **endpoint** `string` HTTPS endpoint for Streamable HTTP; local and standard-input/output transports are unsupported. The egress guard also rejects prohibited destinations such as metadata, loopback, private-network and in-cluster addresses. HTTPS alone does not satisfy these destination checks. **authType** `any` Authentication mechanism configured for the MCP server. How credentials are attached to requests to a tenant-configured MCP server. Credentials are held by reference; inline credential values are neither accepted nor persisted.
| Value | No. | Form | Meaning | |---|---|---|---| | `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE` | 0 | Canonical | Send requests without attaching a secret for authentication. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER` | 1 | Canonical | See meaning below. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER` | 2 | Canonical | See meaning below. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` | 3 | Canonical | See meaning below. | **`CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER`** Send the secret as a Bearer token in the Authorization header. Authorization: Bearer \ Exactly one of: Variant 1: Type: `string` Enum: `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE`, `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER`, `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER`, `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` Variant 2: Type: `integer(int32)` **authSecretRef** `any` Required credential reference for BEARER, HEADER and QUERY authentication. Resolves within this server's tenant and project; only the secret name is returned, never its value. All of: Variant 1: Reference to a secret within the same tenant and project as the resource that uses it. Cross-project and cross-tenant secret references are not supported. Secret values are write-only through the project secret API: writes accept a value and return metadata, while read operations return metadata without the value. Resource references name a secret within their own scope rather than carrying its value or an alternate tenant or project. ### Input constraints ### name The name must contain one through 63 characters. Its first character must be a lowercase ASCII letter or digit. Every remaining character must be a lowercase ASCII letter, digit, period, underscore, or hyphen. Model reference: [SecretRef](/api/models/schema-opqho625u2#response). **name** `string` Name identifying the secret within its project. **authHeaderName** `string` Name of the custom authentication header. The egress guard also rejects protected header names; satisfying the field's character pattern alone does not permit every header. **authQueryParam** `string` Required for QUERY auth; the vendor's parameter name (e.g. "tavilyApiKey"). Restricted to RFC 3986 unreserved characters, which is NOT the same set as auth\_header\_name's RFC 7230 tchar: that set contains '&' (would append a second parameter), '#' (would truncate the URL at a fragment), '%' (would open a malformed escape) and '+' (decodes as a space). The query-parameter name uses its own character set. Empty is allowed — populated only for QUERY auth. **enabled** `boolean` Whether this configuration is enabled. **requestTimeout** `string` Time allowed for a remote request. Omission or a nonpositive duration uses 30 seconds; positive durations below one second are raised to one second. Long waits can delay the conversation while the remote server is unavailable. Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **version** `string(int64)` Output-only revision assigned by the store and incremented on updates. Ignored on writes. Pattern: ^-?\d+$ **createdBy** `string` Output-only identity of the caller that registered the server. Ignored on writes. **createdAt** `string(date-time)` Output-only creation time assigned by the store. Ignored on writes. **updatedAt** `string(date-time)` Output-only last-update time assigned by the store. Ignored on writes. #### mcp-servers-getCustomMcpServer-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "server": { "serverId": "example-id", "displayName": "example", "description": "example", "endpoint": "https://example.com/callback", "authType": "CUSTOM_MCP_SERVER_AUTH_TYPE_NONE", "enabled": true, "requestTimeout": "1s", "version": "1", "createdBy": "example", "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z" } } ``` Document ID: `DOC-IN-tools-connections-servers-api-getCustomMcpServer`. [Section identities and revisions](/documentation-manifest.json). - Get a custom MCP server: `DOC-IN-tools-connections-servers-api-getCustomMcpServer#overview` - Request: `DOC-IN-tools-connections-servers-api-getCustomMcpServer#request` - Responses: `DOC-IN-tools-connections-servers-api-getCustomMcpServer#responses` --- # List custom MCP servers URL: https://docs.travila.ai/api/mcp-servers/list-custom-mcp-servers **POST** `/api/v1/mcp-servers/list` Returns the project's matching custom servers without pagination. Use the secret name filter to inspect dependencies before rotating or deleting a credential. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for listing MCP server registrations belonging to the tenant. **projectId** `string` Identifier of the project associated with the operation. **authSecretNameFilter** `string` When set, return only MCP servers whose auth\_secret\_ref names this secret. **includeDisabled** `boolean` Default false → only enabled servers. #### mcp-servers-listCustomMcpServers-request List enabled custom MCP servers in the authenticated project. ```json {} ``` ## Responses ### 200 — The project's servers Content type: `application/json` Result payload for listing MCP server registrations belonging to the tenant. **servers** `array[llm_v1_services_mcp_v1_CustomMCPServer]` MCP server configurations returned by the listing. A project-scoped, HTTP-only MCP server definition, keyed (tenant\_id, project\_id, server\_id). Its wire ID is "custom:\{server\_id}". Credentials must be stored as secret references; inline tokens must not be persisted in this server definition. auth\_type selects the required credential fields. Authenticated modes require auth\_secret\_ref; NONE requires it to be empty. HEADER requires auth\_header\_name and QUERY requires auth\_query\_param; those names must be empty for every other mode. Inconsistent combinations are rejected before storage. Inline credentials are not accepted. ### Input constraints ### server\_id The server\_id must contain one through 63 characters. Its first character must be a lowercase ASCII letter or digit. Every remaining character must be a lowercase ASCII letter, digit, or hyphen. ### auth\_header\_name The auth\_header\_name may be empty text. Otherwise it must contain one through 128 characters, each an ASCII letter, digit, or one of these literal punctuation characters: ! # $ % & ' \* + . ^ \_ \` | \~ -. No other character is accepted. ### auth\_query\_param The auth\_query\_param may be empty text. Otherwise it must contain one through 128 characters, each an ASCII letter, digit, period, underscore, tilde, or hyphen. No other character is accepted. ### request\_timeout The request\_timeout duration must be no greater than 120 seconds. Model reference: [CustomMCPServer](/api/models/schema-p1cuh9jgfq#response). **serverId** `string` Unique within the project. **displayName** `string` Display name used for the registered MCP server. **description** `string` Human-readable description of the resource. **endpoint** `string` HTTPS endpoint for Streamable HTTP; local and standard-input/output transports are unsupported. The egress guard also rejects prohibited destinations such as metadata, loopback, private-network and in-cluster addresses. HTTPS alone does not satisfy these destination checks. **authType** `any` Authentication mechanism configured for the MCP server. How credentials are attached to requests to a tenant-configured MCP server. Credentials are held by reference; inline credential values are neither accepted nor persisted.
| Value | No. | Form | Meaning | |---|---|---|---| | `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE` | 0 | Canonical | Send requests without attaching a secret for authentication. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER` | 1 | Canonical | See meaning below. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER` | 2 | Canonical | See meaning below. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` | 3 | Canonical | See meaning below. | **`CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER`** Send the secret as a Bearer token in the Authorization header. Authorization: Bearer \ Exactly one of: Variant 1: Type: `string` Enum: `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE`, `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER`, `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER`, `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` Variant 2: Type: `integer(int32)` **authSecretRef** `any` Required credential reference for BEARER, HEADER and QUERY authentication. Resolves within this server's tenant and project; only the secret name is returned, never its value. All of: Variant 1: Reference to a secret within the same tenant and project as the resource that uses it. Cross-project and cross-tenant secret references are not supported. Secret values are write-only through the project secret API: writes accept a value and return metadata, while read operations return metadata without the value. Resource references name a secret within their own scope rather than carrying its value or an alternate tenant or project. ### Input constraints ### name The name must contain one through 63 characters. Its first character must be a lowercase ASCII letter or digit. Every remaining character must be a lowercase ASCII letter, digit, period, underscore, or hyphen. Model reference: [SecretRef](/api/models/schema-opqho625u2#response). **name** `string` Name identifying the secret within its project. **authHeaderName** `string` Name of the custom authentication header. The egress guard also rejects protected header names; satisfying the field's character pattern alone does not permit every header. **authQueryParam** `string` Required for QUERY auth; the vendor's parameter name (e.g. "tavilyApiKey"). Restricted to RFC 3986 unreserved characters, which is NOT the same set as auth\_header\_name's RFC 7230 tchar: that set contains '&' (would append a second parameter), '#' (would truncate the URL at a fragment), '%' (would open a malformed escape) and '+' (decodes as a space). The query-parameter name uses its own character set. Empty is allowed — populated only for QUERY auth. **enabled** `boolean` Whether this configuration is enabled. **requestTimeout** `string` Time allowed for a remote request. Omission or a nonpositive duration uses 30 seconds; positive durations below one second are raised to one second. Long waits can delay the conversation while the remote server is unavailable. Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **version** `string(int64)` Output-only revision assigned by the store and incremented on updates. Ignored on writes. Pattern: ^-?\d+$ **createdBy** `string` Output-only identity of the caller that registered the server. Ignored on writes. **createdAt** `string(date-time)` Output-only creation time assigned by the store. Ignored on writes. **updatedAt** `string(date-time)` Output-only last-update time assigned by the store. Ignored on writes. **total** `string(int64)` Total number of entries reported by the listing. Pattern: ^-?\d+$ #### mcp-servers-listCustomMcpServers-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "servers": [ { "serverId": "example-id", "displayName": "example", "description": "example", "endpoint": "https://example.com/callback", "authType": "CUSTOM_MCP_SERVER_AUTH_TYPE_NONE", "enabled": true, "requestTimeout": "1s", "version": "1", "createdBy": "example", "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z" } ], "total": 1 } ``` Document ID: `DOC-IN-tools-connections-servers-api-listCustomMcpServers`. [Section identities and revisions](/documentation-manifest.json). - List custom MCP servers: `DOC-IN-tools-connections-servers-api-listCustomMcpServers#overview` - Request: `DOC-IN-tools-connections-servers-api-listCustomMcpServers#request` - Responses: `DOC-IN-tools-connections-servers-api-listCustomMcpServers#responses` --- # Custom MCP Server APIs URL: https://docs.travila.ai/api/mcp-servers Version: `aju17f20mq` Use the reference below for request and response fields and operation-specific requirements. # Overview \{#overview} Register custom MCP servers, update their configuration and test discovery. Configuration and discovery do not grant permission to perform a tool action or imply automatic insertion into every agent. ## Authentication \{#authentication} Use an authorized backend `sk_…` key in `X-API-Key`; these configuration operations do not need an end-user identity. A console JWT belongs to the separate console surface. See [Authentication](https://docs.travila.ai/core-platform/identity-access/authentication). ## Scoping \{#scoping} Tenant context comes from the authenticated request. Client-supplied `X-Tenant-Id`, `X-User-Id` or `X-Project-Id` are not an authorization mechanism. 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. ## Credentials \{#credentials} Server endpoints, query parameters and secret bindings are sensitive connection configuration. Use approved network destinations and the secret store; never place credentials in shared examples. **Related guide:** [Custom MCP servers](https://docs.travila.ai/integrations/tools-connections/custom-mcp-servers) ### JSON conventions \{#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](https://docs.travila.ai/api). ## Servers \{#reference-group-1} Register, read, update, and delete custom MCP servers. * [Register a custom MCP server](/api/mcp-servers/create-custom-mcp-server) * [Get a custom MCP server](/api/mcp-servers/get-custom-mcp-server) * [List custom MCP servers](/api/mcp-servers/list-custom-mcp-servers) * [Update a custom MCP server](/api/mcp-servers/update-custom-mcp-server) * [Delete a custom MCP server](/api/mcp-servers/delete-custom-mcp-server) ## Diagnostics \{#reference-group-2} Test a registered server’s connection and tool discovery. * [Test a custom MCP server connection](/api/mcp-servers/test-custom-mcp-server-connection) ## Server 1 \{#reference-server-1} Travila API [https://api.travila.ai](https://api.travila.ai) ## X-API-Key \{#authentication-apiKeyAuth} Authorized tenant backend secret key (`sk_…`). No end-user identity is needed for these tenant/project configuration operations. Keep the key out of client apps; authorization and provisioning still apply.

Authentication credentials

### apiKeyAuth Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-API-Key` ### onBehalfOf Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-On-Behalf-Of` ### bearerAuth Security scheme type: `http` HTTP authorization scheme: `bearer` ## Operations - [Register a custom MCP server](/api/mcp-servers/create-custom-mcp-server) — `POST /api/v1/mcp-servers/create` - [Get a custom MCP server](/api/mcp-servers/get-custom-mcp-server) — `POST /api/v1/mcp-servers/get` - [List custom MCP servers](/api/mcp-servers/list-custom-mcp-servers) — `POST /api/v1/mcp-servers/list` - [Update a custom MCP server](/api/mcp-servers/update-custom-mcp-server) — `POST /api/v1/mcp-servers/update` - [Delete a custom MCP server](/api/mcp-servers/delete-custom-mcp-server) — `POST /api/v1/mcp-servers/delete` - [Test a custom MCP server connection](/api/mcp-servers/test-custom-mcp-server-connection) — `POST /api/v1/mcp-servers/test-connection` Document ID: `DOC-API-mcp-servers-overview`. [Section identities and revisions](/documentation-manifest.json). - Overview: `DOC-API-mcp-servers-overview#overview` - Authentication: `DOC-API-mcp-servers-overview#authentication` - Scoping: `DOC-API-mcp-servers-overview#scoping` - Credentials: `DOC-API-mcp-servers-overview#credentials` - JSON conventions: `DOC-API-mcp-servers-overview#json-conventions` - Servers: `DOC-API-mcp-servers-overview#reference-group-1` - Diagnostics: `DOC-API-mcp-servers-overview#reference-group-2` - Server 1: `DOC-API-mcp-servers-overview#reference-server-1` - X-API-Key: `DOC-API-mcp-servers-overview#authentication-apiKeyAuth` --- # Test a custom MCP server connection URL: https://docs.travila.ai/api/mcp-servers/test-custom-mcp-server-connection **POST** `/api/v1/mcp-servers/test-connection` Reads a stored configuration snapshot, performs the MCP handshake/tool listing and returns the observed count and latency. A concurrent update can change the record after that read. This operation reads the stored definition directly, making it useful after a configuration change. Check [`success`](/api/mcp-servers/test-custom-mcp-server-connection#response-field-success) is `true`; a connection failure can return HTTP 200 with `success` false or omitted and an error. Inspect the error and repair the endpoint, authentication or network access before retrying. Authentication, validation, rate limiting and infrastructure failures can also return non-success HTTP responses. Tests are limited to 10 per minute per project; destination restrictions apply when connecting. Rate limiting does not replace network isolation or authorization. A successful test is a point-in-time connection check, not a guarantee that every advertised tool is safe or available. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for testing connectivity and tool discovery for a tenant-owned MCP server. **projectId** `string` Identifier of the project associated with the operation. **serverId** `string` **required** Identifier of the MCP server associated with the operation or tool. Minimum length: 1 #### mcp-servers-testCustomMcpServerConnection-request Use the unprefixed serverId of a custom server registered in your project. ```json { "serverId": "product-tools" } ``` #### cookbook-integrations-tools-connections-custom-mcp-servers-03-request Guide request for 3. Check the saved connection and choose its tools. Replace example resource identifiers with your own authorized values. ```json { "serverId": "firecrawl" } ``` ## Responses ### 200 — The test ran; read `success` for the outcome Content type: `application/json` Result payload for testing connectivity and tool discovery for a tenant-owned MCP server. **success** `boolean` Whether the operation reports a successful result. **toolCount** `string(int64)` Number of tools reported by the MCP server. Pattern: ^-?\d+$ **latencyMs** `string(int64)` Measured MCP connection-test latency, in milliseconds. Pattern: ^-?\d+$ **error** `string` Sanitized failure reason. Never contains the resolved credential, the auth header, or internal path details. #### mcp-servers-testCustomMcpServerConnection-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "success": true, "toolCount": 1, "latencyMs": "1", "error": "example" } ``` #### cookbook-integrations-tools-connections-custom-mcp-servers-json-01-response Illustrative response for 3. Check the saved connection and choose its tools. Replace example resource identifiers with your own authorized values. ```json { "success": true, "toolCount": 26, "latencyMs": "556" } ``` Document ID: `DOC-IN-tools-connections-servers-api-testCustomMcpServerConnection`. [Section identities and revisions](/documentation-manifest.json). - Test a custom MCP server connection: `DOC-IN-tools-connections-servers-api-testCustomMcpServerConnection#overview` - Request: `DOC-IN-tools-connections-servers-api-testCustomMcpServerConnection#request` - Responses: `DOC-IN-tools-connections-servers-api-testCustomMcpServerConnection#responses` --- # Update a custom MCP server URL: https://docs.travila.ai/api/mcp-servers/update-custom-mcp-server **POST** `/api/v1/mcp-servers/update` Replaces the mutable server configuration and increments its version. Read the saved record, edit the intended fields and submit the complete desired server: omitting [`enabled`](/api/models/schema-p1cuh9jgfq#request-field-enabled) disables it, and omitted optional fields are cleared. The top-level `serverId` selects the record; an update cannot rename it. There is no revision precondition, so concurrent stale updates can overwrite one another. A saved update does not confirm that every subsequent call has switched to the new configuration, and it does not cancel in-flight calls. Use `get` to inspect the saved record and `test-connection` to check a connection using it. The same validation as create applies; an unknown server returns `404`. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for changing a tenant-owned MCP server’s connection configuration. **projectId** `string` Identifier of the project associated with the operation. **serverId** `string` **required** Identifier of the MCP server associated with the operation or tool. Minimum length: 1 **server** `any` **required** MCP server configuration to apply. All of: Variant 1: A project-scoped, HTTP-only MCP server definition, keyed (tenant\_id, project\_id, server\_id). Its wire ID is "custom:\{server\_id}". Credentials must be stored as secret references; inline tokens must not be persisted in this server definition. auth\_type selects the required credential fields. Authenticated modes require auth\_secret\_ref; NONE requires it to be empty. HEADER requires auth\_header\_name and QUERY requires auth\_query\_param; those names must be empty for every other mode. Inconsistent combinations are rejected before storage. Inline credentials are not accepted. ### Input constraints ### server\_id The server\_id must contain one through 63 characters. Its first character must be a lowercase ASCII letter or digit. Every remaining character must be a lowercase ASCII letter, digit, or hyphen. ### auth\_header\_name The auth\_header\_name may be empty text. Otherwise it must contain one through 128 characters, each an ASCII letter, digit, or one of these literal punctuation characters: ! # $ % & ' \* + . ^ \_ \` | \~ -. No other character is accepted. ### auth\_query\_param The auth\_query\_param may be empty text. Otherwise it must contain one through 128 characters, each an ASCII letter, digit, period, underscore, tilde, or hyphen. No other character is accepted. ### request\_timeout The request\_timeout duration must be no greater than 120 seconds. Model reference: [CustomMCPServer](/api/models/schema-p1cuh9jgfq#request). **serverId** `string` **required** Unique within the project. Pattern: ^[a-z0-9][a-z0-9-]{0,62}$ **displayName** `string` Display name used for the registered MCP server. Maximum length: 200 **description** `string` Human-readable description of the resource. Maximum length: 1024 **endpoint** `string(uri)` **required** HTTPS endpoint for Streamable HTTP; local and standard-input/output transports are unsupported. The egress guard also rejects prohibited destinations such as metadata, loopback, private-network and in-cluster addresses. HTTPS alone does not satisfy these destination checks. Maximum length: 2048 Pattern: ^https:// **authType** `any` Authentication mechanism configured for the MCP server. How credentials are attached to requests to a tenant-configured MCP server. Credentials are held by reference; inline credential values are neither accepted nor persisted.
| Value | No. | Form | Meaning | |---|---|---|---| | `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE` | 0 | Canonical | Send requests without attaching a secret for authentication. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER` | 1 | Canonical | See meaning below. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER` | 2 | Canonical | See meaning below. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` | 3 | Canonical | See meaning below. | **`CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER`** Send the secret as a Bearer token in the Authorization header. Authorization: Bearer \ Exactly one of: Variant 1: Type: `string` Enum: `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE`, `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER`, `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER`, `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` Variant 2: Type: `integer(int32)` Enum: `0`, `1`, `2`, `3` **authSecretRef** `any` Required credential reference for BEARER, HEADER and QUERY authentication. Resolves within this server's tenant and project; only the secret name is returned, never its value. All of: Variant 1: Reference to a secret within the same tenant and project as the resource that uses it. Cross-project and cross-tenant secret references are not supported. Secret values are write-only through the project secret API: writes accept a value and return metadata, while read operations return metadata without the value. Resource references name a secret within their own scope rather than carrying its value or an alternate tenant or project. ### Input constraints ### name The name must contain one through 63 characters. Its first character must be a lowercase ASCII letter or digit. Every remaining character must be a lowercase ASCII letter, digit, period, underscore, or hyphen. Model reference: [SecretRef](/api/models/schema-opqho625u2#request). **name** `string` **required** Name identifying the secret within its project. Pattern: ^[a-z0-9][a-z0-9._-]{0,62}$ **authHeaderName** `string` Name of the custom authentication header. The egress guard also rejects protected header names; satisfying the field's character pattern alone does not permit every header. Pattern: ^([A-Za-z0-9!#$%&'*+.^_`|~-]{1,128})?$ **authQueryParam** `string` Required for QUERY auth; the vendor's parameter name (e.g. "tavilyApiKey"). Restricted to RFC 3986 unreserved characters, which is NOT the same set as auth\_header\_name's RFC 7230 tchar: that set contains '&' (would append a second parameter), '#' (would truncate the URL at a fragment), '%' (would open a malformed escape) and '+' (decodes as a space). The query-parameter name uses its own character set. Empty is allowed — populated only for QUERY auth. Pattern: ^([A-Za-z0-9._~-]{1,128})?$ **enabled** `boolean` Whether this configuration is enabled. **requestTimeout** `string` Time allowed for a remote request. Omission or a nonpositive duration uses 30 seconds; positive durations below one second are raised to one second. Long waits can delay the conversation while the remote server is unavailable. Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **version** `string(int64)` Output-only revision assigned by the store and incremented on updates. Ignored on writes. Pattern: ^-?\d+$ **createdBy** `string` Output-only identity of the caller that registered the server. Ignored on writes. **createdAt** `string(date-time)` Output-only creation time assigned by the store. Ignored on writes. **updatedAt** `string(date-time)` Output-only last-update time assigned by the store. Ignored on writes. #### mcp-servers-updateCustomMcpServer-request Replace an existing server configuration; preserve the intended authentication and enabled settings. ```json { "serverId": "product-tools", "server": { "serverId": "product-tools", "displayName": "Product tools", "endpoint": "https://mcp.example.com/mcp", "authType": "CUSTOM_MCP_SERVER_AUTH_TYPE_NONE", "enabled": true } } ``` ## Responses ### 200 — Server updated; the stored record is echoed back Content type: `application/json` Result payload for changing a tenant-owned MCP server’s connection configuration. **server** `any` Updated MCP server configuration. All of: Variant 1: A project-scoped, HTTP-only MCP server definition, keyed (tenant\_id, project\_id, server\_id). Its wire ID is "custom:\{server\_id}". Credentials must be stored as secret references; inline tokens must not be persisted in this server definition. auth\_type selects the required credential fields. Authenticated modes require auth\_secret\_ref; NONE requires it to be empty. HEADER requires auth\_header\_name and QUERY requires auth\_query\_param; those names must be empty for every other mode. Inconsistent combinations are rejected before storage. Inline credentials are not accepted. ### Input constraints ### server\_id The server\_id must contain one through 63 characters. Its first character must be a lowercase ASCII letter or digit. Every remaining character must be a lowercase ASCII letter, digit, or hyphen. ### auth\_header\_name The auth\_header\_name may be empty text. Otherwise it must contain one through 128 characters, each an ASCII letter, digit, or one of these literal punctuation characters: ! # $ % & ' \* + . ^ \_ \` | \~ -. No other character is accepted. ### auth\_query\_param The auth\_query\_param may be empty text. Otherwise it must contain one through 128 characters, each an ASCII letter, digit, period, underscore, tilde, or hyphen. No other character is accepted. ### request\_timeout The request\_timeout duration must be no greater than 120 seconds. Model reference: [CustomMCPServer](/api/models/schema-p1cuh9jgfq#response). **serverId** `string` Unique within the project. **displayName** `string` Display name used for the registered MCP server. **description** `string` Human-readable description of the resource. **endpoint** `string` HTTPS endpoint for Streamable HTTP; local and standard-input/output transports are unsupported. The egress guard also rejects prohibited destinations such as metadata, loopback, private-network and in-cluster addresses. HTTPS alone does not satisfy these destination checks. **authType** `any` Authentication mechanism configured for the MCP server. How credentials are attached to requests to a tenant-configured MCP server. Credentials are held by reference; inline credential values are neither accepted nor persisted.
| Value | No. | Form | Meaning | |---|---|---|---| | `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE` | 0 | Canonical | Send requests without attaching a secret for authentication. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER` | 1 | Canonical | See meaning below. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER` | 2 | Canonical | See meaning below. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` | 3 | Canonical | See meaning below. | **`CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER`** Send the secret as a Bearer token in the Authorization header. Authorization: Bearer \ Exactly one of: Variant 1: Type: `string` Enum: `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE`, `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER`, `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER`, `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` Variant 2: Type: `integer(int32)` **authSecretRef** `any` Required credential reference for BEARER, HEADER and QUERY authentication. Resolves within this server's tenant and project; only the secret name is returned, never its value. All of: Variant 1: Reference to a secret within the same tenant and project as the resource that uses it. Cross-project and cross-tenant secret references are not supported. Secret values are write-only through the project secret API: writes accept a value and return metadata, while read operations return metadata without the value. Resource references name a secret within their own scope rather than carrying its value or an alternate tenant or project. ### Input constraints ### name The name must contain one through 63 characters. Its first character must be a lowercase ASCII letter or digit. Every remaining character must be a lowercase ASCII letter, digit, period, underscore, or hyphen. Model reference: [SecretRef](/api/models/schema-opqho625u2#response). **name** `string` Name identifying the secret within its project. **authHeaderName** `string` Name of the custom authentication header. The egress guard also rejects protected header names; satisfying the field's character pattern alone does not permit every header. **authQueryParam** `string` Required for QUERY auth; the vendor's parameter name (e.g. "tavilyApiKey"). Restricted to RFC 3986 unreserved characters, which is NOT the same set as auth\_header\_name's RFC 7230 tchar: that set contains '&' (would append a second parameter), '#' (would truncate the URL at a fragment), '%' (would open a malformed escape) and '+' (decodes as a space). The query-parameter name uses its own character set. Empty is allowed — populated only for QUERY auth. **enabled** `boolean` Whether this configuration is enabled. **requestTimeout** `string` Time allowed for a remote request. Omission or a nonpositive duration uses 30 seconds; positive durations below one second are raised to one second. Long waits can delay the conversation while the remote server is unavailable. Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$ **version** `string(int64)` Output-only revision assigned by the store and incremented on updates. Ignored on writes. Pattern: ^-?\d+$ **createdBy** `string` Output-only identity of the caller that registered the server. Ignored on writes. **createdAt** `string(date-time)` Output-only creation time assigned by the store. Ignored on writes. **updatedAt** `string(date-time)` Output-only last-update time assigned by the store. Ignored on writes. #### mcp-servers-updateCustomMcpServer-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "server": { "serverId": "example-id", "displayName": "example", "description": "example", "endpoint": "https://example.com/callback", "authType": "CUSTOM_MCP_SERVER_AUTH_TYPE_NONE", "enabled": true, "requestTimeout": "1s", "version": "1", "createdBy": "example", "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z" } } ``` Document ID: `DOC-IN-tools-connections-servers-api-updateCustomMcpServer`. [Section identities and revisions](/documentation-manifest.json). - Update a custom MCP server: `DOC-IN-tools-connections-servers-api-updateCustomMcpServer#overview` - Request: `DOC-IN-tools-connections-servers-api-updateCustomMcpServer#request` - Responses: `DOC-IN-tools-connections-servers-api-updateCustomMcpServer#responses` --- # Add subscribers to a topic URL: https://docs.travila.ai/api/notifications/add-subscribers-to-topic **POST** `/api/v1/notifications/manage/add-subscribers-to-topic` Adds the selected users as subscribers to the specified topic. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Broadcast with topics](/core-platform/notifications/topics) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for adding selected users to a notification topic’s recipient membership. **topicKey** `string` **required** Caller-facing key identifying a notification topic. Minimum length: 1 **userIds** `array[string]` Identifiers of the users selected by the operation. Maximum items: 100 Type: `string` #### notifications-addSubscribersToTopic-request Add existing application users to an existing topic. ```json { "topicKey": "product-updates", "userIds": [ "user-1", "user-2" ] } ``` ## Responses ### 200 — Subscribers added Content type: `application/json` Result payload for adding selected users to a notification topic’s recipient membership. **result** `any` Accepted and failed subscriber counts with per-subscriber errors from the membership change. All of: Variant 1: Result of a topic subscription operation (add/remove subscribers). Novu returns partial success — some subscribers may fail while others succeed. Model reference: [TopicSubscriptionResult](/api/models/schema-p2eb0gb1ln#response). **totalCount** `string(int64)` Total number of subscribers reported for the membership-change result. Pattern: ^-?\d+$ **successful** `string(int64)` Number of subscribers accepted by the topic subscription operation. Pattern: ^-?\d+$ **failed** `string(int64)` Number of subscribers rejected by the topic subscription operation. Pattern: ^-?\d+$ **errors** `array[notification_v1_TopicSubscriptionError]` Errors reported while processing notification requests. Subscriber-specific failure reported while changing notification-topic membership. Model reference: [TopicSubscriptionError](/api/models/schema-okmh5pnenu#response). **subscriberId** `string` Identifier of the notification subscriber. **code** `string` Provider error code for the topic subscription failure. **message** `string` Diagnostic or descriptive text returned by the operation. #### notifications-addSubscribersToTopic-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "result": { "totalCount": 1, "successful": 1, "failed": 1, "errors": [ { "subscriberId": "example_123", "code": "example", "message": "example" } ] } } ``` Document ID: `DOC-CP-notifications-api-addSubscribersToTopic`. [Section identities and revisions](/documentation-manifest.json). - Add subscribers to a topic: `DOC-CP-notifications-api-addSubscribersToTopic#overview` - Request: `DOC-CP-notifications-api-addSubscribersToTopic#request` - Responses: `DOC-CP-notifications-api-addSubscribersToTopic#responses` --- # Archive all inbox messages URL: https://docs.travila.ai/api/notifications/archive-all-inbox-messages **POST** `/api/v1/notifications/archive-all-inbox-messages` Archives all inbox messages for the authenticated user. Optionally scoped to specific workflow tags (OR logic). The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox) · [Inbox state and actions](/api/notifications/inbox) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for archiving inbox notifications selected by the supplied tag filter. **tags** `array[string]` Labels associated with the resource for organization or filtering. Type: `string` #### notifications-archiveAllInboxMessages-request Archive all messages in the selected user’s inbox; no tag filter is supplied. ```json {} ``` ## Responses ### 200 — Messages archived Content type: `application/json` Result payload for archiving inbox notifications selected by the supplied tag filter. **archivedCount** `string(int64)` Number of inbox entries reported archived by the operation. Pattern: ^-?\d+$ #### notifications-archiveAllInboxMessages-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "archivedCount": 1 } ``` Document ID: `DOC-CP-notifications-api-archiveAllInboxMessages`. [Section identities and revisions](/documentation-manifest.json). - Archive all inbox messages: `DOC-CP-notifications-api-archiveAllInboxMessages#overview` - Request: `DOC-CP-notifications-api-archiveAllInboxMessages#request` - Responses: `DOC-CP-notifications-api-archiveAllInboxMessages#responses` --- # Archive all read inbox messages URL: https://docs.travila.ai/api/notifications/archive-all-read-inbox-messages **POST** `/api/v1/notifications/archive-all-read-inbox-messages` Archives every already-read inbox message for the authenticated user. Optionally scoped to specific workflow tags (OR logic). The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for archiving read inbox notifications selected by the supplied tag filter. **tags** `array[string]` Labels associated with the resource for organization or filtering. Type: `string` #### notifications-archiveAllReadInboxMessages-request Archive all read messages in the selected user’s inbox; no tag filter is supplied. ```json {} ``` ## Responses ### 200 — Read messages archived Content type: `application/json` Mirrors ArchiveAllInboxMessagesResponse — same shape, distinct type so the two bulk-archive RPC contracts can evolve independently. **archivedCount** `string(int64)` Number of inbox entries reported archived by the operation. Pattern: ^-?\d+$ #### notifications-archiveAllReadInboxMessages-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "archivedCount": 1 } ``` Document ID: `DOC-CP-notifications-api-archiveAllReadInboxMessages`. [Section identities and revisions](/documentation-manifest.json). - Archive all read inbox messages: `DOC-CP-notifications-api-archiveAllReadInboxMessages#overview` - Request: `DOC-CP-notifications-api-archiveAllReadInboxMessages#request` - Responses: `DOC-CP-notifications-api-archiveAllReadInboxMessages#responses` --- # Archive an inbox message URL: https://docs.travila.ai/api/notifications/archive-inbox-message **POST** `/api/v1/notifications/archive-inbox-message` Archives a single inbox message. Archived messages are hidden from the default feed but retained. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for archiving an inbox notification. Caller user\_id is derived from authentication headers by the gateway. **notificationId** `string` **required** Identifier of the notification whose inbox entry is being modified. Minimum length: 1 #### notifications-archiveInboxMessage-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "notificationId": "example_123" } ``` ## Responses ### 200 — Message archived Content type: `application/json` Result payload for archiving one inbox notification while retaining its provider record. **status** `any` Status reported by the notification provider. All of: Variant 1: Mirrors Novu's common delete/mutate acknowledgement response. Model reference: [OperationStatus](/api/models/schema-ok4lj6t1ka#response). **acknowledged** `boolean` Whether the provider acknowledged the requested operation. **status** `string` Status reported by the notification provider. e.g., "done", "deleted" #### notifications-archiveInboxMessage-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "status": { "acknowledged": true, "status": "example" } } ``` Document ID: `DOC-CP-notifications-api-archiveInboxMessage`. [Section identities and revisions](/documentation-manifest.json). - Archive an inbox message: `DOC-CP-notifications-api-archiveInboxMessage#overview` - Request: `DOC-CP-notifications-api-archiveInboxMessage#request` - Responses: `DOC-CP-notifications-api-archiveInboxMessage#responses` --- # Bulk-update per-workflow preferences URL: https://docs.travila.ai/api/notifications/bulk-update-preferences **POST** `/api/v1/notifications/bulk-update-preferences` Updates channel toggles for multiple workflows in a single request. Updates can partially apply before a later failure. Re-read preferences and retry only unresolved changes; a request failure does not imply an atomic rollback. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Manage notification preferences](/core-platform/notifications/preferences) · [Preferences and channel inheritance](/api/notifications/preferences) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for applying channel-preference changes across selected notification workflows. **entries** `array[notification_v1_services_gateway_v1_UpdateWorkflowPreferenceRequest]` Workflow-specific preference updates submitted together. Maximum items: 100 Inputs for changing the subscriber’s channel preferences for one notification workflow. Model reference: [UpdateWorkflowPreferenceRequest](/api/models/schema-p38aqgjs3a#request). **workflowId** `string` **required** Identifier of the notification workflow whose subscriber preferences are being changed. Minimum length: 1 **channels** `any` Channel switches to update for the subscriber. All of: Variant 1: Per-channel notification toggles. All fields are optional so callers can patch only the channels they want to change; omitted fields remain unchanged. Model reference: [ChannelToggles](/api/models/schema-oj4cvo85fs#request). **inApp** `boolean` Whether in-app notification delivery is enabled. **push** `boolean` Whether push notification delivery is enabled. **email** `boolean` Whether email notification delivery is enabled. **sms** `boolean` Whether SMS notification delivery is enabled. **chat** `boolean` Whether chat notification delivery is enabled. #### notifications-bulkUpdatePreferences-request Update two existing workflows; inspect the per-entry outcomes. ```json { "entries": [ { "workflowId": "promotional", "channels": { "push": false } }, { "workflowId": "weekly-summary", "channels": { "inApp": true, "push": true } } ] } ``` ## Responses ### 200 — Preferences bulk-updated Content type: `application/json` Result payload for applying channel-preference changes across selected notification workflows. **updatedCount** `string(int64)` Number of preference entries reported updated. Pattern: ^-?\d+$ #### notifications-bulkUpdatePreferences-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "updatedCount": 1 } ``` Document ID: `DOC-CP-notifications-api-bulkUpdatePreferences`. [Section identities and revisions](/documentation-manifest.json). - Bulk-update per-workflow preferences: `DOC-CP-notifications-api-bulkUpdatePreferences#overview` - Request: `DOC-CP-notifications-api-bulkUpdatePreferences#request` - Responses: `DOC-CP-notifications-api-bulkUpdatePreferences#responses` --- # Cancel a pending digest event URL: https://docs.travila.ai/api/notifications/cancel-digest-event **POST** `/api/v1/notifications/manage/cancel-digest-event` Cancels a specific event from a pending digest. If the digest has already been sent, this has no effect. ### Cancellation outcomes An already processed digest event can return HTTP 200 with `cancelled: false` and a message that it may already have been processed. Inspect [`cancelled`](/api/notifications/cancel-digest-event#response-field-cancelled) rather than relying on HTTP status alone. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Send notifications](/core-platform/notifications/sending) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for cancelling a queued notification digest event. **transactionId** `string` **required** Identifier correlating a notification trigger with later status or cancellation requests. Minimum length: 1 #### notifications-cancelDigestEvent-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "transactionId": "example_123" } ``` ## Responses ### 200 — Digest event cancellation result Content type: `application/json` Result payload for cancelling a queued notification digest event. **cancelled** `boolean` Whether the notification cancellation was acknowledged. **message** `string` Diagnostic or descriptive text returned by the operation. #### notifications-cancelDigestEvent-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "cancelled": true, "message": "example" } ``` Document ID: `DOC-CP-notifications-api-cancelDigestEvent`. [Section identities and revisions](/documentation-manifest.json). - Cancel a pending digest event: `DOC-CP-notifications-api-cancelDigestEvent#overview` - Request: `DOC-CP-notifications-api-cancelDigestEvent#request` - Responses: `DOC-CP-notifications-api-cancelDigestEvent#responses` --- # Cancel a pending notification URL: https://docs.travila.ai/api/notifications/cancel-notification **POST** `/api/v1/notifications/manage/cancel` Requests cancellation of pending/scheduled provider work by transaction ID. It does not recall notifications already handed to a channel or undo an action the recipient performed. Inspect the cancellation result and preserve uncertainty when delivery is in flight. ### Cancellation outcomes An already processed notification can return HTTP 200 with `cancelled: false` and a message that it may already have been delivered. Inspect [`cancelled`](/api/notifications/cancel-notification#response-field-cancelled) rather than relying on HTTP status alone. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Send notifications](/core-platform/notifications/sending) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for cancelling a pending notification by transaction identifier. **transactionId** `string` **required** Identifier correlating a notification trigger with later status or cancellation requests. Minimum length: 1 #### notifications-cancelNotification-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "transactionId": "example_123" } ``` ## Responses ### 200 — Cancellation result Content type: `application/json` Result payload for cancelling a pending notification by transaction identifier. **cancelled** `boolean` Whether the notification cancellation was acknowledged. **message** `string` Diagnostic or descriptive text returned by the operation. #### notifications-cancelNotification-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "cancelled": true, "message": "example" } ``` Document ID: `DOC-CP-notifications-api-cancelNotification`. [Section identities and revisions](/documentation-manifest.json). - Cancel a pending notification: `DOC-CP-notifications-api-cancelNotification#overview` - Request: `DOC-CP-notifications-api-cancelNotification#request` - Responses: `DOC-CP-notifications-api-cancelNotification#responses` --- # Check if a user is subscribed to a topic URL: https://docs.travila.ai/api/notifications/check-topic-subscription **POST** `/api/v1/notifications/manage/check-topic-subscription` Returns whether the specified user is currently subscribed to the given topic. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Broadcast with topics](/core-platform/notifications/topics) · [Push registration and topic delivery](/api/notifications/delivery) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` user\_id is a query target, not the caller. **topicKey** `string` **required** Caller-facing key identifying a notification topic. Minimum length: 1 **userId** `string` **required** Identifier of the user associated with the operation. Minimum length: 1 #### notifications-checkTopicSubscription-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "topicKey": "example_123", "userId": "example_123" } ``` ## Responses ### 200 — Subscription status returned Content type: `application/json` Result payload for checking whether a user belongs to a notification topic. **isSubscribed** `boolean` Whether the user is subscribed to the selected topic. #### notifications-checkTopicSubscription-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "isSubscribed": true } ``` Document ID: `DOC-CP-notifications-api-checkTopicSubscription`. [Section identities and revisions](/documentation-manifest.json). - Check if a user is subscribed to a topic: `DOC-CP-notifications-api-checkTopicSubscription#overview` - Request: `DOC-CP-notifications-api-checkTopicSubscription#request` - Responses: `DOC-CP-notifications-api-checkTopicSubscription#responses` --- # Complete an inbox message action URL: https://docs.travila.ai/api/notifications/complete-inbox-action **POST** `/api/v1/notifications/complete-inbox-action` Marks an inbox action button completed. This changes inbox presentation state; it does not execute or authorize the business operation behind that button. Verify the actual business operation separately. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for marking an inbox notification’s action completed. **notificationId** `string` **required** Identifier of the notification whose inbox entry is being modified. Minimum length: 1 **actionType** `any` **required** Action selector used when completing the inbox action. Which configured notification action a completion or reversal refers to.
| Value | No. | Form | Meaning | |---|---|---|---| | `ACTION_TYPE_PRIMARY` | 0 | Canonical | The notification's primary action button or action slot. | | `ACTION_TYPE_SECONDARY` | 1 | Canonical | The notification's secondary action button or action slot. |
Exactly one of: Variant 1: Type: `string` Enum: `ACTION_TYPE_PRIMARY`, `ACTION_TYPE_SECONDARY` Variant 2: Type: `integer(int32)` Enum: `0`, `1` #### notifications-completeInboxAction-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "notificationId": "example_123", "actionType": "ACTION_TYPE_PRIMARY" } ``` ## Responses ### 200 — Action completed Content type: `application/json` Result payload for marking an inbox notification’s action completed. **status** `any` Status reported by the notification provider. All of: Variant 1: Mirrors Novu's common delete/mutate acknowledgement response. Model reference: [OperationStatus](/api/models/schema-ok4lj6t1ka#response). **acknowledged** `boolean` Whether the provider acknowledged the requested operation. **status** `string` Status reported by the notification provider. e.g., "done", "deleted" #### notifications-completeInboxAction-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "status": { "acknowledged": true, "status": "example" } } ``` Document ID: `DOC-CP-notifications-api-completeInboxAction`. [Section identities and revisions](/documentation-manifest.json). - Complete an inbox message action: `DOC-CP-notifications-api-completeInboxAction#overview` - Request: `DOC-CP-notifications-api-completeInboxAction#request` - Responses: `DOC-CP-notifications-api-completeInboxAction#responses` --- # Configure a notification provider URL: https://docs.travila.ai/api/notifications/configure-provider **POST** `/api/v1/notifications/manage/configure-provider` Configures credentials and activation state for a notification provider (e.g., FCM, SendGrid, Twilio). Uses **upsert** semantics: if an active integration already exists for the specified provider type, it updates the existing integration in place (preserving its ID and subscriber linkages). If no active integration exists, a new one is created. The current read-then-upsert path does not establish atomic uniqueness under concurrent configuration. Credentials are sensitive and should stay in trusted backend tooling; the API shape is not proof that they bypass all internal journals or diagnostics. ### Provider configuration outcomes Multiple active integrations of the same type return `409 Conflict` and need support resolution. After a credential change, test delivery to an already registered device. [Provider status](/api/notifications/get-providers) alone does not prove arrival. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for configuring a notification delivery provider. Tenant and environment are derived from authentication headers by the gateway. **provider** `any` Notification delivery provider being configured or reported. Service used to deliver a notification through its selected channel.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_TYPE_FCM` | 0 | Canonical | See meaning below. | | `PROVIDER_TYPE_APNS` | 1 | Canonical | See meaning below. | | `PROVIDER_TYPE_SENDGRID` | 2 | Canonical | See meaning below. | | `PROVIDER_TYPE_SES` | 3 | Canonical | See meaning below. | | `PROVIDER_TYPE_TWILIO` | 4 | Canonical | See meaning below. | | `PROVIDER_TYPE_SLACK` | 5 | Canonical | See meaning below. | | `PROVIDER_TYPE_DISCORD` | 6 | Canonical | See meaning below. | **`PROVIDER_TYPE_FCM`** Firebase Cloud Messaging for device or web push delivery. Firebase Cloud Messaging (push) **`PROVIDER_TYPE_APNS`** Apple Push Notification service for Apple-device push delivery. Apple Push Notification Service **`PROVIDER_TYPE_SENDGRID`** SendGrid for email delivery. SendGrid (email) **`PROVIDER_TYPE_SES`** Amazon Simple Email Service for email delivery. AWS SES (email) **`PROVIDER_TYPE_TWILIO`** Twilio for SMS delivery. Twilio (SMS) **`PROVIDER_TYPE_SLACK`** Slack for chat-message delivery. Slack (chat) **`PROVIDER_TYPE_DISCORD`** Discord for chat-message delivery. Discord (chat)
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_TYPE_FCM`, `PROVIDER_TYPE_APNS`, `PROVIDER_TYPE_SENDGRID`, `PROVIDER_TYPE_SES`, `PROVIDER_TYPE_TWILIO`, `PROVIDER_TYPE_SLACK`, `PROVIDER_TYPE_DISCORD` Variant 2: Type: `integer(int32)` **credentials** `map[string, string]` Provider-specific credentials supplied when configuring delivery. **active** `boolean` Whether the resource is marked active. #### notifications-configureProvider-request Configure email delivery with your SendGrid credential; the displayed key is a placeholder. ```json { "provider": "PROVIDER_TYPE_SENDGRID", "credentials": { "apiKey": "REPLACE_WITH_SENDGRID_API_KEY" }, "active": true } ``` ## Responses ### 200 — Provider configured (created or updated) Content type: `application/json` Result payload for configuring credentials and activation for a notification delivery provider. **integrationId** `string` Identifier of the provider integration in Novu. **active** `boolean` Whether the resource is marked active. #### notifications-configureProvider-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "integrationId": "example_123", "active": true } ``` ### 409 — Multiple active connections exist for this provider type. Contact your Travila operator to resolve the conflict before retrying. Document ID: `DOC-CP-notifications-api-configureProvider`. [Section identities and revisions](/documentation-manifest.json). - Configure a notification provider: `DOC-CP-notifications-api-configureProvider#overview` - Request: `DOC-CP-notifications-api-configureProvider#request` - Responses: `DOC-CP-notifications-api-configureProvider#responses` --- # Create a notification subscriber URL: https://docs.travila.ai/api/notifications/create-subscriber **POST** `/api/v1/notifications/manage/create-subscriber` Creates a new subscriber profile in the notification system. The subscriber ID is used to target notifications and manage preferences. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` tenant\_id and environment derived from auth headers by gateway. **subscriberId** `string` **required** Identifier of the notification subscriber. Minimum length: 1 **email** `string` Email address used for subscriber contact and delivery. **phone** `string` Phone number used for subscriber contact and delivery. **firstName** `string` Subscriber’s given name. **lastName** `string` Subscriber’s family name. **avatarUrl** `string` URL of the subscriber’s avatar image. **locale** `string` Subscriber locale used when rendering notifications. **data** `map[string, string]` Custom key-value attributes to attach to the new subscriber. #### notifications-createSubscriber-request Enroll an application user for notification delivery; use their stable application user ID. ```json { "subscriberId": "user-1", "email": "alex@example.com", "firstName": "Alex", "locale": "en-US" } ``` #### cookbook-core-platform-notifications-administration-json-02-request Guide request for 2. Enroll the same application user. Replace example resource identifiers with your own authorized values. ```json { "subscriberId": "user-1" } ``` ## Responses ### 200 — Subscriber created Content type: `application/json` Result payload for creating a notification subscriber with contact and locale attributes. **novuSubscriberId** `string` Subscriber identifier returned by Novu. **subscriberId** `string` Identifier of the notification subscriber. #### notifications-createSubscriber-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "novuSubscriberId": "example_123", "subscriberId": "example_123" } ``` Document ID: `DOC-CP-notifications-api-createSubscriber`. [Section identities and revisions](/documentation-manifest.json). - Create a notification subscriber: `DOC-CP-notifications-api-createSubscriber#overview` - Request: `DOC-CP-notifications-api-createSubscriber#request` - Responses: `DOC-CP-notifications-api-createSubscriber#responses` --- # Create a notification topic URL: https://docs.travila.ai/api/notifications/create-topic **POST** `/api/v1/notifications/manage/create-topic` Creates a new topic that users can be subscribed to. Topics enable broadcasting notifications to groups of subscribers. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Broadcast with topics](/core-platform/notifications/topics) · [Push registration and topic delivery](/api/notifications/delivery) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for creating a named notification topic with a caller-selected key. **topicKey** `string` **required** Caller-facing key identifying a notification topic. Minimum length: 1 **name** `string` Display name assigned to the notification topic. #### notifications-createTopic-request Create a topic before adding its subscribers. ```json { "topicKey": "product-updates", "name": "Product updates" } ``` ## Responses ### 200 — Topic created successfully Content type: `application/json` Result payload for creating a named notification topic with a caller-selected key. **topicKey** `string` Caller-facing key identifying a notification topic. **topicId** `string` Provider-assigned identifier of the notification topic. #### notifications-createTopic-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "topicKey": "example_123", "topicId": "example_123" } ``` Document ID: `DOC-CP-notifications-api-createTopic`. [Section identities and revisions](/documentation-manifest.json). - Create a notification topic: `DOC-CP-notifications-api-createTopic#overview` - Request: `DOC-CP-notifications-api-createTopic#request` - Responses: `DOC-CP-notifications-api-createTopic#responses` --- # Create a notification workflow URL: https://docs.travila.ai/api/notifications/create-workflow **POST** `/api/v1/notifications/manage/create-workflow` Creates a new notification workflow definition with steps, channel configuration, and preference settings. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for creating a notification workflow. Tenant and environment are derived from authentication headers by the gateway. **workflow** `map[string, any]` Notification workflow definition to create. #### notifications-createWorkflow-request Create the in-app welcome definition from the administration recipe; provider JSON is passed through. ```json { "workflow": { "name": "Welcome Notification", "description": "Sent when a user completes onboarding", "__source": "editor", "steps": [ { "name": "In-App Step", "type": "in_app", "controlValues": { "body": "Welcome to your health coaching journey!" } } ] } } ``` ## Responses ### 200 — Workflow created Content type: `application/json` Result payload for registering a notification workflow definition with the provider. **workflow** `map[string, any]` Notification workflow definition supplied to or returned by the provider. #### notifications-createWorkflow-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "workflow": { "example": "value" } } ``` Document ID: `DOC-CP-notifications-api-createWorkflow`. [Section identities and revisions](/documentation-manifest.json). - Create a notification workflow: `DOC-CP-notifications-api-createWorkflow#overview` - Request: `DOC-CP-notifications-api-createWorkflow#request` - Responses: `DOC-CP-notifications-api-createWorkflow#responses` --- # Delete an inbox message URL: https://docs.travila.ai/api/notifications/delete-inbox-message **POST** `/api/v1/notifications/delete-inbox-message` Deletes the specified inbox message in the effective user’s inbox. This does not recall copies already delivered through other channels or attest to backup erasure. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Caller user\_id derived from auth headers by gateway. **messageId** `string` **required** Identifier of the inbox message to delete. Minimum length: 1 #### notifications-deleteInboxMessage-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "messageId": "example_123" } ``` ## Responses ### 200 — Message deleted successfully Content type: `application/json` Result payload for removing an identified message from the subscriber’s notification inbox. **status** `any` Status reported by the notification provider. All of: Variant 1: Mirrors Novu's common delete/mutate acknowledgement response. Model reference: [OperationStatus](/api/models/schema-ok4lj6t1ka#response). **acknowledged** `boolean` Whether the provider acknowledged the requested operation. **status** `string` Status reported by the notification provider. e.g., "done", "deleted" #### notifications-deleteInboxMessage-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "status": { "acknowledged": true, "status": "example" } } ``` Document ID: `DOC-CP-notifications-api-deleteInboxMessage`. [Section identities and revisions](/documentation-manifest.json). - Delete an inbox message: `DOC-CP-notifications-api-deleteInboxMessage#overview` - Request: `DOC-CP-notifications-api-deleteInboxMessage#request` - Responses: `DOC-CP-notifications-api-deleteInboxMessage#responses` --- # Delete the caller's subscriber profile URL: https://docs.travila.ai/api/notifications/delete-subscriber **POST** `/api/v1/notifications/manage/delete-subscriber` Requests deletion of the authenticated beneficiary's subscriber at the configured provider. An absent subscriber is an idempotent success. Inspect nested `status.acknowledged`. A missing [`status`](/api/notifications/delete-subscriber#response-field-status) is unknown: the current handler can return an empty HTTP 200 response on configuration, network or provider errors. Reconcile that outcome instead of declaring cleanup complete. Provider acknowledgment does not certify complete erasure of queued work, remote copies or platform records. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Caller user\_id derived from auth headers by gateway. #### notifications-deleteSubscriber-request Delete the subscriber selected by authentication; no subscriber ID is accepted in this body. ```json {} ``` ## Responses ### 200 — Provider acknowledgment when present; HTTP success alone does not confirm deletion. Content type: `application/json` Result payload for removing the subscriber’s notification-provider record. **status** `any` Status reported by the notification provider. All of: Variant 1: Mirrors Novu's common delete/mutate acknowledgement response. Model reference: [OperationStatus](/api/models/schema-ok4lj6t1ka#response). **acknowledged** `boolean` Whether the provider acknowledged the requested operation. **status** `string` Status reported by the notification provider. e.g., "done", "deleted" #### notifications-deleteSubscriber-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "status": { "acknowledged": true, "status": "example" } } ``` Document ID: `DOC-CP-notifications-api-deleteSubscriber`. [Section identities and revisions](/documentation-manifest.json). - Delete the caller's subscriber profile: `DOC-CP-notifications-api-deleteSubscriber#overview` - Request: `DOC-CP-notifications-api-deleteSubscriber#request` - Responses: `DOC-CP-notifications-api-deleteSubscriber#responses` --- # Delete a notification topic URL: https://docs.travila.ai/api/notifications/delete-topic **POST** `/api/v1/notifications/manage/delete-topic` Deletes an existing topic. All subscriber associations with this topic are removed. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Broadcast with topics](/core-platform/notifications/topics) · [Push registration and topic delivery](/api/notifications/delivery) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for removing an identified notification topic. **topicKey** `string` **required** Caller-facing key identifying a notification topic. Minimum length: 1 #### notifications-deleteTopic-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "topicKey": "example_123" } ``` ## Responses ### 200 — Topic deleted Content type: `application/json` Result payload for removing an identified notification topic. **status** `any` Status reported by the notification provider. All of: Variant 1: Mirrors Novu's common delete/mutate acknowledgement response. Model reference: [OperationStatus](/api/models/schema-ok4lj6t1ka#response). **acknowledged** `boolean` Whether the provider acknowledged the requested operation. **status** `string` Status reported by the notification provider. e.g., "done", "deleted" #### notifications-deleteTopic-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "status": { "acknowledged": true, "status": "example" } } ``` Document ID: `DOC-CP-notifications-api-deleteTopic`. [Section identities and revisions](/documentation-manifest.json). - Delete a notification topic: `DOC-CP-notifications-api-deleteTopic#overview` - Request: `DOC-CP-notifications-api-deleteTopic#request` - Responses: `DOC-CP-notifications-api-deleteTopic#responses` --- # Delete a notification workflow URL: https://docs.travila.ai/api/notifications/delete-workflow **POST** `/api/v1/notifications/manage/delete-workflow` Deletes a notification workflow. The workflow can be identified by either workflow ID or trigger identifier. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` tenant\_id and environment derived from auth headers by gateway. **workflowId** `string` Identifier of the notification workflow selected for deletion. **triggerIdentifier** `string` Trigger identifier used to address a notification workflow. #### notifications-deleteWorkflow-request Retire an existing workflow after stopping new triggers. ```json { "workflowId": "welcome-notification" } ``` ## Responses ### 200 — Workflow deleted Content type: `application/json` Result payload for removing an identified notification workflow definition. **workflowId** `string` Identifier of the notification workflow selected for deletion. #### notifications-deleteWorkflow-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "workflowId": "example_123" } ``` Document ID: `DOC-CP-notifications-api-deleteWorkflow`. [Section identities and revisions](/documentation-manifest.json). - Delete a notification workflow: `DOC-CP-notifications-api-deleteWorkflow#overview` - Request: `DOC-CP-notifications-api-deleteWorkflow#request` - Responses: `DOC-CP-notifications-api-deleteWorkflow#responses` --- # Get delivery status of a notification URL: https://docs.travila.ai/api/notifications/get-delivery-status **POST** `/api/v1/notifications/manage/get-delivery-status` Returns the current delivery status and metadata for a specific notification transaction, including provider-level details and timestamps. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for reading provider activity for a notification transaction. **transactionId** `string` **required** Identifier correlating a notification trigger with later status or cancellation requests. Minimum length: 1 #### notifications-getDeliveryStatus-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "transactionId": "example_123" } ``` ## Responses ### 200 — Delivery status returned Content type: `application/json` Result payload for reading provider activity for a notification transaction. **activity** `map[string, any]` Notification activity entries returned by the provider. #### notifications-getDeliveryStatus-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "activity": { "example": "value" } } ``` Document ID: `DOC-CP-notifications-api-getDeliveryStatus`. [Section identities and revisions](/documentation-manifest.json). - Get delivery status of a notification: `DOC-CP-notifications-api-getDeliveryStatus#overview` - Request: `DOC-CP-notifications-api-getDeliveryStatus#request` - Responses: `DOC-CP-notifications-api-getDeliveryStatus#responses` --- # Get inbox feed messages URL: https://docs.travila.ai/api/notifications/get-inbox-feed **POST** `/api/v1/notifications/get-inbox-feed` Returns a paginated list of in-app inbox messages for the authenticated user, applying the supplied selection criteria. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for reading the caller’s notification inbox feed. Caller user\_id is derived from authentication headers by the gateway. **page** `string(int64)` Page number used by this listing operation, starting at 1. Pattern: ^-?\d+$ **pageSize** `string(int64)` Number of entries requested per page. Zero or omission lets the server choose its default. Pattern: ^-?\d+$ **filter** `any` Selection criteria applied to the listing. All of: Variant 1: Read-state, category, tag, and archive criteria selecting inbox entries. Model reference: [InboxFeedFilter](/api/models/schema-ojrenemkui#request). **unseenOnly** `boolean` Whether the inbox filter selects only unseen messages. **unreadOnly** `boolean` Whether the inbox filter selects only unread messages. **feedIds** `array[string]` Filter by Novu feed identifiers. Type: `string` **categories** `array[string]` Categories used to select inbox messages. Type: `string` **tags** `array[string]` Filter by workflow tags (OR logic per Novu semantics). Type: `string` **archived** `boolean` When true, include archived messages. False or omission selects the live inbox and excludes archived messages. #### notifications-getInboxFeed-request Read the selected user’s inbox using default paging and filters. ```json {} ``` ## Responses ### 200 — Inbox feed retrieved successfully Content type: `application/json` Result payload for paging through a subscriber’s inbox with read-state and category filters. **messages** `array[notification_v1_InboxMessage]` Inbox messages returned after applying the selected query or state change. Notification content and interaction state displayed in a subscriber’s inbox. Model reference: [InboxMessage](/api/models/schema-1kescd68ar#response). **messageId** `string` Identifier of the message represented by this inbox entry. **notificationId** `string` Identifier of the notification represented by this inbox entry. **title** `string` Title displayed for the inbox notification. **body** `string` Body text of the inbox message. **data** `map[string, string]` Additional key-value attributes attached to the inbox notification. **deepLink** `string` Application deep link associated with the inbox message. **imageUrl** `string` Image URL associated with the inbox message. **status** `any` Read, seen, or archived state recorded for the inbox message. Inbox state or requested state transition for a notification message.
| Value | No. | Form | Meaning | |---|---|---|---| | `MESSAGE_STATUS_UNSEEN` | 0 | Canonical | The message has not been marked seen or read. | | `MESSAGE_STATUS_SEEN` | 1 | Canonical | The message has been marked seen and is not marked read or archived. | | `MESSAGE_STATUS_READ` | 2 | Canonical | The message has been marked read and is not archived. | | `MESSAGE_STATUS_UNREAD` | 3 | Canonical | Request clearing the read state; this is an update action rather than a distinct status emitted by message reads. | | `MESSAGE_STATUS_ARCHIVED` | 4 | Canonical | The message has been archived; this state takes precedence over seen and read when reported. |
Exactly one of: Variant 1: Type: `string` Enum: `MESSAGE_STATUS_UNSEEN`, `MESSAGE_STATUS_SEEN`, `MESSAGE_STATUS_READ`, `MESSAGE_STATUS_UNREAD`, `MESSAGE_STATUS_ARCHIVED` Variant 2: Type: `integer(int32)` **category** `string` Category assigned to the inbox message or workflow. **createdAt** `string(date-time)` Time when this record was created. **seenAt** `string(date-time)` Time when the inbox message was marked seen. **readAt** `string(date-time)` Time when the inbox message was marked read. **actions** `array[notification_v1_InboxMessageAction]` Interactive actions attached to the inbox message. CTA buttons Interactive action attached to an inbox message, including completion state. Model reference: [InboxMessageAction](/api/models/schema-1kcu6c9rot#response). **actionId** `string` Identifier of an action attached to the inbox message. **label** `string` Display label for the inbox action. **url** `string` Destination URL opened by this inbox action. **isPrimary** `boolean` Whether the inbox action is designated as the primary action. **completed** `boolean` Whether the user has completed this action via CompleteInboxAction. **completedAt** `string(date-time)` Time when this inbox action was marked complete. **tags** `array[string]` Workflow tags for tab assignment (OR-filtered in feed). Type: `string` **archived** `boolean` Whether this inbox notification is archived. **archivedAt** `string(date-time)` Time when the inbox message was archived. **totalCount** `string(int64)` Total number of matching entries reported by the operation. Pattern: ^-?\d+$ **page** `string(int64)` Page number reported for the returned inbox feed. Pattern: ^-?\d+$ **pageSize** `string(int64)` Page size reported for the returned inbox feed. Pattern: ^-?\d+$ **hasMore** `boolean` Whether the listing reports additional entries beyond this page. #### notifications-getInboxFeed-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "messages": [ { "messageId": "example_123", "notificationId": "example_123", "title": "example", "body": "example", "data": {}, "deepLink": "example", "imageUrl": "https://example.com/resource", "status": "MESSAGE_STATUS_UNSEEN", "category": "example", "createdAt": "2026-09-16T12:00:00Z", "seenAt": "2026-09-16T12:00:00Z", "readAt": "2026-09-16T12:00:00Z", "actions": [ { "actionId": "example_123", "label": "example", "url": "https://example.com/resource", "isPrimary": true, "completed": true } ], "tags": [ "example" ], "archived": true, "archivedAt": "2026-09-16T12:00:00Z" } ], "totalCount": 1, "page": 1, "pageSize": 1, "hasMore": true } ``` Document ID: `DOC-CP-notifications-api-getInboxFeed`. [Section identities and revisions](/documentation-manifest.json). - Get inbox feed messages: `DOC-CP-notifications-api-getInboxFeed#overview` - Request: `DOC-CP-notifications-api-getInboxFeed#request` - Responses: `DOC-CP-notifications-api-getInboxFeed#responses` --- # Get an inbox session token URL: https://docs.travila.ai/api/notifications/get-inbox-session **POST** `/api/v1/notifications/get-inbox-session` Returns a session token and connection URLs for the real-time in-app inbox. The token is short-lived and should be refreshed before expiry. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox) · [Inbox state and actions](/api/notifications/inbox) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Caller user\_id derived from auth headers by gateway. #### notifications-getInboxSession-request Create an inbox session for the selected user; identity comes from authentication. ```json {} ``` ## Responses ### 200 — Inbox session created successfully Content type: `application/json` Result payload for issuing connection details for a subscriber’s inbox session. **token** `string` Token issued for the subscriber’s inbox session. **socketUrl** `string` WebSocket endpoint provided for the inbox session. **expiresIn** `string(int64)` Remaining lifetime of the inbox session token, in seconds. Pattern: ^-?\d+$ #### notifications-getInboxSession-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "token": "example", "socketUrl": "https://example.com/resource", "expiresIn": "1" } ``` Document ID: `DOC-CP-notifications-api-getInboxSession`. [Section identities and revisions](/documentation-manifest.json). - Get an inbox session token: `DOC-CP-notifications-api-getInboxSession#overview` - Request: `DOC-CP-notifications-api-getInboxSession#request` - Responses: `DOC-CP-notifications-api-getInboxSession#responses` --- # Get unseen and unread inbox counts URL: https://docs.travila.ai/api/notifications/get-inbox-unseen-count **POST** `/api/v1/notifications/get-inbox-unseen-count` Returns the number of unseen and unread messages in the user's inbox, optionally filtered by feed IDs. Counts are capped. Inspect the overflow flags before treating them as exact totals. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Caller user\_id derived from auth headers by gateway. **feedIds** `array[string]` Feed identifiers used to select inbox messages. Type: `string` #### notifications-getInboxUnseenCount-request Count unseen messages in the selected user’s inbox. ```json {} ``` ## Responses ### 200 — Counts retrieved successfully Content type: `application/json` Result payload for counting unseen inbox notifications in selected feeds. **unseenCount** `string(int64)` Number of inbox messages reported unseen, capped at 10. Check has\_more\_unseen before treating this count as an exact total. Pattern: ^-?\d+$ **unreadCount** `string(int64)` Number of inbox messages reported unread, capped at 10. Check has\_more\_unread before treating this count as an exact total. Pattern: ^-?\d+$ **hasMoreUnseen** `boolean` Whether unseen messages exceed the capped count. When true, a badge can display "9+". **hasMoreUnread** `boolean` Whether unread messages exceed the capped count. When true, a badge can display "9+". #### notifications-getInboxUnseenCount-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "unseenCount": 1, "unreadCount": 1, "hasMoreUnseen": true, "hasMoreUnread": true } ``` Document ID: `DOC-CP-notifications-api-getInboxUnseenCount`. [Section identities and revisions](/documentation-manifest.json). - Get unseen and unread inbox counts: `DOC-CP-notifications-api-getInboxUnseenCount#overview` - Request: `DOC-CP-notifications-api-getInboxUnseenCount#request` - Responses: `DOC-CP-notifications-api-getInboxUnseenCount#responses` --- # Get notification activity log URL: https://docs.travila.ai/api/notifications/get-notification-activity **POST** `/api/v1/notifications/manage/get-notification-activity` Returns provider activity pages for diagnosing delivery across recipients. Provider activity can lag delivery and is not a complete authorization or business-outcome audit. Use a bounded time window to inspect failures, and keep successful recipients usable while you investigate. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration) · [Preferences and channel inheritance](/api/notifications/preferences) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Caller user\_id derived from auth headers by gateway. **page** `string(int64)` Page number used by this listing operation. Pattern: ^-?\d+$ **pageSize** `string(int64)` Number of entries requested per page. Zero or omission lets the server choose its default. Pattern: ^-?\d+$ **channels** `array[string]` Provider delivery-channel names used to restrict the query, such as "in\_app" and "push". These are provider strings, not CHANNEL\_\* enum names. Type: `string` **from** `string(date-time)` Lower time bound for the notification activity query. **to** `string(date-time)` Upper time bound for the notification activity query. **subscriberIds** `array[string]` When supplied, restrict notification activity to these subscriber identifiers. Type: `string` #### notifications-getNotificationActivity-request Read notification activity using default paging and filters. ```json {} ``` ## Responses ### 200 — Activity log returned Content type: `application/json` Result payload for querying delivery activity for a user across a selected time range. **entries** `array[map[string, any]]` Notification delivery activity entries returned for the selected query. Type: `map[string, any]` **hasMore** `boolean` Whether the listing reports additional entries beyond this page. #### notifications-getNotificationActivity-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "entries": [ { "example": "value" } ], "hasMore": true } ``` Document ID: `DOC-CP-notifications-api-getNotificationActivity`. [Section identities and revisions](/documentation-manifest.json). - Get notification activity log: `DOC-CP-notifications-api-getNotificationActivity#overview` - Request: `DOC-CP-notifications-api-getNotificationActivity#request` - Responses: `DOC-CP-notifications-api-getNotificationActivity#responses` --- # Get pending workflow changes URL: https://docs.travila.ai/api/notifications/get-pending-changes **POST** `/api/v1/notifications/manage/get-pending-changes` Returns pending workflow edits in the notification provider’s development configuration. These provider environments do not create separate Travila projects or test/live isolation. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Request for pending notification configuration changes. Tenant identity is derived from authentication headers by the gateway. #### notifications-getPendingChanges-request List pending notification configuration changes in the configured environment. ```json {} ``` ## Responses ### 200 — Pending changes returned Content type: `application/json` Result payload for listing notification configuration changes awaiting promotion. **changes** `array[notification_v1_PendingChange]` Pending notification configuration changes returned by the provider. Notification configuration change awaiting promotion to another provider environment. Model reference: [PendingChange](/api/models/schema-ok6l245g8f#response). **changeId** `string` Identifier of a pending notification configuration change. **type** `string` Kind of notification resource affected by the pending configuration change. "NotificationTemplate", "MessageTemplate", etc. **entityName** `string` Name of the notification resource affected by the pending change. **entityId** `string` Identifier of the notification resource affected by the pending change. **createdAt** `string(date-time)` Time when this record was created. **createdBy** `string` Identifier of the actor that created the pending change. **totalCount** `string(int64)` Total number of matching entries reported by the operation. Pattern: ^-?\d+$ #### notifications-getPendingChanges-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "changes": [ { "changeId": "example_123", "type": "example", "entityName": "example", "entityId": "example_123", "createdAt": "2026-09-16T12:00:00Z", "createdBy": "example" } ], "totalCount": 1 } ``` Document ID: `DOC-CP-notifications-api-getPendingChanges`. [Section identities and revisions](/documentation-manifest.json). - Get pending workflow changes: `DOC-CP-notifications-api-getPendingChanges#overview` - Request: `DOC-CP-notifications-api-getPendingChanges#request` - Responses: `DOC-CP-notifications-api-getPendingChanges#responses` --- # Get notification preferences URL: https://docs.travila.ai/api/notifications/get-preferences **POST** `/api/v1/notifications/get-preferences` Returns the authenticated user's notification preferences, including per-channel and per-category settings. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Manage notification preferences](/core-platform/notifications/preferences) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Request for the caller’s hierarchical notification preferences. Caller user\_id is derived from authentication headers by the gateway. #### notifications-getPreferences-request Read notification preferences for the selected user. ```json {} ``` ## Responses ### 200 — Preferences retrieved successfully Content type: `application/json` Result payload for reading global and workflow-specific channel preferences for a subscriber. **global** `any` Subscriber preferences that apply across notification workflows. All of: Variant 1: Subscriber's global (all-workflow) notification preferences. Model reference: [GlobalPreferences](/api/models/schema-p20l2ff92r#response). **enabled** `boolean` Master switch — false disables all non-critical notifications. **channels** `any` Channel switches recorded for these subscriber preferences. All of: Variant 1: Per-channel notification toggles. All fields are optional so callers can patch only the channels they want to change; omitted fields remain unchanged. Model reference: [ChannelToggles](/api/models/schema-oj4cvo85fs#response). **inApp** `boolean` Whether in-app notification delivery is enabled. **push** `boolean` Whether push notification delivery is enabled. **email** `boolean` Whether email notification delivery is enabled. **sms** `boolean` Whether SMS notification delivery is enabled. **chat** `boolean` Whether chat notification delivery is enabled. **workflows** `array[notification_v1_WorkflowPreferences]` Subscriber channel preferences for individual notification workflows. Per-workflow notification channel preferences for a subscriber. Model reference: [WorkflowPreferences](/api/models/schema-p2jctrvcjc#response). **workflowId** `string` Novu workflow identifier (slug). **workflowName** `string` Human-readable display name. **critical** `boolean` If true, subscriber cannot opt out (admin-enforced). **tags** `array[string]` Workflow tags for grouping in settings UI. Type: `string` **channels** `any` Channel switches recorded for these subscriber preferences. All of: Variant 1: Per-channel notification toggles. All fields are optional so callers can patch only the channels they want to change; omitted fields remain unchanged. Model reference: [ChannelToggles](/api/models/schema-oj4cvo85fs#response). **inApp** `boolean` Whether in-app notification delivery is enabled. **push** `boolean` Whether push notification delivery is enabled. **email** `boolean` Whether email notification delivery is enabled. **sms** `boolean` Whether SMS notification delivery is enabled. **chat** `boolean` Whether chat notification delivery is enabled. #### notifications-getPreferences-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "global": { "enabled": true, "channels": { "inApp": true, "push": true, "email": true, "sms": true, "chat": true } }, "workflows": [ { "workflowId": "example_123", "workflowName": "example", "critical": true, "tags": [ "example" ], "channels": { "inApp": true, "push": true, "email": true, "sms": true, "chat": true } } ] } ``` Document ID: `DOC-CP-notifications-api-getPreferences`. [Section identities and revisions](/documentation-manifest.json). - Get notification preferences: `DOC-CP-notifications-api-getPreferences#overview` - Request: `DOC-CP-notifications-api-getPreferences#request` - Responses: `DOC-CP-notifications-api-getPreferences#responses` --- # List configured providers URL: https://docs.travila.ai/api/notifications/get-providers **POST** `/api/v1/notifications/manage/get-providers` Returns active configured notification providers and their integration identifiers. Inactive providers are omitted. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` tenant\_id and environment derived from auth headers by gateway. #### notifications-getProviders-request List configured notification delivery providers. ```json {} ``` ## Responses ### 200 — Providers listed Content type: `application/json` Result payload for reading the configured notification delivery providers. **providers** `array[notification_v1_ProviderInfo]` Configured notification delivery providers. Configured notification provider and its integration identifier and active state. Model reference: [ProviderInfo](/api/models/schema-p28bvfiqrb#response). **provider** `any` Notification delivery provider being configured or reported. Service used to deliver a notification through its selected channel.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_TYPE_FCM` | 0 | Canonical | See meaning below. | | `PROVIDER_TYPE_APNS` | 1 | Canonical | See meaning below. | | `PROVIDER_TYPE_SENDGRID` | 2 | Canonical | See meaning below. | | `PROVIDER_TYPE_SES` | 3 | Canonical | See meaning below. | | `PROVIDER_TYPE_TWILIO` | 4 | Canonical | See meaning below. | | `PROVIDER_TYPE_SLACK` | 5 | Canonical | See meaning below. | | `PROVIDER_TYPE_DISCORD` | 6 | Canonical | See meaning below. | **`PROVIDER_TYPE_FCM`** Firebase Cloud Messaging for device or web push delivery. Firebase Cloud Messaging (push) **`PROVIDER_TYPE_APNS`** Apple Push Notification service for Apple-device push delivery. Apple Push Notification Service **`PROVIDER_TYPE_SENDGRID`** SendGrid for email delivery. SendGrid (email) **`PROVIDER_TYPE_SES`** Amazon Simple Email Service for email delivery. AWS SES (email) **`PROVIDER_TYPE_TWILIO`** Twilio for SMS delivery. Twilio (SMS) **`PROVIDER_TYPE_SLACK`** Slack for chat-message delivery. Slack (chat) **`PROVIDER_TYPE_DISCORD`** Discord for chat-message delivery. Discord (chat)
Exactly one of: Variant 1: Type: `string` Enum: `PROVIDER_TYPE_FCM`, `PROVIDER_TYPE_APNS`, `PROVIDER_TYPE_SENDGRID`, `PROVIDER_TYPE_SES`, `PROVIDER_TYPE_TWILIO`, `PROVIDER_TYPE_SLACK`, `PROVIDER_TYPE_DISCORD` Variant 2: Type: `integer(int32)` **integrationId** `string` Identifier of the provider integration in Novu. **active** `boolean` Whether the resource is marked active. #### notifications-getProviders-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "providers": [ { "provider": "PROVIDER_TYPE_FCM", "integrationId": "example_123", "active": true } ] } ``` Document ID: `DOC-CP-notifications-api-getProviders`. [Section identities and revisions](/documentation-manifest.json). - List configured providers: `DOC-CP-notifications-api-getProviders#overview` - Request: `DOC-CP-notifications-api-getProviders#request` - Responses: `DOC-CP-notifications-api-getProviders#responses` --- # Get registered notification channels URL: https://docs.travila.ai/api/notifications/get-registered-channels **POST** `/api/v1/notifications/get-registered-channels` Returns the list of notification channels and their registration status for the authenticated user. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Keep push notifications attached to the signed-in user](/core-platform/notifications/push) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Caller user\_id derived from auth headers by gateway. #### notifications-getRegisteredChannels-request Read the notification channels registered for the selected user. ```json {} ``` ## Responses ### 200 — Channels retrieved successfully Content type: `application/json` Result payload for reading the notification channels with registered delivery credentials. **channels** `array[notification_v1_ChannelRegistration]` Registration status and credential counts for the subscriber’s delivery channels. Registration state and credential count for one notification channel. Model reference: [ChannelRegistration](/api/models/schema-1kaqut27uf#response). **channel** `any` Notification channel represented by this registration. Delivery channel for a notification that does not expect a reply.
| Value | No. | Form | Meaning | |---|---|---|---| | `CHANNEL_PUSH` | 0 | Canonical | See meaning below. | | `CHANNEL_IN_APP` | 1 | Canonical | See meaning below. | | `CHANNEL_EMAIL` | 2 | Canonical | See meaning below. | | `CHANNEL_SMS` | 3 | Canonical | See meaning below. | | `CHANNEL_CHAT` | 4 | Canonical | See meaning below. | **`CHANNEL_PUSH`** Deliver a device push notification through the configured push provider. FCM/APNS push notifications **`CHANNEL_IN_APP`** Deliver the notification to the in-app inbox. Novu Inbox (notification center) **`CHANNEL_EMAIL`** Send a one-way email notification through the configured email provider. SendGrid/SES - do-not-reply only **`CHANNEL_SMS`** Send a one-way SMS notification, such as an alert or authentication message. Twilio - do-not-reply only (alerts, 2FA) **`CHANNEL_CHAT`** Send a one-way message to an integrated chat destination. Slack, Discord, MS Teams - one-way notifications
Exactly one of: Variant 1: Type: `string` Enum: `CHANNEL_PUSH`, `CHANNEL_IN_APP`, `CHANNEL_EMAIL`, `CHANNEL_SMS`, `CHANNEL_CHAT` Variant 2: Type: `integer(int32)` **registered** `boolean` Whether the subscriber has a registration for this channel. **credentialCount** `string(int64)` Number of delivery credentials registered for the channel. e.g., number of device tokens Pattern: ^-?\d+$ #### notifications-getRegisteredChannels-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "channels": [ { "channel": "CHANNEL_PUSH", "registered": true, "credentialCount": 1 } ] } ``` Document ID: `DOC-CP-notifications-api-getRegisteredChannels`. [Section identities and revisions](/documentation-manifest.json). - Get registered notification channels: `DOC-CP-notifications-api-getRegisteredChannels#overview` - Request: `DOC-CP-notifications-api-getRegisteredChannels#request` - Responses: `DOC-CP-notifications-api-getRegisteredChannels#responses` --- # Get the caller's subscriber profile URL: https://docs.travila.ai/api/notifications/get-subscriber **POST** `/api/v1/notifications/manage/get-subscriber` Returns the subscriber profile for the authenticated caller, including channel registrations and notification preferences. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Caller user\_id derived from auth headers by gateway. #### notifications-getSubscriber-request Read the subscriber selected by authentication; no subscriber ID is accepted in this body. ```json {} ``` ## Responses ### 200 — Subscriber profile returned Content type: `application/json` Result payload for retrieving a notification subscriber’s contact and custom attributes. **subscriberId** `string` Identifier of the notification subscriber. **data** `any` Contact, locale, and custom attributes returned for the subscriber. All of: Variant 1: Contact, locale, and custom attributes used by notification delivery. Model reference: [SubscriberData](/api/models/schema-1kgdnn5p53#response). **firstName** `string` Subscriber’s given name. **lastName** `string` Subscriber’s family name. **email** `string` Email address used for subscriber contact and delivery. **phone** `string` Phone number used for subscriber contact and delivery. **avatarUrl** `string` URL of the subscriber’s avatar image. **locale** `string` Subscriber locale used when rendering notifications. e.g., "en-US" **timezone** `string` Subscriber time zone used for notification presentation. e.g., "America/Los\_Angeles" **customData** `map[string, string]` Additional template variables. **channels** `array[notification_v1_ChannelRegistration]` Registration status and credential counts for the subscriber’s delivery channels. Registration state and credential count for one notification channel. Model reference: [ChannelRegistration](/api/models/schema-1kaqut27uf#response). **channel** `any` Notification channel represented by this registration. Delivery channel for a notification that does not expect a reply.
| Value | No. | Form | Meaning | |---|---|---|---| | `CHANNEL_PUSH` | 0 | Canonical | See meaning below. | | `CHANNEL_IN_APP` | 1 | Canonical | See meaning below. | | `CHANNEL_EMAIL` | 2 | Canonical | See meaning below. | | `CHANNEL_SMS` | 3 | Canonical | See meaning below. | | `CHANNEL_CHAT` | 4 | Canonical | See meaning below. | **`CHANNEL_PUSH`** Deliver a device push notification through the configured push provider. FCM/APNS push notifications **`CHANNEL_IN_APP`** Deliver the notification to the in-app inbox. Novu Inbox (notification center) **`CHANNEL_EMAIL`** Send a one-way email notification through the configured email provider. SendGrid/SES - do-not-reply only **`CHANNEL_SMS`** Send a one-way SMS notification, such as an alert or authentication message. Twilio - do-not-reply only (alerts, 2FA) **`CHANNEL_CHAT`** Send a one-way message to an integrated chat destination. Slack, Discord, MS Teams - one-way notifications
Exactly one of: Variant 1: Type: `string` Enum: `CHANNEL_PUSH`, `CHANNEL_IN_APP`, `CHANNEL_EMAIL`, `CHANNEL_SMS`, `CHANNEL_CHAT` Variant 2: Type: `integer(int32)` **registered** `boolean` Whether the subscriber has a registration for this channel. **credentialCount** `string(int64)` Number of delivery credentials registered for the channel. e.g., number of device tokens Pattern: ^-?\d+$ **createdAt** `string(date-time)` Time when this record was created. **updatedAt** `string(date-time)` Time when this record was last updated. **globalPreferences** `any` Subscriber preferences that apply across notification workflows. All of: Variant 1: Subscriber's global (all-workflow) notification preferences. Model reference: [GlobalPreferences](/api/models/schema-p20l2ff92r#response). **enabled** `boolean` Master switch — false disables all non-critical notifications. **channels** `any` Channel switches recorded for these subscriber preferences. All of: Variant 1: Per-channel notification toggles. All fields are optional so callers can patch only the channels they want to change; omitted fields remain unchanged. Model reference: [ChannelToggles](/api/models/schema-oj4cvo85fs#response). **inApp** `boolean` Whether in-app notification delivery is enabled. **push** `boolean` Whether push notification delivery is enabled. **email** `boolean` Whether email notification delivery is enabled. **sms** `boolean` Whether SMS notification delivery is enabled. **chat** `boolean` Whether chat notification delivery is enabled. **workflowPreferences** `array[notification_v1_WorkflowPreferences]` Subscriber preferences scoped to individual notification workflows. Per-workflow notification channel preferences for a subscriber. Model reference: [WorkflowPreferences](/api/models/schema-p2jctrvcjc#response). **workflowId** `string` Novu workflow identifier (slug). **workflowName** `string` Human-readable display name. **critical** `boolean` If true, subscriber cannot opt out (admin-enforced). **tags** `array[string]` Workflow tags for grouping in settings UI. Type: `string` **channels** `any` Channel switches recorded for these subscriber preferences. All of: Variant 1: Per-channel notification toggles. All fields are optional so callers can patch only the channels they want to change; omitted fields remain unchanged. Model reference: [ChannelToggles](/api/models/schema-oj4cvo85fs#response). **inApp** `boolean` Whether in-app notification delivery is enabled. **push** `boolean` Whether push notification delivery is enabled. **email** `boolean` Whether email notification delivery is enabled. **sms** `boolean` Whether SMS notification delivery is enabled. **chat** `boolean` Whether chat notification delivery is enabled. #### notifications-getSubscriber-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "subscriberId": "example_123", "data": { "firstName": "example", "lastName": "example", "email": "user@example.com", "phone": "example", "avatarUrl": "https://example.com/resource", "locale": "en-US", "timezone": "example", "customData": {} }, "channels": [ { "channel": "CHANNEL_PUSH", "registered": true, "credentialCount": 1 } ], "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z", "globalPreferences": { "enabled": true, "channels": { "inApp": true, "push": true, "email": true, "sms": true, "chat": true } }, "workflowPreferences": [ { "workflowId": "example_123", "workflowName": "example", "critical": true, "tags": [ "example" ], "channels": { "inApp": true, "push": true, "email": true, "sms": true, "chat": true } } ] } ``` Document ID: `DOC-CP-notifications-api-getSubscriber`. [Section identities and revisions](/documentation-manifest.json). - Get the caller's subscriber profile: `DOC-CP-notifications-api-getSubscriber#overview` - Request: `DOC-CP-notifications-api-getSubscriber#request` - Responses: `DOC-CP-notifications-api-getSubscriber#responses` --- # Get a notification workflow URL: https://docs.travila.ai/api/notifications/get-workflow **POST** `/api/v1/notifications/manage/get-workflow` Returns the full workflow definition and metadata for the supplied workflow ID. A trigger identifier alone does not select the workflow. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` tenant\_id and environment derived from auth headers by gateway. **workflowId** `string` Identifier of the notification workflow to retrieve. **triggerIdentifier** `string` Trigger identifier used to address a notification workflow. #### notifications-getWorkflow-request Read an existing workflow using its saved workflow identifier. ```json { "workflowId": "welcome-notification" } ``` ## Responses ### 200 — Workflow returned Content type: `application/json` Result payload for retrieving a notification workflow by identifier or trigger name. **workflow** `map[string, any]` Notification workflow definition supplied to or returned by the provider. #### notifications-getWorkflow-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "workflow": { "example": "value" } } ``` Document ID: `DOC-CP-notifications-api-getWorkflow`. [Section identities and revisions](/documentation-manifest.json). - Get a notification workflow: `DOC-CP-notifications-api-getWorkflow#overview` - Request: `DOC-CP-notifications-api-getWorkflow#request` - Responses: `DOC-CP-notifications-api-getWorkflow#responses` --- # List all subscribers URL: https://docs.travila.ai/api/notifications/list-subscribers **POST** `/api/v1/notifications/manage/list-subscribers` Returns a paginated list of all subscriber profiles in the notification system. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` tenant\_id and environment derived from auth headers by gateway. **page** `string(int64)` Page number used by this listing operation. Pattern: ^-?\d+$ **pageSize** `string(int64)` Number of entries requested per page. Zero or omission lets the server choose its default. Pattern: ^-?\d+$ #### notifications-listSubscribers-request List subscribers in the authenticated tenant with default paging. ```json {} ``` ## Responses ### 200 — Subscribers listed Content type: `application/json` Result payload for paging through notification subscribers and their presence summaries. **subscribers** `array[notification_v1_SubscriberSummary]` Subscriber records returned by the listing. Contact and presence information returned in a subscriber listing. Model reference: [SubscriberSummary](/api/models/schema-okk1bp39s4#response). **subscriberId** `string` Identifier of the notification subscriber. **email** `string` Email address used for subscriber contact and delivery. **firstName** `string` Subscriber’s given name. **lastName** `string` Subscriber’s family name. **isOnline** `boolean` Whether the provider reports the subscriber currently online. **lastOnlineAt** `string(date-time)` Time when the provider last observed the subscriber online. **totalCount** `string(int64)` Total number of matching entries reported by the operation. Pattern: ^-?\d+$ **hasMore** `boolean` Whether the listing reports additional entries beyond this page. #### notifications-listSubscribers-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "subscribers": [ { "subscriberId": "example_123", "email": "user@example.com", "firstName": "example", "lastName": "example", "isOnline": true, "lastOnlineAt": "2026-09-16T12:00:00Z" } ], "totalCount": 1, "hasMore": true } ``` Document ID: `DOC-CP-notifications-api-listSubscribers`. [Section identities and revisions](/documentation-manifest.json). - List all subscribers: `DOC-CP-notifications-api-listSubscribers#overview` - Request: `DOC-CP-notifications-api-listSubscribers#request` - Responses: `DOC-CP-notifications-api-listSubscribers#responses` --- # List subscribers of a topic URL: https://docs.travila.ai/api/notifications/list-topic-subscribers **POST** `/api/v1/notifications/manage/list-topic-subscribers` Returns the first page of user IDs subscribed to the selected topic, bounded by page\_size. The page field does not advance the result, and no continuation cursor is returned. A true has\_more value does not provide a way to retrieve the next page through this operation. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Broadcast with topics](/core-platform/notifications/topics) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for paging through members of a selected notification topic. **topicKey** `string` **required** Caller-facing key identifying a notification topic. Minimum length: 1 **page** `string(int64)` Page number used by this listing operation. Pattern: ^-?\d+$ **pageSize** `string(int64)` Number of entries requested per page. Zero or omission lets the server choose its default. Pattern: ^-?\d+$ #### notifications-listTopicSubscribers-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "topicKey": "example_123" } ``` ## Responses ### 200 — Topic subscribers listed Content type: `application/json` Result payload for paging through members of a selected notification topic. **userIds** `array[string]` Identifiers of the users selected by the operation. Type: `string` **totalCount** `string(int64)` Total number of matching entries reported by the operation. Pattern: ^-?\d+$ **hasMore** `boolean` Whether the listing reports additional entries beyond this page. #### notifications-listTopicSubscribers-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "userIds": [ "example_123" ], "totalCount": 1, "hasMore": true } ``` Document ID: `DOC-CP-notifications-api-listTopicSubscribers`. [Section identities and revisions](/documentation-manifest.json). - List subscribers of a topic: `DOC-CP-notifications-api-listTopicSubscribers#overview` - Request: `DOC-CP-notifications-api-listTopicSubscribers#request` - Responses: `DOC-CP-notifications-api-listTopicSubscribers#responses` --- # List notification workflows URL: https://docs.travila.ai/api/notifications/list-workflows **POST** `/api/v1/notifications/manage/list-workflows` Returns a paginated list of all notification workflows with summary information. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` tenant\_id and environment derived from auth headers by gateway. **page** `string(int64)` Page number used by this listing operation. Pattern: ^-?\d+$ **pageSize** `string(int64)` Number of entries requested per page. Zero or omission lets the server choose its default. Pattern: ^-?\d+$ #### notifications-listWorkflows-request List notification workflows with default paging. ```json {} ``` ## Responses ### 200 — Workflows listed Content type: `application/json` Result payload for paging through available notification workflow definitions. **workflows** `array[map[string, any]]` Notification workflow definitions returned by the listing. Type: `map[string, any]` **totalCount** `string(int64)` Total number of matching entries reported by the operation. Pattern: ^-?\d+$ **hasMore** `boolean` Whether the listing reports additional entries beyond this page. #### notifications-listWorkflows-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "workflows": [ { "example": "value" } ], "totalCount": 1, "hasMore": true } ``` Document ID: `DOC-CP-notifications-api-listWorkflows`. [Section identities and revisions](/documentation-manifest.json). - List notification workflows: `DOC-CP-notifications-api-listWorkflows#overview` - Request: `DOC-CP-notifications-api-listWorkflows#request` - Responses: `DOC-CP-notifications-api-listWorkflows#responses` --- # Mark all inbox messages URL: https://docs.travila.ai/api/notifications/mark-all-inbox-messages-as **POST** `/api/v1/notifications/mark-all-inbox-messages` Marks all inbox messages as seen, read, unseen, or unread. Optionally scoped to specific feed IDs. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Caller user\_id derived from auth headers by gateway. **markAs** `any` Read or seen state to apply to the selected inbox messages. Inbox state or requested state transition for a notification message.
| Value | No. | Form | Meaning | |---|---|---|---| | `MESSAGE_STATUS_UNSEEN` | 0 | Canonical | The message has not been marked seen or read. | | `MESSAGE_STATUS_SEEN` | 1 | Canonical | The message has been marked seen and is not marked read or archived. | | `MESSAGE_STATUS_READ` | 2 | Canonical | The message has been marked read and is not archived. | | `MESSAGE_STATUS_UNREAD` | 3 | Canonical | Request clearing the read state; this is an update action rather than a distinct status emitted by message reads. | | `MESSAGE_STATUS_ARCHIVED` | 4 | Canonical | The message has been archived; this state takes precedence over seen and read when reported. |
Exactly one of: Variant 1: Type: `string` Enum: `MESSAGE_STATUS_UNSEEN`, `MESSAGE_STATUS_SEEN`, `MESSAGE_STATUS_READ`, `MESSAGE_STATUS_UNREAD`, `MESSAGE_STATUS_ARCHIVED` Variant 2: Type: `integer(int32)` **feedIds** `array[string]` Feed identifiers used to select inbox messages. Type: `string` #### notifications-markAllInboxMessagesAs-request Mark all inbox messages in the selected user scope as read. ```json { "markAs": "MESSAGE_STATUS_READ" } ``` ## Responses ### 200 — Messages marked successfully Content type: `application/json` Result payload for changing the read or seen state of selected inbox messages. **updatedCount** `string(int64)` Number of inbox messages reported updated. Pattern: ^-?\d+$ #### notifications-markAllInboxMessagesAs-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "updatedCount": 1 } ``` Document ID: `DOC-CP-notifications-api-markAllInboxMessagesAs`. [Section identities and revisions](/documentation-manifest.json). - Mark all inbox messages: `DOC-CP-notifications-api-markAllInboxMessagesAs#overview` - Request: `DOC-CP-notifications-api-markAllInboxMessagesAs#request` - Responses: `DOC-CP-notifications-api-markAllInboxMessagesAs#responses` --- # Mark a single inbox message URL: https://docs.travila.ai/api/notifications/mark-inbox-message-as **POST** `/api/v1/notifications/mark-inbox-message` Marks a specific inbox message as seen, read, unseen, or unread. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Caller user\_id derived from auth headers by gateway. **messageId** `string` **required** Identifier of the inbox message whose state is being changed. Minimum length: 1 **markAs** `any` Read or seen state to apply to the selected inbox message. Inbox state or requested state transition for a notification message.
| Value | No. | Form | Meaning | |---|---|---|---| | `MESSAGE_STATUS_UNSEEN` | 0 | Canonical | The message has not been marked seen or read. | | `MESSAGE_STATUS_SEEN` | 1 | Canonical | The message has been marked seen and is not marked read or archived. | | `MESSAGE_STATUS_READ` | 2 | Canonical | The message has been marked read and is not archived. | | `MESSAGE_STATUS_UNREAD` | 3 | Canonical | Request clearing the read state; this is an update action rather than a distinct status emitted by message reads. | | `MESSAGE_STATUS_ARCHIVED` | 4 | Canonical | The message has been archived; this state takes precedence over seen and read when reported. |
Exactly one of: Variant 1: Type: `string` Enum: `MESSAGE_STATUS_UNSEEN`, `MESSAGE_STATUS_SEEN`, `MESSAGE_STATUS_READ`, `MESSAGE_STATUS_UNREAD`, `MESSAGE_STATUS_ARCHIVED` Variant 2: Type: `integer(int32)` #### notifications-markInboxMessageAs-request Mark an existing inbox message as read. ```json { "messageId": "msg_123", "markAs": "MESSAGE_STATUS_READ" } ``` ## Responses ### 200 — Message marked successfully Content type: `application/json` Result payload for changing an inbox message’s read or seen state. **messages** `array[notification_v1_InboxMessageSummary]` Inbox messages returned after applying the requested read or seen state change. Summary of an inbox message after a mark operation. Model reference: [InboxMessageSummary](/api/models/schema-ojt6e86adl#response). **messageId** `string` Identifier of the inbox message represented by this summary. **channel** `string` Delivery channel reported for this inbox message. **read** `boolean` Whether the inbox message has been marked read. **seen** `boolean` Whether the inbox message has been marked seen. **archived** `boolean` Whether this inbox message is archived. **content** `string` Rendered notification content. **subject** `string` Subject text for the notification message. **status** `string` Status reported by the notification provider. **createdAt** `string` Time when this record was created. **lastReadDate** `string` Most recent timestamp recorded for reading inbox messages. **lastSeenDate** `string` Most recent timestamp recorded for seeing inbox messages. #### notifications-markInboxMessageAs-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "messages": [ { "messageId": "example_123", "channel": "example", "read": true, "seen": true, "archived": true, "content": "Example text", "subject": "example", "status": "example", "createdAt": "example", "lastReadDate": "example", "lastSeenDate": "example" } ] } ``` Document ID: `DOC-CP-notifications-api-markInboxMessageAs`. [Section identities and revisions](/documentation-manifest.json). - Mark a single inbox message: `DOC-CP-notifications-api-markInboxMessageAs#overview` - Request: `DOC-CP-notifications-api-markInboxMessageAs#request` - Responses: `DOC-CP-notifications-api-markInboxMessageAs#responses` --- # Notification APIs URL: https://docs.travila.ai/api/notifications Version: `aju17f20mq` Use the reference below for request and response fields and operation-specific requirements. # Overview \{#overview} Register devices, read inbox messages and manage notification preferences, workflows and dispatch. Provider and channel availability depend on deployment configuration. ## Authentication \{#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](https://docs.travila.ai/core-platform/identity-access/authentication). Public management operations under `/manage/` belong in trusted backend tooling. The API accepts a verified backend key or configured standalone JWT for tenant-context management; it does not enforce an operation-specific admin role or permission there. Do not treat this acceptance as a secure admin authorization contract. Restrict access at your application boundary. Get/update/delete of the caller’s subscriber profile still require user context. 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. Send acknowledgements mean the provider accepted a trigger, not that a recipient received or read it. Preference state, channel registration and topic membership do not by themselves establish consent or sending authority. **Related guide:** [Notifications](https://docs.travila.ai/core-platform/notifications) ### JSON conventions \{#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](https://docs.travila.ai/api). ## User: Channel Registration \{#reference-group-1} Register and manage push notification devices and channels. See the [Notifications guide](https://docs.travila.ai/core-platform/notifications). * [Register a push notification device](/api/notifications/register-push-device) * [Unregister a push notification device](/api/notifications/unregister-push-device) * [Get registered notification channels](/api/notifications/get-registered-channels) * [Get an inbox session token](/api/notifications/get-inbox-session) ## User: In-App Inbox \{#reference-group-2} Real-time in-app inbox — session token, feed, mark, and delete. See the [Notifications guide](https://docs.travila.ai/core-platform/notifications). * [Get inbox feed messages](/api/notifications/get-inbox-feed) * [Get unseen and unread inbox counts](/api/notifications/get-inbox-unseen-count) * [Mark a single inbox message](/api/notifications/mark-inbox-message-as) * [Mark all inbox messages](/api/notifications/mark-all-inbox-messages-as) * [Delete an inbox message](/api/notifications/delete-inbox-message) * [Archive an inbox message](/api/notifications/archive-inbox-message) * [Unarchive an inbox message](/api/notifications/unarchive-inbox-message) * [Archive all inbox messages](/api/notifications/archive-all-inbox-messages) * [Archive all read inbox messages](/api/notifications/archive-all-read-inbox-messages) * [Complete an inbox message action](/api/notifications/complete-inbox-action) * [Revert an inbox message action](/api/notifications/revert-inbox-action) ## User: Preferences \{#reference-group-3} Get and update per-channel notification preferences. See the [Notifications guide](https://docs.travila.ai/core-platform/notifications). * [Get notification preferences](/api/notifications/get-preferences) * [Update global notification preferences](/api/notifications/update-global-preference) * [Update per-workflow notification preferences](/api/notifications/update-workflow-preference) * [Bulk-update per-workflow preferences](/api/notifications/bulk-update-preferences) ## Management: Notification Dispatch \{#reference-group-4} Send, broadcast, bulk-send, topic-send, and cancel notifications. See the [Notifications guide](https://docs.travila.ai/core-platform/notifications). * [Send a notification to a user](/api/notifications/send-notification) * [Send a notification to multiple users](/api/notifications/send-bulk-notification) * [Cancel a pending notification](/api/notifications/cancel-notification) ## Management: Topics \{#reference-group-5} Pub/sub fan-out — create topics, manage subscribers, send to topic. See the [Notifications guide](https://docs.travila.ai/core-platform/notifications). * [Create a notification topic](/api/notifications/create-topic) * [Delete a notification topic](/api/notifications/delete-topic) * [Add subscribers to a topic](/api/notifications/add-subscribers-to-topic) * [Remove subscribers from a topic](/api/notifications/remove-subscribers-from-topic) * [List subscribers of a topic](/api/notifications/list-topic-subscribers) * [Check if a user is subscribed to a topic](/api/notifications/check-topic-subscription) * [Send a notification to all topic subscribers](/api/notifications/send-to-topic) ## Management: Digest \{#reference-group-6} Batched digest delivery and cancellation. See the [Notifications guide](https://docs.travila.ai/core-platform/notifications). * [Send a notification with digest aggregation](/api/notifications/send-with-digest) * [Cancel a pending digest event](/api/notifications/cancel-digest-event) ## Management: Subscribers \{#reference-group-7} Create, read, update, delete, and list notification subscribers. See the [Notifications guide](https://docs.travila.ai/core-platform/notifications). * [Create a notification subscriber](/api/notifications/create-subscriber) * [Get the caller's subscriber profile](/api/notifications/get-subscriber) * [Update subscriber profile data](/api/notifications/update-subscriber-data) * [Delete the caller's subscriber profile](/api/notifications/delete-subscriber) * [List all subscribers](/api/notifications/list-subscribers) ## Management: Activity & Status \{#reference-group-8} Query delivery status and notification activity logs. See the [Notifications guide](https://docs.travila.ai/core-platform/notifications). * [Get delivery status of a notification](/api/notifications/get-delivery-status) * [Get notification activity log](/api/notifications/get-notification-activity) ## Management: Providers \{#reference-group-9} Configure and list delivery providers (FCM, SendGrid, etc.). See the [Notifications guide](https://docs.travila.ai/core-platform/notifications). * [Configure a notification provider](/api/notifications/configure-provider) * [List configured providers](/api/notifications/get-providers) ## Management: Workflows \{#reference-group-10} Create, update, get, list, and delete notification workflows. See the [Notifications guide](https://docs.travila.ai/core-platform/notifications). * [Create a notification workflow](/api/notifications/create-workflow) * [Update an existing notification workflow](/api/notifications/update-workflow) * [Get a notification workflow](/api/notifications/get-workflow) * [List notification workflows](/api/notifications/list-workflows) * [Delete a notification workflow](/api/notifications/delete-workflow) * [Get pending workflow changes](/api/notifications/get-pending-changes) * [Promote a single workflow change](/api/notifications/promote-change) * [Promote all pending workflow changes](/api/notifications/promote-all-changes) ## Server 1 \{#reference-server-1} Travila API [https://api.travila.ai](https://api.travila.ai) ## X-API-Key \{#authentication-apiKeyAuth} 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 \{#authentication-onBehalfOf} 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 \{#authentication-bearerAuth} JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission.

Authentication credentials

### apiKeyAuth Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-API-Key` ### onBehalfOf Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-On-Behalf-Of` ### bearerAuth Security scheme type: `http` HTTP authorization scheme: `bearer` ## Operations - [Register a push notification device](/api/notifications/register-push-device) — `POST /api/v1/notifications/register-push-device` - [Unregister a push notification device](/api/notifications/unregister-push-device) — `POST /api/v1/notifications/unregister-push-device` - [Get registered notification channels](/api/notifications/get-registered-channels) — `POST /api/v1/notifications/get-registered-channels` - [Get an inbox session token](/api/notifications/get-inbox-session) — `POST /api/v1/notifications/get-inbox-session` - [Send a notification to a user](/api/notifications/send-notification) — `POST /api/v1/notifications/manage/send` - [Send a notification to multiple users](/api/notifications/send-bulk-notification) — `POST /api/v1/notifications/manage/send-bulk` - [Cancel a pending notification](/api/notifications/cancel-notification) — `POST /api/v1/notifications/manage/cancel` - [Get inbox feed messages](/api/notifications/get-inbox-feed) — `POST /api/v1/notifications/get-inbox-feed` - [Get unseen and unread inbox counts](/api/notifications/get-inbox-unseen-count) — `POST /api/v1/notifications/get-inbox-unseen-count` - [Mark a single inbox message](/api/notifications/mark-inbox-message-as) — `POST /api/v1/notifications/mark-inbox-message` - [Mark all inbox messages](/api/notifications/mark-all-inbox-messages-as) — `POST /api/v1/notifications/mark-all-inbox-messages` - [Delete an inbox message](/api/notifications/delete-inbox-message) — `POST /api/v1/notifications/delete-inbox-message` - [Archive an inbox message](/api/notifications/archive-inbox-message) — `POST /api/v1/notifications/archive-inbox-message` - [Unarchive an inbox message](/api/notifications/unarchive-inbox-message) — `POST /api/v1/notifications/unarchive-inbox-message` - [Archive all inbox messages](/api/notifications/archive-all-inbox-messages) — `POST /api/v1/notifications/archive-all-inbox-messages` - [Archive all read inbox messages](/api/notifications/archive-all-read-inbox-messages) — `POST /api/v1/notifications/archive-all-read-inbox-messages` - [Complete an inbox message action](/api/notifications/complete-inbox-action) — `POST /api/v1/notifications/complete-inbox-action` - [Revert an inbox message action](/api/notifications/revert-inbox-action) — `POST /api/v1/notifications/revert-inbox-action` - [Create a notification topic](/api/notifications/create-topic) — `POST /api/v1/notifications/manage/create-topic` - [Delete a notification topic](/api/notifications/delete-topic) — `POST /api/v1/notifications/manage/delete-topic` - [Add subscribers to a topic](/api/notifications/add-subscribers-to-topic) — `POST /api/v1/notifications/manage/add-subscribers-to-topic` - [Remove subscribers from a topic](/api/notifications/remove-subscribers-from-topic) — `POST /api/v1/notifications/manage/remove-subscribers-from-topic` - [List subscribers of a topic](/api/notifications/list-topic-subscribers) — `POST /api/v1/notifications/manage/list-topic-subscribers` - [Check if a user is subscribed to a topic](/api/notifications/check-topic-subscription) — `POST /api/v1/notifications/manage/check-topic-subscription` - [Send a notification to all topic subscribers](/api/notifications/send-to-topic) — `POST /api/v1/notifications/manage/send-to-topic` - [Send a notification with digest aggregation](/api/notifications/send-with-digest) — `POST /api/v1/notifications/manage/send-with-digest` - [Cancel a pending digest event](/api/notifications/cancel-digest-event) — `POST /api/v1/notifications/manage/cancel-digest-event` - [Get notification preferences](/api/notifications/get-preferences) — `POST /api/v1/notifications/get-preferences` - [Update global notification preferences](/api/notifications/update-global-preference) — `POST /api/v1/notifications/update-global-preference` - [Update per-workflow notification preferences](/api/notifications/update-workflow-preference) — `POST /api/v1/notifications/update-workflow-preference` - [Bulk-update per-workflow preferences](/api/notifications/bulk-update-preferences) — `POST /api/v1/notifications/bulk-update-preferences` - [Update subscriber profile data](/api/notifications/update-subscriber-data) — `POST /api/v1/notifications/manage/update-subscriber-data` - [Get the caller's subscriber profile](/api/notifications/get-subscriber) — `POST /api/v1/notifications/manage/get-subscriber` - [Delete the caller's subscriber profile](/api/notifications/delete-subscriber) — `POST /api/v1/notifications/manage/delete-subscriber` - [Create a notification subscriber](/api/notifications/create-subscriber) — `POST /api/v1/notifications/manage/create-subscriber` - [List all subscribers](/api/notifications/list-subscribers) — `POST /api/v1/notifications/manage/list-subscribers` - [Get delivery status of a notification](/api/notifications/get-delivery-status) — `POST /api/v1/notifications/manage/get-delivery-status` - [Get notification activity log](/api/notifications/get-notification-activity) — `POST /api/v1/notifications/manage/get-notification-activity` - [Configure a notification provider](/api/notifications/configure-provider) — `POST /api/v1/notifications/manage/configure-provider` - [List configured providers](/api/notifications/get-providers) — `POST /api/v1/notifications/manage/get-providers` - [Create a notification workflow](/api/notifications/create-workflow) — `POST /api/v1/notifications/manage/create-workflow` - [Update an existing notification workflow](/api/notifications/update-workflow) — `POST /api/v1/notifications/manage/update-workflow` - [Get a notification workflow](/api/notifications/get-workflow) — `POST /api/v1/notifications/manage/get-workflow` - [List notification workflows](/api/notifications/list-workflows) — `POST /api/v1/notifications/manage/list-workflows` - [Delete a notification workflow](/api/notifications/delete-workflow) — `POST /api/v1/notifications/manage/delete-workflow` - [Get pending workflow changes](/api/notifications/get-pending-changes) — `POST /api/v1/notifications/manage/get-pending-changes` - [Promote a single workflow change](/api/notifications/promote-change) — `POST /api/v1/notifications/manage/promote-change` - [Promote all pending workflow changes](/api/notifications/promote-all-changes) — `POST /api/v1/notifications/manage/promote-all-changes` Document ID: `DOC-API-notifications-overview`. [Section identities and revisions](/documentation-manifest.json). - Overview: `DOC-API-notifications-overview#overview` - Authentication: `DOC-API-notifications-overview#authentication` - JSON conventions: `DOC-API-notifications-overview#json-conventions` - User: Channel Registration: `DOC-API-notifications-overview#reference-group-1` - User: In-App Inbox: `DOC-API-notifications-overview#reference-group-2` - User: Preferences: `DOC-API-notifications-overview#reference-group-3` - Management: Notification Dispatch: `DOC-API-notifications-overview#reference-group-4` - Management: Topics: `DOC-API-notifications-overview#reference-group-5` - Management: Digest: `DOC-API-notifications-overview#reference-group-6` - Management: Subscribers: `DOC-API-notifications-overview#reference-group-7` - Management: Activity & Status: `DOC-API-notifications-overview#reference-group-8` - Management: Providers: `DOC-API-notifications-overview#reference-group-9` - Management: Workflows: `DOC-API-notifications-overview#reference-group-10` - Server 1: `DOC-API-notifications-overview#reference-server-1` - X-API-Key: `DOC-API-notifications-overview#authentication-apiKeyAuth` - X-On-Behalf-Of: `DOC-API-notifications-overview#authentication-onBehalfOf` - Authorization: Bearer: `DOC-API-notifications-overview#authentication-bearerAuth` --- # Promote all pending workflow changes URL: https://docs.travila.ai/api/notifications/promote-all-changes **POST** `/api/v1/notifications/manage/promote-all-changes` Promotes staged workflow changes to the notification provider’s live configuration. Supply changeIds to select changes; omitting it or sending an empty array selects all pending changes. Inspect per-change errors alongside the successful results. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` tenant\_id derived from auth headers by gateway. **changeIds** `array[string]` Identifiers of notification configuration changes selected for promotion. Type: `string` #### notifications-promoteAllChanges-request Promote explicitly selected pending changes; replace changeIds with IDs from get-pending-changes. ```json { "changeIds": [ "change_123" ] } ``` ## Responses ### 200 — Changes promoted Content type: `application/json` Result payload for promoting selected notification configuration changes between provider environments. **promotedCount** `string(int64)` Number of configuration changes reported promoted. Pattern: ^-?\d+$ **promotedIds** `array[string]` Identifiers of configuration changes reported promoted. Type: `string` **errors** `array[notification_v1_PromotionError]` Errors reported while processing notification requests. Failure associated with promotion of one notification configuration change. Model reference: [PromotionError](/api/models/schema-okaelqap4k#response). **changeId** `string` Identifier of a pending notification configuration change. **error** `string` Error information reported for this operation or item. #### notifications-promoteAllChanges-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "promotedCount": 1, "promotedIds": [ "example_123" ], "errors": [ { "changeId": "example_123", "error": "example" } ] } ``` Document ID: `DOC-CP-notifications-api-promoteAllChanges`. [Section identities and revisions](/documentation-manifest.json). - Promote all pending workflow changes: `DOC-CP-notifications-api-promoteAllChanges#overview` - Request: `DOC-CP-notifications-api-promoteAllChanges#request` - Responses: `DOC-CP-notifications-api-promoteAllChanges#responses` --- # Promote a single workflow change URL: https://docs.travila.ai/api/notifications/promote-change **POST** `/api/v1/notifications/manage/promote-change` Promotes one staged workflow change to the notification provider’s live configuration by changeId. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` tenant\_id derived from auth headers by gateway. **changeId** `string` **required** Identifier of a pending notification configuration change. Minimum length: 1 #### notifications-promoteChange-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "changeId": "example_123" } ``` ## Responses ### 200 — Change promoted Content type: `application/json` Result payload for promoting a notification configuration change between provider environments. **success** `boolean` Whether the operation reports a successful result. **productionEntityId** `string` Identifier assigned to the promoted resource in the target environment. #### notifications-promoteChange-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "success": true, "productionEntityId": "example_123" } ``` Document ID: `DOC-CP-notifications-api-promoteChange`. [Section identities and revisions](/documentation-manifest.json). - Promote a single workflow change: `DOC-CP-notifications-api-promoteChange#overview` - Request: `DOC-CP-notifications-api-promoteChange#request` - Responses: `DOC-CP-notifications-api-promoteChange#responses` --- # Register a push notification device URL: https://docs.travila.ai/api/notifications/register-push-device **POST** `/api/v1/notifications/register-push-device` Registers an FCM device token for push notifications. Associates the token with the user's subscriber profile. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Keep push notifications attached to the signed-in user](/core-platform/notifications/push) · [Build a signed-in support chat that survives reconnects](/managed-agents/conversations/build-chat-assistant) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for registering a push-notification device. Caller user\_id is derived from authentication headers by the gateway. **fcmToken** `string` **required** Firebase Cloud Messaging token identifying the push delivery target. Minimum length: 1 **platform** `any` Device platform associated with the registered push token. Client platform associated with a push-notification device registration.
| Value | No. | Form | Meaning | |---|---|---|---| | `PLATFORM_IOS` | 0 | Canonical | An Apple iOS device registration. | | `PLATFORM_ANDROID` | 1 | Canonical | An Android device registration. | | `PLATFORM_WEB` | 2 | Canonical | A web-browser push registration. |
Exactly one of: Variant 1: Type: `string` Enum: `PLATFORM_IOS`, `PLATFORM_ANDROID`, `PLATFORM_WEB` Variant 2: Type: `integer(int32)` **deviceId** `string` Client-provided identifier of the device being registered. #### notifications-registerPushDevice-request Register the selected user’s actual device token; the displayed token is a placeholder. ```json { "fcmToken": "REPLACE_WITH_DEVICE_FCM_TOKEN" } ``` #### cookbook-managed-agents-conversations-build-chat-assistant-05-request Guide request for Variant: bring the user back when a notification arrives. Replace example resource identifiers with your own authorized values. ```json { "fcmToken": "firebase-cloud-messaging-token", "platform": "PLATFORM_IOS", "deviceId": "device-unique-id" } ``` ## Responses ### 200 — Device registered successfully Content type: `application/json` Result payload for registering an FCM token as a user’s push notification delivery target. **success** `boolean` Whether the operation reports a successful result. **subscriberId** `string` Identifier of the notification subscriber. #### notifications-registerPushDevice-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "success": true, "subscriberId": "example_123" } ``` #### cookbook-managed-agents-conversations-build-chat-assistant-json-06-response Illustrative response for Variant: bring the user back when a notification arrives. Replace example resource identifiers with your own authorized values. ```json { "subscriberId": "user_123", "success": true } ``` Document ID: `DOC-CP-notifications-api-registerPushDevice`. [Section identities and revisions](/documentation-manifest.json). - Register a push notification device: `DOC-CP-notifications-api-registerPushDevice#overview` - Request: `DOC-CP-notifications-api-registerPushDevice#request` - Responses: `DOC-CP-notifications-api-registerPushDevice#responses` --- # Remove subscribers from a topic URL: https://docs.travila.ai/api/notifications/remove-subscribers-from-topic **POST** `/api/v1/notifications/manage/remove-subscribers-from-topic` Removes the specified users from the topic's subscriber list. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Broadcast with topics](/core-platform/notifications/topics) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for removing selected users from a notification topic’s recipient membership. **topicKey** `string` **required** Caller-facing key identifying a notification topic. Minimum length: 1 **userIds** `array[string]` Identifiers of the users selected by the operation. Type: `string` #### notifications-removeSubscribersFromTopic-request Remove the selected application user from an existing topic. ```json { "topicKey": "product-updates", "userIds": [ "user-1" ] } ``` ## Responses ### 200 — Subscribers removed Content type: `application/json` Result payload for removing selected users from a notification topic’s recipient membership. **result** `any` Accepted and failed subscriber counts with per-subscriber errors from the membership change. All of: Variant 1: Result of a topic subscription operation (add/remove subscribers). Novu returns partial success — some subscribers may fail while others succeed. Model reference: [TopicSubscriptionResult](/api/models/schema-p2eb0gb1ln#response). **totalCount** `string(int64)` Total number of subscribers reported for the membership-change result. Pattern: ^-?\d+$ **successful** `string(int64)` Number of subscribers accepted by the topic subscription operation. Pattern: ^-?\d+$ **failed** `string(int64)` Number of subscribers rejected by the topic subscription operation. Pattern: ^-?\d+$ **errors** `array[notification_v1_TopicSubscriptionError]` Errors reported while processing notification requests. Subscriber-specific failure reported while changing notification-topic membership. Model reference: [TopicSubscriptionError](/api/models/schema-okmh5pnenu#response). **subscriberId** `string` Identifier of the notification subscriber. **code** `string` Provider error code for the topic subscription failure. **message** `string` Diagnostic or descriptive text returned by the operation. #### notifications-removeSubscribersFromTopic-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "result": { "totalCount": 1, "successful": 1, "failed": 1, "errors": [ { "subscriberId": "example_123", "code": "example", "message": "example" } ] } } ``` Document ID: `DOC-CP-notifications-api-removeSubscribersFromTopic`. [Section identities and revisions](/documentation-manifest.json). - Remove subscribers from a topic: `DOC-CP-notifications-api-removeSubscribersFromTopic#overview` - Request: `DOC-CP-notifications-api-removeSubscribersFromTopic#request` - Responses: `DOC-CP-notifications-api-removeSubscribersFromTopic#responses` --- # Revert an inbox message action URL: https://docs.travila.ai/api/notifications/revert-inbox-action **POST** `/api/v1/notifications/revert-inbox-action` Restores an inbox action button’s pending state. It does not undo the business operation previously associated with the button. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for undoing completion of an inbox notification’s action. **notificationId** `string` **required** Identifier of the notification whose inbox entry is being modified. Minimum length: 1 **actionType** `any` **required** Action selector used when reverting the inbox action. Which configured notification action a completion or reversal refers to.
| Value | No. | Form | Meaning | |---|---|---|---| | `ACTION_TYPE_PRIMARY` | 0 | Canonical | The notification's primary action button or action slot. | | `ACTION_TYPE_SECONDARY` | 1 | Canonical | The notification's secondary action button or action slot. |
Exactly one of: Variant 1: Type: `string` Enum: `ACTION_TYPE_PRIMARY`, `ACTION_TYPE_SECONDARY` Variant 2: Type: `integer(int32)` Enum: `0`, `1` #### notifications-revertInboxAction-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "notificationId": "example_123", "actionType": "ACTION_TYPE_PRIMARY" } ``` ## Responses ### 200 — Action reverted Content type: `application/json` Result payload for undoing completion of an inbox notification’s action. **status** `any` Status reported by the notification provider. All of: Variant 1: Mirrors Novu's common delete/mutate acknowledgement response. Model reference: [OperationStatus](/api/models/schema-ok4lj6t1ka#response). **acknowledged** `boolean` Whether the provider acknowledged the requested operation. **status** `string` Status reported by the notification provider. e.g., "done", "deleted" #### notifications-revertInboxAction-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "status": { "acknowledged": true, "status": "example" } } ``` Document ID: `DOC-CP-notifications-api-revertInboxAction`. [Section identities and revisions](/documentation-manifest.json). - Revert an inbox message action: `DOC-CP-notifications-api-revertInboxAction#overview` - Request: `DOC-CP-notifications-api-revertInboxAction#request` - Responses: `DOC-CP-notifications-api-revertInboxAction#responses` --- # Send a notification to multiple users URL: https://docs.travila.ai/api/notifications/send-bulk-notification **POST** `/api/v1/notifications/manage/send-bulk` Submits per-recipient notification events together. A batch can mix workflows. Results are per-event: one recipient failing does not fail the others. Inspect each entry's [`acknowledged`](/api/models/schema-oisl2i7j7o#response-field-acknowledged) and errors rather than the HTTP status alone. Accepted triggers are not delivery receipts, and retrying an entire partially accepted batch can duplicate work. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Send notifications](/core-platform/notifications/sending) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` events contain recipient user\_ids, not the caller. **events** `array[notification_v1_BulkTriggerEvent]` Notification trigger events submitted together. Submit at most 100 events per batch. One notification workflow trigger included in a bulk submission. Model reference: [BulkTriggerEvent](/api/models/schema-oiqb7f8bbv#request). **workflowId** `string` **required** Identifier of the notification workflow to trigger. Minimum length: 1 **userId** `string` **required** Identifier of the user associated with the operation. Minimum length: 1 **payload** `map[string, any]` Template variables and event data passed to the notification workflow. **overrides** `map[string, any]` Provider-specific overrides applied to the notification trigger. **transactionId** `string` Identifier correlating a notification trigger with later status or cancellation requests. #### notifications-sendBulkNotification-request Trigger a prepared workflow for two enrolled users; inspect every returned result. ```json { "events": [ { "workflowId": "push-notification", "userId": "user-1", "payload": { "title": "Update", "body": "New feature available" } }, { "workflowId": "push-notification", "userId": "user-2", "payload": { "title": "Update", "body": "New feature available" } } ] } ``` ## Responses ### 200 — Bulk notification results Content type: `application/json` Result payload for triggering multiple notification workflow events together. **results** `array[notification_v1_BulkTriggerResult]` Provider acknowledgements and errors for the submitted notification triggers. Provider acknowledgement and errors for one bulk notification trigger. Model reference: [BulkTriggerResult](/api/models/schema-oisl2i7j7o#response). **acknowledged** `boolean` Whether the notification provider acknowledged the trigger. **status** `string` Status reported by the notification provider. **transactionId** `string` Identifier correlating a notification trigger with later status or cancellation requests. **errors** `array[string]` Errors reported while processing notification requests. Type: `string` #### notifications-sendBulkNotification-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "results": [ { "acknowledged": true, "status": "example", "transactionId": "example_123", "errors": [ "example" ] } ] } ``` Document ID: `DOC-CP-notifications-api-sendBulkNotification`. [Section identities and revisions](/documentation-manifest.json). - Send a notification to multiple users: `DOC-CP-notifications-api-sendBulkNotification#overview` - Request: `DOC-CP-notifications-api-sendBulkNotification#request` - Responses: `DOC-CP-notifications-api-sendBulkNotification#responses` --- # Send a notification to a user URL: https://docs.travila.ai/api/notifications/send-notification **POST** `/api/v1/notifications/manage/send` Sends a notification to a single user by triggering a notification workflow. The configured workflow determines its delivery channels. A transactionId is a provider correlation/deduplication input, not an unlimited exactly-once guarantee or an authorization grant; reconcile uncertain sends before retrying. ### Workflow definitions and payload variables [`workflowId`](/api/notifications/send-notification#request-field-workflowid) selects a prepared notification workflow containing its channels and message templates. Discover workflows through [list workflows](/api/notifications/list-workflows). The send operation renders that workflow with the supplied [`payload`](/api/notifications/send-notification#request-field-payload) variables; it does not accept arbitrary message text outside the template contract. Save the returned [`transactionId`](/api/notifications/send-notification#response-field-transactionid) and any one you supplied. Use it for [cancelling](/core-platform/notifications/sending#cancel-a-pending-notification) and [checking delivery](/core-platform/notifications/administration#delivery-status). Inspect the trigger acknowledgment and errors before treating the send as accepted. Acceptance does not confirm delivery or a read receipt: workflow configuration, recipient preferences and provider delivery can produce later failures or suppression. Check delivery status for the subsequent channel attempts. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Send notifications](/core-platform/notifications/sending) · [Welcome a new user with an in-app message](/core-platform/notifications/administration) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for dispatching a notification. user\_id identifies the recipient, not the caller. **workflowId** `string` **required** Identifier of the notification workflow to trigger. Minimum length: 1 **userId** `string` **required** Identifier of the notification's intended recipient. Minimum length: 1 **payload** `map[string, any]` Template variables and event data passed to the notification workflow. **overrides** `map[string, any]` Provider-specific overrides passed through to delivery, such as an FCM data payload. **transactionId** `string` Identifier correlating a notification trigger with later status or cancellation requests. #### notifications-sendNotification-request Trigger the prepared welcome workflow for an enrolled user; replace the workflow and user identifiers. ```json { "workflowId": "welcome-notification", "userId": "user-1", "payload": {} } ``` ## Responses ### 200 — Notification trigger accepted; delivery is separate Content type: `application/json` Result payload for triggering a notification workflow for a selected user. **acknowledged** `boolean` Whether the notification provider acknowledged the trigger. **status** `string` Descriptive status reported by the notification provider, not a fixed set of states. "processed" means the workflow was accepted for processing; it does not confirm delivery. **transactionId** `string` Identifier correlating a notification trigger with later status or cancellation requests. **errors** `array[string]` Errors reported while processing notification requests. Type: `string` #### notifications-sendNotification-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "acknowledged": true, "status": "example", "transactionId": "example_123", "errors": [ "example" ] } ``` Document ID: `DOC-CP-notifications-api-sendNotification`. [Section identities and revisions](/documentation-manifest.json). - Send a notification to a user: `DOC-CP-notifications-api-sendNotification#overview` - Request: `DOC-CP-notifications-api-sendNotification#request` - Responses: `DOC-CP-notifications-api-sendNotification#responses` --- # Send a notification to all topic subscribers URL: https://docs.travila.ai/api/notifications/send-to-topic **POST** `/api/v1/notifications/manage/send-to-topic` Broadcasts a notification to all subscribers of the specified topic. Optionally excludes a single user (e.g., the action originator). Acceptance is not a delivery or read receipt. Workflow configuration, recipient preferences and provider delivery can produce later failures or suppression. A transactionId is a provider correlation/deduplication input, not an unlimited exactly-once guarantee or an authorization grant; reconcile uncertain sends before retrying. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Broadcast with topics](/core-platform/notifications/topics) · [Push registration and topic delivery](/api/notifications/delivery) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` exclude\_user\_id is an exclusion target, not the caller. **workflowId** `string` **required** Identifier of the notification workflow to trigger. Minimum length: 1 **topicKey** `string` **required** Caller-facing key identifying a notification topic. Minimum length: 1 **payload** `map[string, any]` Template variables and event data passed to the notification workflow. **overrides** `map[string, any]` Provider-specific overrides applied to the notification trigger. **transactionId** `string` Identifier correlating a notification trigger with later status or cancellation requests. **excludeUserId** `string` User identifier to omit from the topic notification’s recipients. #### notifications-sendToTopic-request Trigger a prepared workflow for subscribers to an existing topic. ```json { "workflowId": "push-notification", "topicKey": "product-updates", "payload": { "title": "Update", "body": "New feature available" } } ``` ## Responses ### 200 — Topic notification trigger accepted; delivery is separate Content type: `application/json` Result payload for triggering a notification workflow for the subscribers of a topic. **acknowledged** `boolean` Whether the notification provider acknowledged the trigger. **status** `string` Status reported by the notification provider. **transactionId** `string` Identifier correlating a notification trigger with later status or cancellation requests. **errors** `array[string]` Errors reported while processing notification requests. Type: `string` #### notifications-sendToTopic-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "acknowledged": true, "status": "example", "transactionId": "example_123", "errors": [ "example" ] } ``` Document ID: `DOC-CP-notifications-api-sendToTopic`. [Section identities and revisions](/documentation-manifest.json). - Send a notification to all topic subscribers: `DOC-CP-notifications-api-sendToTopic#overview` - Request: `DOC-CP-notifications-api-sendToTopic#request` - Responses: `DOC-CP-notifications-api-sendToTopic#responses` --- # Send a notification with digest aggregation URL: https://docs.travila.ai/api/notifications/send-with-digest **POST** `/api/v1/notifications/manage/send-with-digest` Triggers a notification workflow that must already have a digest step configured. The workflow’s configured digest window determines whether and how events are batched before delivery; this operation does not create that digest configuration. Acceptance is not a delivery or read receipt. Workflow configuration, recipient preferences and provider delivery can produce later failures or suppression. A transactionId is a provider correlation/deduplication input, not an unlimited exactly-once guarantee or an authorization grant; reconcile uncertain sends before retrying. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Send notifications](/core-platform/notifications/sending) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for dispatching a notification with digest handling. user\_id identifies the recipient, not the caller. **workflowId** `string` **required** Identifier of the notification workflow to trigger. Minimum length: 1 **userId** `string` **required** Identifier of the notification’s intended recipient. Minimum length: 1 **payload** `map[string, any]` Template variables and event data passed to the notification workflow. **overrides** `map[string, any]` Provider-specific overrides applied to the notification trigger. **transactionId** `string` Identifier correlating a notification trigger with later status or cancellation requests. #### notifications-sendWithDigest-request Submit one event to a workflow that already has a digest step configured. ```json { "workflowId": "activity-digest", "userId": "user-1", "payload": { "title": "Account activity", "body": "A new report is available." } } ``` ## Responses ### 200 — Digest notification accepted Content type: `application/json` Result payload for submitting a notification event for digest processing. **acknowledged** `boolean` Whether the notification provider acknowledged the trigger. **status** `string` Status reported by the notification provider. **transactionId** `string` Identifier correlating a notification trigger with later status or cancellation requests. **errors** `array[string]` Errors reported while processing notification requests. Type: `string` #### notifications-sendWithDigest-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "acknowledged": true, "status": "example", "transactionId": "example_123", "errors": [ "example" ] } ``` Document ID: `DOC-CP-notifications-api-sendWithDigest`. [Section identities and revisions](/documentation-manifest.json). - Send a notification with digest aggregation: `DOC-CP-notifications-api-sendWithDigest#overview` - Request: `DOC-CP-notifications-api-sendWithDigest#request` - Responses: `DOC-CP-notifications-api-sendWithDigest#responses` --- # Unarchive an inbox message URL: https://docs.travila.ai/api/notifications/unarchive-inbox-message **POST** `/api/v1/notifications/unarchive-inbox-message` Restores a previously archived inbox message back into the default feed. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for restoring an archived notification to the subscriber’s inbox feed. **notificationId** `string` **required** Identifier of the notification whose inbox entry is being modified. Minimum length: 1 #### notifications-unarchiveInboxMessage-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "notificationId": "example_123" } ``` ## Responses ### 200 — Message unarchived Content type: `application/json` Result payload for restoring an archived notification to the subscriber’s inbox feed. **status** `any` Status reported by the notification provider. All of: Variant 1: Mirrors Novu's common delete/mutate acknowledgement response. Model reference: [OperationStatus](/api/models/schema-ok4lj6t1ka#response). **acknowledged** `boolean` Whether the provider acknowledged the requested operation. **status** `string` Status reported by the notification provider. e.g., "done", "deleted" #### notifications-unarchiveInboxMessage-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "status": { "acknowledged": true, "status": "example" } } ``` Document ID: `DOC-CP-notifications-api-unarchiveInboxMessage`. [Section identities and revisions](/documentation-manifest.json). - Unarchive an inbox message: `DOC-CP-notifications-api-unarchiveInboxMessage#overview` - Request: `DOC-CP-notifications-api-unarchiveInboxMessage#request` - Responses: `DOC-CP-notifications-api-unarchiveInboxMessage#responses` --- # Unregister a push notification device URL: https://docs.travila.ai/api/notifications/unregister-push-device **POST** `/api/v1/notifications/unregister-push-device` Removes an FCM device token from the user's subscriber profile. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Keep push notifications attached to the signed-in user](/core-platform/notifications/push) · [Build a signed-in support chat that survives reconnects](/managed-agents/conversations/build-chat-assistant) · [Push registration and topic delivery](/api/notifications/delivery) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Caller user\_id derived from auth headers by gateway. **fcmToken** `string` **required** Firebase Cloud Messaging token identifying the push delivery target. Minimum length: 1 #### notifications-unregisterPushDevice-request Remove a device token previously registered for the selected user. ```json { "fcmToken": "REPLACE_WITH_DEVICE_FCM_TOKEN" } ``` #### cookbook-managed-agents-conversations-build-chat-assistant-06-request Guide request for Variant: bring the user back when a notification arrives. Replace example resource identifiers with your own authorized values. ```json { "fcmToken": "firebase-cloud-messaging-token" } ``` ## Responses ### 200 — Device unregistered successfully Content type: `application/json` Result payload for removing an FCM token from the user’s registered push delivery targets. **subscriberId** `string` Identifier of the notification subscriber. **remainingCredentialCount** `string(int64)` Number of push credentials remaining after unregistering the device. Pattern: ^-?\d+$ #### notifications-unregisterPushDevice-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "subscriberId": "example_123", "remainingCredentialCount": 1 } ``` Document ID: `DOC-CP-notifications-api-unregisterPushDevice`. [Section identities and revisions](/documentation-manifest.json). - Unregister a push notification device: `DOC-CP-notifications-api-unregisterPushDevice#overview` - Request: `DOC-CP-notifications-api-unregisterPushDevice#request` - Responses: `DOC-CP-notifications-api-unregisterPushDevice#responses` --- # Update global notification preferences URL: https://docs.travila.ai/api/notifications/update-global-preference **POST** `/api/v1/notifications/update-global-preference` Updates the subscriber's global (all-workflow) channel toggles. Omitted channels are left unchanged. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Manage notification preferences](/core-platform/notifications/preferences) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for changing the subscriber’s channel preferences across notification workflows. **channels** `any` Channel switches to update for the subscriber. All of: Variant 1: Per-channel notification toggles. All fields are optional so callers can patch only the channels they want to change; omitted fields remain unchanged. Model reference: [ChannelToggles](/api/models/schema-oj4cvo85fs#request). **inApp** `boolean` Whether in-app notification delivery is enabled. **push** `boolean` Whether push notification delivery is enabled. **email** `boolean` Whether email notification delivery is enabled. **sms** `boolean` Whether SMS notification delivery is enabled. **chat** `boolean` Whether chat notification delivery is enabled. #### notifications-updateGlobalPreference-request Disable push notifications while leaving omitted channels unchanged. ```json { "channels": { "push": false } } ``` ## Responses ### 200 — Global preference updated Content type: `application/json` An empty JSON object. #### notifications-updateGlobalPreference-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json {} ``` Document ID: `DOC-CP-notifications-api-updateGlobalPreference`. [Section identities and revisions](/documentation-manifest.json). - Update global notification preferences: `DOC-CP-notifications-api-updateGlobalPreference#overview` - Request: `DOC-CP-notifications-api-updateGlobalPreference#request` - Responses: `DOC-CP-notifications-api-updateGlobalPreference#responses` --- # Update subscriber profile data URL: https://docs.travila.ai/api/notifications/update-subscriber-data **POST** `/api/v1/notifications/manage/update-subscriber-data` Updates the subscriber's profile data including name, email, phone, locale, and custom metadata. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for updating notification subscriber data. Caller user\_id is derived from authentication headers by the gateway. **data** `any` **required** Contact, locale, and custom subscriber attributes to update. All of: Variant 1: Contact, locale, and custom attributes used by notification delivery. Model reference: [SubscriberData](/api/models/schema-1kgdnn5p53#request). **firstName** `string` Subscriber’s given name. **lastName** `string` Subscriber’s family name. **email** `string` Email address used for subscriber contact and delivery. **phone** `string` Phone number used for subscriber contact and delivery. **avatarUrl** `string` URL of the subscriber’s avatar image. **locale** `string` Subscriber locale used when rendering notifications. e.g., "en-US" **timezone** `string` Subscriber time zone used for notification presentation. e.g., "America/Los\_Angeles" **customData** `map[string, string]` Additional template variables. #### notifications-updateSubscriberData-request Update attributes for the user selected by authentication. ```json { "data": { "firstName": "Alex", "locale": "en-US", "timezone": "America/New_York" } } ``` ## Responses ### 200 — Subscriber data updated Content type: `application/json` Result payload for changing contact, locale, or custom attributes used for notification delivery. **data** `any` Contact, locale, and custom attributes returned for the subscriber. All of: Variant 1: Contact, locale, and custom attributes used by notification delivery. Model reference: [SubscriberData](/api/models/schema-1kgdnn5p53#response). **firstName** `string` Subscriber’s given name. **lastName** `string` Subscriber’s family name. **email** `string` Email address used for subscriber contact and delivery. **phone** `string` Phone number used for subscriber contact and delivery. **avatarUrl** `string` URL of the subscriber’s avatar image. **locale** `string` Subscriber locale used when rendering notifications. e.g., "en-US" **timezone** `string` Subscriber time zone used for notification presentation. e.g., "America/Los\_Angeles" **customData** `map[string, string]` Additional template variables. **updatedAt** `string(date-time)` Time when this record was last updated. #### notifications-updateSubscriberData-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "data": { "firstName": "example", "lastName": "example", "email": "user@example.com", "phone": "example", "avatarUrl": "https://example.com/resource", "locale": "en-US", "timezone": "example", "customData": {} }, "updatedAt": "2026-09-16T12:00:00Z" } ``` Document ID: `DOC-CP-notifications-api-updateSubscriberData`. [Section identities and revisions](/documentation-manifest.json). - Update subscriber profile data: `DOC-CP-notifications-api-updateSubscriberData#overview` - Request: `DOC-CP-notifications-api-updateSubscriberData#request` - Responses: `DOC-CP-notifications-api-updateSubscriberData#responses` --- # Update per-workflow notification preferences URL: https://docs.travila.ai/api/notifications/update-workflow-preference **POST** `/api/v1/notifications/update-workflow-preference` Updates the subscriber's channel toggles for a single workflow. Omitted channels are left unchanged. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Manage notification preferences](/core-platform/notifications/preferences) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for changing the subscriber’s channel preferences for one notification workflow. **workflowId** `string` **required** Identifier of the notification workflow whose subscriber preferences are being changed. Minimum length: 1 **channels** `any` Channel switches to update for the subscriber. All of: Variant 1: Per-channel notification toggles. All fields are optional so callers can patch only the channels they want to change; omitted fields remain unchanged. Model reference: [ChannelToggles](/api/models/schema-oj4cvo85fs#request). **inApp** `boolean` Whether in-app notification delivery is enabled. **push** `boolean` Whether push notification delivery is enabled. **email** `boolean` Whether email notification delivery is enabled. **sms** `boolean` Whether SMS notification delivery is enabled. **chat** `boolean` Whether chat notification delivery is enabled. #### notifications-updateWorkflowPreference-request Disable push for an existing workflow while leaving other channels unchanged. ```json { "workflowId": "promotional", "channels": { "push": false } } ``` ## Responses ### 200 — Workflow preference updated Content type: `application/json` An empty JSON object. #### notifications-updateWorkflowPreference-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json {} ``` Document ID: `DOC-CP-notifications-api-updateWorkflowPreference`. [Section identities and revisions](/documentation-manifest.json). - Update per-workflow notification preferences: `DOC-CP-notifications-api-updateWorkflowPreference#overview` - Request: `DOC-CP-notifications-api-updateWorkflowPreference#request` - Responses: `DOC-CP-notifications-api-updateWorkflowPreference#responses` --- # Update an existing notification workflow URL: https://docs.travila.ai/api/notifications/update-workflow **POST** `/api/v1/notifications/manage/update-workflow` Updates the identified workflow using the supplied definition. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration) ## Authentication One of: - API Key via `X-API-Key` header parameter - HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` tenant\_id and environment derived from auth headers by gateway. **workflowId** `string` Identifier of the notification workflow to update. **workflow** `map[string, any]` Notification workflow definition supplied to or returned by the provider. #### notifications-updateWorkflow-request Replace an existing workflow with the complete definition; preserve every delivery step you intend to keep. ```json { "workflowId": "welcome-notification", "workflow": { "name": "Welcome Notification", "description": "Sent when a user completes onboarding", "__source": "editor", "steps": [ { "name": "In-App Step", "type": "in_app", "controlValues": { "body": "Welcome to your health coaching journey!" } } ] } } ``` ## Responses ### 200 — Workflow updated Content type: `application/json` Result payload for changing a registered notification workflow definition. **workflow** `map[string, any]` Notification workflow definition supplied to or returned by the provider. #### notifications-updateWorkflow-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "workflow": { "example": "value" } } ``` Document ID: `DOC-CP-notifications-api-updateWorkflow`. [Section identities and revisions](/documentation-manifest.json). - Update an existing notification workflow: `DOC-CP-notifications-api-updateWorkflow#overview` - Request: `DOC-CP-notifications-api-updateWorkflow#request` - Responses: `DOC-CP-notifications-api-updateWorkflow#responses` --- # Create a scheduled job URL: https://docs.travila.ai/api/scheduled-jobs/create-job **POST** `/api/v1/scheduler/create-job` Creates a new scheduled job. The job becomes active immediately and fires on its next matching time. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Run work on a schedule](/core-platform/scheduling) · [Manage jobs](/core-platform/scheduling/managing) · [Automate recurring agent work](/core-platform/scheduling/build-scheduled-agents) · [Create a scheduled job](/core-platform/scheduling/creating) · [Monitor executions and retries](/core-platform/scheduling/execution) · [Schedule retries and auto-pause](/api/scheduled-jobs/schedules) ## Authentication One of: - API Key via `X-API-Key` header parameter - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for creating a scheduled job and its trigger settings. ### Input constraints ### interval\_seconds The interval\_seconds value must be zero, meaning unset for this create request, or at least 60 seconds. ### auto\_pause\_threshold The auto\_pause\_threshold value must be zero, or between 3 and 100 inclusive. **name** `string` **required** Human-readable name assigned to the scheduled job. Minimum length: 1 Maximum length: 256 **description** `string` Human-readable explanation of the scheduled job. **scheduleType** `any` Selects which schedule expression to supply. For SCHEDULE\_TYPE\_CRON, set cron\_expression and optionally timezone; for SCHEDULE\_TYPE\_ONCE, set scheduled\_at; for SCHEDULE\_TYPE\_RECURRING\_INTERVAL, set interval\_seconds. Supply exactly one expression matching the chosen type. Expression format that determines when a scheduled job fires.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCHEDULE_TYPE_CRON` | 0 | Canonical | Fire according to the configured cron expression and timezone. For example, `0 9 * * 1-5` selects 09:00 on weekdays in that timezone. | | `SCHEDULE_TYPE_ONCE` | 1 | Canonical | Fire once at the configured scheduled timestamp. | | `SCHEDULE_TYPE_RECURRING_INTERVAL` | 2 | Canonical | Fire repeatedly at the configured interval in seconds. |
Exactly one of: Variant 1: Type: `string` Enum: `SCHEDULE_TYPE_CRON`, `SCHEDULE_TYPE_ONCE`, `SCHEDULE_TYPE_RECURRING_INTERVAL` Variant 2: Type: `integer(int32)` **cronExpression** `string` Cron expression evaluated in timezone. Accepts 5 or 6 fields and supported shorthand expressions. Examples: `0 9 * * 1-5` for weekdays at 09:00, `*/15 * * * *` for every 15 minutes, and `0 0 1 * *` for the first day of each month at midnight. `@daily` means `0 0 * * *`; `@hourly` means `0 * * * *`. Maximum length: 128 Pattern: ^$|^@\w+(\s.+)?$|^\S+(\s+\S+){4,5}$ **timezone** `string` IANA timezone for cron evaluation, such as "America/New\_York". Defaults to "UTC". **scheduledAt** `string(date-time)` Instant at which a one-time scheduled job should run. **intervalSeconds** `string(int64)` Interval between scheduled triggers, in seconds. Pattern: ^-?\d+$ **target** `any` **required** Destination and invocation settings for the scheduled job. All of: Variant 1: ScheduleTarget describes the HTTP endpoint that receives each job invocation. Model reference: [ScheduleTarget](/api/models/schema-1lbkptb5rj#request). **url** `string(uri)` **required** Destination URL. Must be a valid absolute URI. Minimum length: 1 **method** `string` HTTP method to use. Defaults to "POST". **kind** `string` **required** Logical kind used for routing and observability (e.g., "notification", "llm\_conversation", "metering"). Required. Minimum length: 1 **payload** `map[string, any]` Arbitrary JSON payload forwarded verbatim to the target. **retryPolicy** `any` Attempt limits and backoff settings for the scheduled target. All of: Variant 1: RetryPolicy controls how failed executions are retried. Model reference: [RetryPolicy](/api/models/schema-1l9ki2op1i#request). **maxAttempts** `string(int64)` Maximum delivery attempts (including the initial attempt). Default 10. Pattern: ^-?\d+$ **initialBackoffMs** `string(int64)` Initial backoff before the first retry, in milliseconds. Default 5000. Pattern: ^-?\d+$ **maxBackoffMs** `string(int64)` Maximum backoff cap, in milliseconds. Default 1800000 (30 min). Pattern: ^-?\d+$ **metadata** `map[string, any]` Application-defined JSON metadata attached to the scheduled job. **autoPauseThreshold** `string(int64)` Consecutive failure threshold used to pause the scheduled job. Omission or zero selects the default of 10. A nonzero override must be from 3 through 100. This create request does not expose a value that disables auto-pause. Pattern: ^-?\d+$ **ownerSubject** `string` Owner subject. When omitted, defaults to the caller derived from headers. **externalId** `string` Optional client-supplied identifier, unique within (tenant, project) among live schedules. Immutable once set. Must not start with "sched\_". Maximum length: 255 #### scheduled-jobs-createJob-request Schedule a weekday digest while acting on behalf of its owner; replace the target URL with your endpoint. ```json { "name": "Daily digest", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * 1-5", "timezone": "America/New_York", "target": { "url": "https://your-api.example.com/jobs/daily-digest", "kind": "digest", "payload": { "report": "daily" } } } ``` #### cookbook-core-platform-scheduling-build-scheduled-agents-02-request Guide request for Step 4: Create the schedule. Replace example resource identifiers with your own authorized values. ```json { "name": "Daily agent briefing", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * 1-5", "timezone": "America/New_York", "target": { "url": "https://api.example.com/hooks/scheduled-agent", "kind": "agent-briefing", "payload": { "task": "daily-briefing" } } } ``` #### cookbook-core-platform-scheduling-creating-02-request Guide request for Variant: remind the user once at a chosen time. Replace example resource identifiers with your own authorized values. ```json { "name": "Send welcome email", "scheduleType": "SCHEDULE_TYPE_ONCE", "scheduledAt": "2026-10-10T14:00:00Z", "target": { "url": "https://your-api.example.com/jobs/welcome", "kind": "notification", "payload": { "user_id": "usr_abc123" } } } ``` #### cookbook-core-platform-scheduling-creating-03-request Guide request for Variant: refresh application data every few minutes. Replace example resource identifiers with your own authorized values. ```json { "name": "Sync cache", "scheduleType": "SCHEDULE_TYPE_RECURRING_INTERVAL", "intervalSeconds": 300, "target": { "url": "https://your-api.example.com/jobs/cache-sync", "kind": "maintenance" } } ``` #### cookbook-core-platform-scheduling-execution-02-request Guide request for Recover a temporary receiver failure. Replace example resource identifiers with your own authorized values. ```json { "name": "Critical alert", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "*/5 * * * *", "target": { "url": "https://your-api.example.com/jobs/alert", "kind": "alert" }, "retryPolicy": { "maxAttempts": 3, "initialBackoffMs": 1000, "maxBackoffMs": 10000 } } ``` #### cookbook-core-platform-scheduling-managing-08-request Guide request for Variant: use your application’s reminder identifier. Replace example resource identifiers with your own authorized values. ```json { "name": "Daily digest", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * 1-5", "externalId": "user-42-daily-digest", "target": { "url": "https://your-api.example.com/jobs/daily-digest", "kind": "digest" } } ``` ## Responses ### 200 — Scheduled job created Content type: `application/json` Schedule is the canonical representation of a scheduled job. Creating any schedule type returns the `Schedule` resource directly, with the same shape used by get, pause and resume operations. [`triggerCount`](/api/models/schema-1ld0l8rmvg#response-field-triggercount): Cumulative firings. [`failureCount`](/api/models/schema-1ld0l8rmvg#response-field-failurecount): Cumulative failed first attempts; a later successful retry does not erase the earlier failure. [`consecutiveFailureCount`](/api/models/schema-1ld0l8rmvg#response-field-consecutivefailurecount): Current sequence of failed firings; a successful attempt resets it. This counter drives auto-pause. Zero-valued counters can be omitted. Nonzero 64-bit counters are decimal JSON strings; preserve their integer precision. Model reference: [Schedule](/api/models/schema-1ld0l8rmvg#response). **scheduleId** `string` Server-assigned identifier of the scheduled job, prefixed with "sched\_". **tenantId** `string` Identifier of the tenant that owns or scopes this record. **projectId** `string` Identifier of the project within the tenant that scopes this record. **ownerSubject** `string` Subject identifier of the owning user or service account. **name** `string` Human-readable name assigned to the scheduled job. **description** `string` Human-readable explanation of the scheduled job. **scheduleType** `any` Schedule type and expression. Expression format that determines when a scheduled job fires.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCHEDULE_TYPE_CRON` | 0 | Canonical | Fire according to the configured cron expression and timezone. For example, `0 9 * * 1-5` selects 09:00 on weekdays in that timezone. | | `SCHEDULE_TYPE_ONCE` | 1 | Canonical | Fire once at the configured scheduled timestamp. | | `SCHEDULE_TYPE_RECURRING_INTERVAL` | 2 | Canonical | Fire repeatedly at the configured interval in seconds. |
Exactly one of: Variant 1: Type: `string` Enum: `SCHEDULE_TYPE_CRON`, `SCHEDULE_TYPE_ONCE`, `SCHEDULE_TYPE_RECURRING_INTERVAL` Variant 2: Type: `integer(int32)` **cronExpression** `string` Cron expression. Populated when schedule\_type is SCHEDULE\_TYPE\_CRON. **timezone** `string` IANA timezone for cron evaluation. Default "UTC". **scheduledAt** `string(date-time)` Exact fire time. Populated when schedule\_type is SCHEDULE\_TYPE\_ONCE. **intervalSeconds** `string(int64)` Interval between firings in seconds. Populated when schedule\_type is SCHEDULE\_TYPE\_RECURRING\_INTERVAL. Pattern: ^-?\d+$ **target** `any` Destination and invocation settings for the scheduled job. All of: Variant 1: ScheduleTarget describes the HTTP endpoint that receives each job invocation. Model reference: [ScheduleTarget](/api/models/schema-1lbkptb5rj#response). **url** `string` Destination URL. Must be a valid absolute URI. **method** `string` HTTP method to use. Defaults to "POST". **kind** `string` Logical kind used for routing and observability (e.g., "notification", "llm\_conversation", "metering"). Required. **payload** `map[string, any]` Arbitrary JSON payload forwarded verbatim to the target. **state** `any` Lifecycle status controlling whether the scheduled job can trigger. Lifecycle condition that determines whether a scheduled job may trigger: active, paused, or deleted. This is separate from the outcome of an individual scheduled-job execution.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCHEDULE_STATUS_ACTIVE` | 0 | Canonical | The schedule is active and can trigger at its next matching time. | | `SCHEDULE_STATUS_PAUSED` | 1 | Canonical | The schedule is paused and does not trigger until resumed. | | `SCHEDULE_STATUS_DELETED` | 2 | Canonical | The schedule has been deleted; this is a schedule condition, not an execution outcome. |
Exactly one of: Variant 1: Type: `string` Enum: `SCHEDULE_STATUS_ACTIVE`, `SCHEDULE_STATUS_PAUSED`, `SCHEDULE_STATUS_DELETED` Variant 2: Type: `integer(int32)` **retryPolicy** `any` Attempt limits and backoff settings for the scheduled target. All of: Variant 1: RetryPolicy controls how failed executions are retried. Model reference: [RetryPolicy](/api/models/schema-1l9ki2op1i#response). **maxAttempts** `string(int64)` Maximum delivery attempts (including the initial attempt). Default 10. Pattern: ^-?\d+$ **initialBackoffMs** `string(int64)` Initial backoff before the first retry, in milliseconds. Default 5000. Pattern: ^-?\d+$ **maxBackoffMs** `string(int64)` Maximum backoff cap, in milliseconds. Default 1800000 (30 min). Pattern: ^-?\d+$ **metadata** `map[string, any]` Application-defined JSON metadata attached to the scheduled job. **autoPauseThreshold** `string(int64)` If consecutive\_failure\_count reaches this threshold the job is auto-paused (state PAUSED, paused\_by\_subject "system\:auto-pause"). It is compared against consecutive\_failure\_count, NOT failure\_count. failure\_count is cumulative for the schedule's whole life, so a healthy schedule that collects scattered failures over months would eventually exceed any threshold and pause itself forever. A stored threshold of 0 disables auto-pause; otherwise the threshold is from 3 through 100. The public create request uses 0 or omission to select the default of 10, and the public update request uses 0 or omission to leave the current threshold unchanged. These public requests do not provide a disable control. Pattern: ^-?\d+$ **externalId** `string` Client-supplied external id. Echoed back when set; empty otherwise. Optional, immutable, unique within (tenant\_id, project\_id) among live schedules. Never starts with the reserved system-id prefix "sched\_". **createdAt** `string(date-time)` Time at which the scheduled job was created. **createdBySubject** `string` Subject identifier recorded when the schedule was created. **updatedAt** `string(date-time)` Time this record was most recently updated. **updatedBySubject** `string` Subject identifier recorded when the schedule was last updated. **pausedAt** `string(date-time)` Time at which the schedule was paused. **pausedBySubject** `string` Subject identifier recorded for the schedule pause. **pausedReason** `string` Explanation recorded for the schedule pause. **resumedAt** `string(date-time)` Time at which the schedule was most recently resumed. **resumedBySubject** `string` Subject identifier recorded for the schedule resume. **deletedAt** `string(date-time)` Time at which the schedule was deleted. **deletedBySubject** `string` Subject identifier recorded for the schedule deletion. **lastTriggeredAt** `string(date-time)` Time when the schedule was last triggered. Trigger and failure counters advance at most once per scheduled firing on its first attempt; retrying that firing does not inflate them. **nextTriggerAt** `string(date-time)` Time calculated for the next scheduled trigger. **triggerCount** `string(int64)` Scheduled times that ran, cumulative for the schedule's whole life. Pattern: ^-?\d+$ **failureCount** `string(int64)` Scheduled times whose first attempt failed, cumulative for the schedule's whole life. A firing that fails on attempt 1 and succeeds on retry still counts here — a failure was observed. This counter does NOT drive auto-pause. See consecutive\_failure\_count. Pattern: ^-?\d+$ **consecutiveFailureCount** `string(int64)` Current run of consecutive failed firings. This is the counter auto\_pause\_threshold is compared against. Incremented when a firing's first attempt fails; reset to 0 as soon as any attempt of any firing succeeds. So a firing that fails on attempt 1 and succeeds on retry has net zero effect here while still advancing failure\_count — the target recovered, so the run is over. A non-success terminal outcome counts as a failure, including a firing cancelled on a terminal 4xx. Pattern: ^-?\d+$ #### scheduled-jobs-createJob-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "scheduleId": "sched_a1b2c3d4e5f60718", "tenantId": "example_123", "projectId": "example_123", "ownerSubject": "example", "name": "example", "description": "example", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * *", "timezone": "example", "scheduledAt": "2026-09-16T12:00:00Z", "intervalSeconds": 1, "target": { "url": "https://example.com/callback", "method": "example", "kind": "example", "payload": { "example": "value" } }, "state": "SCHEDULE_STATUS_ACTIVE", "retryPolicy": { "maxAttempts": 1, "initialBackoffMs": 1, "maxBackoffMs": 1 }, "metadata": { "example": "value" }, "autoPauseThreshold": 1, "externalId": "example_123", "createdAt": "2026-09-16T12:00:00Z", "createdBySubject": "example", "updatedAt": "2026-09-16T12:00:00Z", "updatedBySubject": "example", "pausedAt": "2026-09-16T12:00:00Z", "pausedBySubject": "example", "pausedReason": "example", "resumedAt": "2026-09-16T12:00:00Z", "resumedBySubject": "example", "deletedAt": "2026-09-16T12:00:00Z", "deletedBySubject": "example", "lastTriggeredAt": "2026-09-16T12:00:00Z", "nextTriggerAt": "2026-09-16T12:00:00Z", "triggerCount": "1", "failureCount": "1", "consecutiveFailureCount": "1" } ``` #### cookbook-core-platform-scheduling-build-scheduled-agents-json-03-response Illustrative response for Step 4: Create the schedule. Replace example resource identifiers with your own authorized values. ```json { "scheduleId": "sched_a1b2c3d4e5f60718", "name": "Daily agent briefing", "state": "SCHEDULE_STATUS_ACTIVE", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * 1-5", "timezone": "America/New_York", "nextTriggerAt": "2026-06-04T13:00:00Z", "createdAt": "2026-06-03T14:00:00Z" } ``` #### cookbook-core-platform-scheduling-creating-json-01-response Illustrative response for Confirm and save the next scheduled time. Replace example resource identifiers with your own authorized values. ```json { "scheduleId": "sched_a1b2c3d4e5f60718", "name": "Daily digest", "state": "SCHEDULE_STATUS_ACTIVE", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * 1-5", "timezone": "America/New_York", "nextTriggerAt": "2026-06-04T13:00:00Z", "createdAt": "2026-06-03T14:00:00Z" } ``` Document ID: `DOC-CP-scheduling-api-createJob`. [Section identities and revisions](/documentation-manifest.json). - Create a scheduled job: `DOC-CP-scheduling-api-createJob#overview` - Request: `DOC-CP-scheduling-api-createJob#request` - Responses: `DOC-CP-scheduling-api-createJob#responses` --- # Delete a scheduled job URL: https://docs.travila.ai/api/scheduled-jobs/delete-job **POST** `/api/v1/scheduler/delete-job` Soft-deletes the schedule and stops future scheduling. The record is retained for inspection. Already dispatched work and its external effects are not undone by deleting the schedule. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Manage jobs](/core-platform/scheduling/managing) ## Authentication One of: - API Key via `X-API-Key` header parameter - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for deleting a scheduled job and its trigger settings. ### Input constraints ### Record relationship Exactly one of schedule\_id or external\_id must be nonempty. Supplying neither or supplying both does not satisfy this condition. **scheduleId** `string` Identifier of the scheduled job. **externalId** `string` Caller-assigned correlation identifier for the scheduled job. #### scheduled-jobs-deleteJob-request Replace scheduleId with the ID returned when the job was created. ```json { "scheduleId": "sched_a1b2c3d4e5f60718" } ``` #### cookbook-core-platform-scheduling-managing-05-request Guide request for 4. Remove this reminder. Replace example resource identifiers with your own authorized values. ```json { "scheduleId": "sched_a1b2c3d4e5f60718" } ``` ## Responses ### 200 — Scheduled job deleted Content type: `application/json` Result of deleting a scheduled job and its trigger settings. **scheduleId** `string` Identifier of the scheduled job. #### scheduled-jobs-deleteJob-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "scheduleId": "sched_a1b2c3d4e5f60718" } ``` Document ID: `DOC-CP-scheduling-api-deleteJob`. [Section identities and revisions](/documentation-manifest.json). - Delete a scheduled job: `DOC-CP-scheduling-api-deleteJob#overview` - Request: `DOC-CP-scheduling-api-deleteJob#request` - Responses: `DOC-CP-scheduling-api-deleteJob#responses` --- # Delete all scheduled jobs for the calling owner URL: https://docs.travila.ai/api/scheduled-jobs/delete-jobs-for-owner **POST** `/api/v1/scheduler/delete-jobs-for-owner` Soft-deletes schedules owned by the authenticated beneficiary within the verified tenant/project context. This is an explicit schedule-cleanup operation for offboarding or user-requested deletion. Do not call it on sign-out: schedules belong to the user/project and are not scoped to the current device session. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Manage jobs](/core-platform/scheduling/managing) ## Authentication One of: - API Key via `X-API-Key` header parameter - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Tenant/project come from the ingress headers. The owner is the caller itself (derived from x-user-id) — there are no body fields. #### scheduled-jobs-deleteJobsForOwner-request Delete all jobs owned by the authenticated end user in the current project. ```json {} ``` ## Responses ### 200 — Scheduled jobs deleted Content type: `application/json` Result of deleting scheduled jobs belonging to the selected owner. **deletedCount** `string(int64)` Number of scheduled jobs deleted by the operation. Pattern: ^-?\d+$ #### scheduled-jobs-deleteJobsForOwner-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "deletedCount": 1 } ``` #### cookbook-core-platform-scheduling-managing-json-01-response Illustrative response for Account cleanup: remove all of the user’s schedules. Replace example resource identifiers with your own authorized values. ```json { "deletedCount": 3 } ``` Document ID: `DOC-CP-scheduling-api-deleteJobsForOwner`. [Section identities and revisions](/documentation-manifest.json). - Delete all scheduled jobs for the calling owner: `DOC-CP-scheduling-api-deleteJobsForOwner#overview` - Request: `DOC-CP-scheduling-api-deleteJobsForOwner#request` - Responses: `DOC-CP-scheduling-api-deleteJobsForOwner#responses` --- # Delete all scheduled jobs for a project URL: https://docs.travila.ai/api/scheduled-jobs/delete-jobs-for-project **POST** `/api/v1/scheduler/delete-jobs-for-project` Soft-deletes every scheduled job belonging to the tenant and project in the request context. Intended as a tenant lifecycle hook invoked during project teardown. The request body carries no fields — tenant and project are derived from ingress headers. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Manage jobs](/core-platform/scheduling/managing) ## Authentication One of: - API Key via `X-API-Key` header parameter - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Tenant/project come from the ingress headers — the request body carries no fields. #### scheduled-jobs-deleteJobsForProject-request Delete all jobs in the authenticated project; this operation has no per-job selector. ```json {} ``` ## Responses ### 200 — Scheduled jobs deleted Content type: `application/json` Result of deleting scheduled jobs within the selected project. **deletedCount** `string(int64)` Number of scheduled jobs deleted by the operation. Pattern: ^-?\d+$ #### scheduled-jobs-deleteJobsForProject-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "deletedCount": 1 } ``` #### cookbook-core-platform-scheduling-managing-json-02-response Illustrative response for Project teardown: remove schedules across all owners. Replace example resource identifiers with your own authorized values. ```json { "deletedCount": 47 } ``` Document ID: `DOC-CP-scheduling-api-deleteJobsForProject`. [Section identities and revisions](/documentation-manifest.json). - Delete all scheduled jobs for a project: `DOC-CP-scheduling-api-deleteJobsForProject#overview` - Request: `DOC-CP-scheduling-api-deleteJobsForProject#request` - Responses: `DOC-CP-scheduling-api-deleteJobsForProject#responses` --- # Get a scheduled job URL: https://docs.travila.ai/api/scheduled-jobs/get-job **POST** `/api/v1/scheduler/get-job` Returns the metadata and current state of a single scheduled job by ID. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Manage jobs](/core-platform/scheduling/managing) ## Authentication One of: - API Key via `X-API-Key` header parameter - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for retrieving a scheduled job and its trigger settings. ### Input constraints ### Record relationship Exactly one of schedule\_id or external\_id must be nonempty. Supplying neither or supplying both does not satisfy this condition. **scheduleId** `string` Identifier of the scheduled job. **externalId** `string` Caller-assigned correlation identifier for the scheduled job. #### scheduled-jobs-getJob-request Replace scheduleId with the ID returned when the job was created. ```json { "scheduleId": "sched_a1b2c3d4e5f60718" } ``` #### cookbook-core-platform-scheduling-managing-01-request Guide request for 1. Load the reminder being changed. Replace example resource identifiers with your own authorized values. ```json { "scheduleId": "sched_a1b2c3d4e5f60718" } ``` #### cookbook-core-platform-scheduling-managing-09-request Guide request for Variant: use your application’s reminder identifier. Replace example resource identifiers with your own authorized values. ```json { "externalId": "user-42-daily-digest" } ``` ## Responses ### 200 — Scheduled job returned Content type: `application/json` Schedule is the canonical representation of a scheduled job. Creating any schedule type returns the `Schedule` resource directly, with the same shape used by get, pause and resume operations. [`triggerCount`](/api/models/schema-1ld0l8rmvg#response-field-triggercount): Cumulative firings. [`failureCount`](/api/models/schema-1ld0l8rmvg#response-field-failurecount): Cumulative failed first attempts; a later successful retry does not erase the earlier failure. [`consecutiveFailureCount`](/api/models/schema-1ld0l8rmvg#response-field-consecutivefailurecount): Current sequence of failed firings; a successful attempt resets it. This counter drives auto-pause. Zero-valued counters can be omitted. Nonzero 64-bit counters are decimal JSON strings; preserve their integer precision. Model reference: [Schedule](/api/models/schema-1ld0l8rmvg#response). **scheduleId** `string` Server-assigned identifier of the scheduled job, prefixed with "sched\_". **tenantId** `string` Identifier of the tenant that owns or scopes this record. **projectId** `string` Identifier of the project within the tenant that scopes this record. **ownerSubject** `string` Subject identifier of the owning user or service account. **name** `string` Human-readable name assigned to the scheduled job. **description** `string` Human-readable explanation of the scheduled job. **scheduleType** `any` Schedule type and expression. Expression format that determines when a scheduled job fires.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCHEDULE_TYPE_CRON` | 0 | Canonical | Fire according to the configured cron expression and timezone. For example, `0 9 * * 1-5` selects 09:00 on weekdays in that timezone. | | `SCHEDULE_TYPE_ONCE` | 1 | Canonical | Fire once at the configured scheduled timestamp. | | `SCHEDULE_TYPE_RECURRING_INTERVAL` | 2 | Canonical | Fire repeatedly at the configured interval in seconds. |
Exactly one of: Variant 1: Type: `string` Enum: `SCHEDULE_TYPE_CRON`, `SCHEDULE_TYPE_ONCE`, `SCHEDULE_TYPE_RECURRING_INTERVAL` Variant 2: Type: `integer(int32)` **cronExpression** `string` Cron expression. Populated when schedule\_type is SCHEDULE\_TYPE\_CRON. **timezone** `string` IANA timezone for cron evaluation. Default "UTC". **scheduledAt** `string(date-time)` Exact fire time. Populated when schedule\_type is SCHEDULE\_TYPE\_ONCE. **intervalSeconds** `string(int64)` Interval between firings in seconds. Populated when schedule\_type is SCHEDULE\_TYPE\_RECURRING\_INTERVAL. Pattern: ^-?\d+$ **target** `any` Destination and invocation settings for the scheduled job. All of: Variant 1: ScheduleTarget describes the HTTP endpoint that receives each job invocation. Model reference: [ScheduleTarget](/api/models/schema-1lbkptb5rj#response). **url** `string` Destination URL. Must be a valid absolute URI. **method** `string` HTTP method to use. Defaults to "POST". **kind** `string` Logical kind used for routing and observability (e.g., "notification", "llm\_conversation", "metering"). Required. **payload** `map[string, any]` Arbitrary JSON payload forwarded verbatim to the target. **state** `any` Lifecycle status controlling whether the scheduled job can trigger. Lifecycle condition that determines whether a scheduled job may trigger: active, paused, or deleted. This is separate from the outcome of an individual scheduled-job execution.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCHEDULE_STATUS_ACTIVE` | 0 | Canonical | The schedule is active and can trigger at its next matching time. | | `SCHEDULE_STATUS_PAUSED` | 1 | Canonical | The schedule is paused and does not trigger until resumed. | | `SCHEDULE_STATUS_DELETED` | 2 | Canonical | The schedule has been deleted; this is a schedule condition, not an execution outcome. |
Exactly one of: Variant 1: Type: `string` Enum: `SCHEDULE_STATUS_ACTIVE`, `SCHEDULE_STATUS_PAUSED`, `SCHEDULE_STATUS_DELETED` Variant 2: Type: `integer(int32)` **retryPolicy** `any` Attempt limits and backoff settings for the scheduled target. All of: Variant 1: RetryPolicy controls how failed executions are retried. Model reference: [RetryPolicy](/api/models/schema-1l9ki2op1i#response). **maxAttempts** `string(int64)` Maximum delivery attempts (including the initial attempt). Default 10. Pattern: ^-?\d+$ **initialBackoffMs** `string(int64)` Initial backoff before the first retry, in milliseconds. Default 5000. Pattern: ^-?\d+$ **maxBackoffMs** `string(int64)` Maximum backoff cap, in milliseconds. Default 1800000 (30 min). Pattern: ^-?\d+$ **metadata** `map[string, any]` Application-defined JSON metadata attached to the scheduled job. **autoPauseThreshold** `string(int64)` If consecutive\_failure\_count reaches this threshold the job is auto-paused (state PAUSED, paused\_by\_subject "system\:auto-pause"). It is compared against consecutive\_failure\_count, NOT failure\_count. failure\_count is cumulative for the schedule's whole life, so a healthy schedule that collects scattered failures over months would eventually exceed any threshold and pause itself forever. A stored threshold of 0 disables auto-pause; otherwise the threshold is from 3 through 100. The public create request uses 0 or omission to select the default of 10, and the public update request uses 0 or omission to leave the current threshold unchanged. These public requests do not provide a disable control. Pattern: ^-?\d+$ **externalId** `string` Client-supplied external id. Echoed back when set; empty otherwise. Optional, immutable, unique within (tenant\_id, project\_id) among live schedules. Never starts with the reserved system-id prefix "sched\_". **createdAt** `string(date-time)` Time at which the scheduled job was created. **createdBySubject** `string` Subject identifier recorded when the schedule was created. **updatedAt** `string(date-time)` Time this record was most recently updated. **updatedBySubject** `string` Subject identifier recorded when the schedule was last updated. **pausedAt** `string(date-time)` Time at which the schedule was paused. **pausedBySubject** `string` Subject identifier recorded for the schedule pause. **pausedReason** `string` Explanation recorded for the schedule pause. **resumedAt** `string(date-time)` Time at which the schedule was most recently resumed. **resumedBySubject** `string` Subject identifier recorded for the schedule resume. **deletedAt** `string(date-time)` Time at which the schedule was deleted. **deletedBySubject** `string` Subject identifier recorded for the schedule deletion. **lastTriggeredAt** `string(date-time)` Time when the schedule was last triggered. Trigger and failure counters advance at most once per scheduled firing on its first attempt; retrying that firing does not inflate them. **nextTriggerAt** `string(date-time)` Time calculated for the next scheduled trigger. **triggerCount** `string(int64)` Scheduled times that ran, cumulative for the schedule's whole life. Pattern: ^-?\d+$ **failureCount** `string(int64)` Scheduled times whose first attempt failed, cumulative for the schedule's whole life. A firing that fails on attempt 1 and succeeds on retry still counts here — a failure was observed. This counter does NOT drive auto-pause. See consecutive\_failure\_count. Pattern: ^-?\d+$ **consecutiveFailureCount** `string(int64)` Current run of consecutive failed firings. This is the counter auto\_pause\_threshold is compared against. Incremented when a firing's first attempt fails; reset to 0 as soon as any attempt of any firing succeeds. So a firing that fails on attempt 1 and succeeds on retry has net zero effect here while still advancing failure\_count — the target recovered, so the run is over. A non-success terminal outcome counts as a failure, including a firing cancelled on a terminal 4xx. Pattern: ^-?\d+$ #### scheduled-jobs-getJob-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "scheduleId": "sched_a1b2c3d4e5f60718", "tenantId": "example_123", "projectId": "example_123", "ownerSubject": "example", "name": "example", "description": "example", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * *", "timezone": "example", "scheduledAt": "2026-09-16T12:00:00Z", "intervalSeconds": 1, "target": { "url": "https://example.com/callback", "method": "example", "kind": "example", "payload": { "example": "value" } }, "state": "SCHEDULE_STATUS_ACTIVE", "retryPolicy": { "maxAttempts": 1, "initialBackoffMs": 1, "maxBackoffMs": 1 }, "metadata": { "example": "value" }, "autoPauseThreshold": 1, "externalId": "example_123", "createdAt": "2026-09-16T12:00:00Z", "createdBySubject": "example", "updatedAt": "2026-09-16T12:00:00Z", "updatedBySubject": "example", "pausedAt": "2026-09-16T12:00:00Z", "pausedBySubject": "example", "pausedReason": "example", "resumedAt": "2026-09-16T12:00:00Z", "resumedBySubject": "example", "deletedAt": "2026-09-16T12:00:00Z", "deletedBySubject": "example", "lastTriggeredAt": "2026-09-16T12:00:00Z", "nextTriggerAt": "2026-09-16T12:00:00Z", "triggerCount": "1", "failureCount": "1", "consecutiveFailureCount": "1" } ``` Document ID: `DOC-CP-scheduling-api-getJob`. [Section identities and revisions](/documentation-manifest.json). - Get a scheduled job: `DOC-CP-scheduling-api-getJob#overview` - Request: `DOC-CP-scheduling-api-getJob#request` - Responses: `DOC-CP-scheduling-api-getJob#responses` --- # List executions for a scheduled job URL: https://docs.travila.ai/api/scheduled-jobs/list-executions **POST** `/api/v1/scheduler/list-executions` Returns a paginated execution history for a scheduled job. Each record captures a single firing — its status, HTTP result, attempt number, and duration. Optionally filter by execution status. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Monitor executions and retries](/core-platform/scheduling/execution) ## Authentication One of: - API Key via `X-API-Key` header parameter - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for listing the execution history of a scheduled job. **scheduleId** `string` **required** Identifier of the scheduled job. Minimum length: 1 **pageSize** `string(int64)` Number of entries requested per page. Zero or omission lets the server choose its default. Pattern: ^-?\d+$ **pageToken** `string` Continuation token from a previous response; leave empty to start the listing. **statusFilter** `any` Execution status used to restrict the execution history. Terminal result of one scheduled-job firing. Use `end_reason` for additional information about a non-successful result. A firing that exhausts its delivery attempts has status FAILED and `end_reason` "discarded".
| Value | No. | Form | Meaning | |---|---|---|---| | `EXECUTION_STATUS_COMPLETED` | 0 | Canonical | The scheduled HTTP dispatch received a status below 400; this does not establish completion of downstream asynchronous work. | | `EXECUTION_STATUS_FAILED` | 1 | Canonical | The firing failed, including exhausted delivery attempts; inspect end\_reason. | | `EXECUTION_STATUS_CANCELLED` | 2 | Canonical | The firing was cancelled rather than completed, for example by an operator or a non-HTTP cancellation condition, such as a permanent failure to obtain dispatch credentials before the request is sent. |
Exactly one of: Variant 1: Type: `string` Enum: `EXECUTION_STATUS_COMPLETED`, `EXECUTION_STATUS_FAILED`, `EXECUTION_STATUS_CANCELLED` Variant 2: Type: `integer(int32)` #### scheduled-jobs-listExecutions-request Replace scheduleId with the ID returned when the job was created. ```json { "scheduleId": "sched_a1b2c3d4e5f60718" } ``` #### cookbook-core-platform-scheduling-execution-01-request Guide request for Find where the missing digest stopped. Replace example resource identifiers with your own authorized values. ```json { "scheduleId": "sched_a1b2c3d4e5f60718", "pageSize": 20, "statusFilter": "EXECUTION_STATUS_FAILED" } ``` ## Responses ### 200 — Executions returned Content type: `application/json` Result of listing the execution history of a scheduled job. **executions** `array[platform_v1_services_scheduler_v1_Execution]` Scheduled execution records included in this result page. Execution is a single firing record for a scheduled job. Model reference: [Execution](/api/models/schema-1l7vrun3li#response). **executionId** `string(int64)` Identifier of the scheduled job execution record. Pattern: ^-?\d+$ **scheduleId** `string` Identifier of the scheduled job. **tenantId** `string` Identifier of the tenant that owns or scopes this record. **projectId** `string` Identifier of the project within the tenant that scopes this record. **scheduledTime** `string(date-time)` Instant for which this execution or trigger was scheduled. **startedAt** `string(date-time)` Time at which the scheduled execution started. **completedAt** `string(date-time)` Time at which the scheduled execution completed. **status** `any` Execution outcome recorded for this scheduled attempt. Terminal result of one scheduled-job firing. Use `end_reason` for additional information about a non-successful result. A firing that exhausts its delivery attempts has status FAILED and `end_reason` "discarded".
| Value | No. | Form | Meaning | |---|---|---|---| | `EXECUTION_STATUS_COMPLETED` | 0 | Canonical | The scheduled HTTP dispatch received a status below 400; this does not establish completion of downstream asynchronous work. | | `EXECUTION_STATUS_FAILED` | 1 | Canonical | The firing failed, including exhausted delivery attempts; inspect end\_reason. | | `EXECUTION_STATUS_CANCELLED` | 2 | Canonical | The firing was cancelled rather than completed, for example by an operator or a non-HTTP cancellation condition, such as a permanent failure to obtain dispatch credentials before the request is sent. |
Exactly one of: Variant 1: Type: `string` Enum: `EXECUTION_STATUS_COMPLETED`, `EXECUTION_STATUS_FAILED`, `EXECUTION_STATUS_CANCELLED` Variant 2: Type: `integer(int32)` **httpStatus** `string(int64)` HTTP status code returned by the target. Pattern: ^-?\d+$ **attempt** `string(int64)` Attempt number (1-based) within this firing. Pattern: ^-?\d+$ **durationMs** `string(int64)` End-to-end duration of the delivery attempt, in milliseconds. Pattern: ^-?\d+$ **targetKind** `string` Kind of target invoked by the scheduled execution. **error** `string` Error message when status is FAILED. **responseBody** `string` Truncated HTTP response body captured on failed dispatches, with a 4 KiB cap. Empty for successful dispatches by design — only error responses are stored. May also be empty for binary content types or transport-level errors (see response\_size\_bytes / error). **responseHeaders** `map[string, string]` Allowlisted response headers from the failed dispatch. Allowlist: content-type, content-length, retry-after, x-request-id, date. **responseTruncated** `boolean` True when response\_body was clipped at the 4 KiB cap. **responseSizeBytes** `string(int64)` Original response size in bytes (from Content-Length when present, else total bytes read before truncation). Pattern: ^-?\d+$ **endReason** `string` Explanation of an execution failure when status alone is insufficient. `discarded` means the job exhausted `maxAttempts` and will not be retried. Empty when there is no additional reason. **nextPageToken** `string` Opaque cursor token for the next page. Empty when no further pages exist. #### scheduled-jobs-listExecutions-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "executions": [ { "executionId": "1", "scheduleId": "sched_a1b2c3d4e5f60718", "tenantId": "example_123", "projectId": "example_123", "scheduledTime": "2026-09-16T12:00:00Z", "startedAt": "2026-09-16T12:00:00Z", "completedAt": "2026-09-16T12:00:00Z", "status": "EXECUTION_STATUS_COMPLETED", "httpStatus": 1, "attempt": 1, "durationMs": 1, "targetKind": "example", "error": "example", "responseBody": "example", "responseHeaders": {}, "responseTruncated": true, "responseSizeBytes": 1, "endReason": "example" } ], "nextPageToken": "example" } ``` Document ID: `DOC-CP-scheduling-api-listExecutions`. [Section identities and revisions](/documentation-manifest.json). - List executions for a scheduled job: `DOC-CP-scheduling-api-listExecutions#overview` - Request: `DOC-CP-scheduling-api-listExecutions#request` - Responses: `DOC-CP-scheduling-api-listExecutions#responses` --- # List scheduled jobs URL: https://docs.travila.ai/api/scheduled-jobs/list-jobs **POST** `/api/v1/scheduler/list-jobs` Returns a paginated list of scheduled jobs for the authenticated tenant and project. Optionally filter by lifecycle state or target kind. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Manage jobs](/core-platform/scheduling/managing) ## Authentication One of: - API Key via `X-API-Key` header parameter - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for listing scheduled jobs and their trigger settings. A zero or omitted page size lets the server choose its default. **pageSize** `string(int64)` Number of entries requested per page. Zero or omission lets the server choose its default. Pattern: ^-?\d+$ **pageToken** `string` Continuation token from a previous response; leave empty to start the listing. **stateFilter** `any` Schedule lifecycle status used to restrict the job listing. Lifecycle condition that determines whether a scheduled job may trigger: active, paused, or deleted. This is separate from the outcome of an individual scheduled-job execution.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCHEDULE_STATUS_ACTIVE` | 0 | Canonical | The schedule is active and can trigger at its next matching time. | | `SCHEDULE_STATUS_PAUSED` | 1 | Canonical | The schedule is paused and does not trigger until resumed. | | `SCHEDULE_STATUS_DELETED` | 2 | Canonical | The schedule has been deleted; this is a schedule condition, not an execution outcome. |
Exactly one of: Variant 1: Type: `string` Enum: `SCHEDULE_STATUS_ACTIVE`, `SCHEDULE_STATUS_PAUSED`, `SCHEDULE_STATUS_DELETED` Variant 2: Type: `integer(int32)` **targetKindFilter** `string` Target kind used to restrict the scheduled job listing. #### scheduled-jobs-listJobs-request List jobs visible in the authenticated scope with default paging. ```json {} ``` #### cookbook-core-platform-scheduling-managing-02-request Guide request for Variant: show the user’s reminder list. Replace example resource identifiers with your own authorized values. ```json { "pageSize": 20, "stateFilter": "SCHEDULE_STATUS_ACTIVE" } ``` ## Responses ### 200 — Scheduled jobs returned Content type: `application/json` Result of listing scheduled jobs and their trigger settings. **schedules** `array[platform_v1_services_scheduler_v1_Schedule]` Scheduled jobs included in this result page. Schedule is the canonical representation of a scheduled job. Creating any schedule type returns the `Schedule` resource directly, with the same shape used by get, pause and resume operations. [`triggerCount`](/api/models/schema-1ld0l8rmvg#response-field-triggercount): Cumulative firings. [`failureCount`](/api/models/schema-1ld0l8rmvg#response-field-failurecount): Cumulative failed first attempts; a later successful retry does not erase the earlier failure. [`consecutiveFailureCount`](/api/models/schema-1ld0l8rmvg#response-field-consecutivefailurecount): Current sequence of failed firings; a successful attempt resets it. This counter drives auto-pause. Zero-valued counters can be omitted. Nonzero 64-bit counters are decimal JSON strings; preserve their integer precision. Model reference: [Schedule](/api/models/schema-1ld0l8rmvg#response). **scheduleId** `string` Server-assigned identifier of the scheduled job, prefixed with "sched\_". **tenantId** `string` Identifier of the tenant that owns or scopes this record. **projectId** `string` Identifier of the project within the tenant that scopes this record. **ownerSubject** `string` Subject identifier of the owning user or service account. **name** `string` Human-readable name assigned to the scheduled job. **description** `string` Human-readable explanation of the scheduled job. **scheduleType** `any` Schedule type and expression. Expression format that determines when a scheduled job fires.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCHEDULE_TYPE_CRON` | 0 | Canonical | Fire according to the configured cron expression and timezone. For example, `0 9 * * 1-5` selects 09:00 on weekdays in that timezone. | | `SCHEDULE_TYPE_ONCE` | 1 | Canonical | Fire once at the configured scheduled timestamp. | | `SCHEDULE_TYPE_RECURRING_INTERVAL` | 2 | Canonical | Fire repeatedly at the configured interval in seconds. |
Exactly one of: Variant 1: Type: `string` Enum: `SCHEDULE_TYPE_CRON`, `SCHEDULE_TYPE_ONCE`, `SCHEDULE_TYPE_RECURRING_INTERVAL` Variant 2: Type: `integer(int32)` **cronExpression** `string` Cron expression. Populated when schedule\_type is SCHEDULE\_TYPE\_CRON. **timezone** `string` IANA timezone for cron evaluation. Default "UTC". **scheduledAt** `string(date-time)` Exact fire time. Populated when schedule\_type is SCHEDULE\_TYPE\_ONCE. **intervalSeconds** `string(int64)` Interval between firings in seconds. Populated when schedule\_type is SCHEDULE\_TYPE\_RECURRING\_INTERVAL. Pattern: ^-?\d+$ **target** `any` Destination and invocation settings for the scheduled job. All of: Variant 1: ScheduleTarget describes the HTTP endpoint that receives each job invocation. Model reference: [ScheduleTarget](/api/models/schema-1lbkptb5rj#response). **url** `string` Destination URL. Must be a valid absolute URI. **method** `string` HTTP method to use. Defaults to "POST". **kind** `string` Logical kind used for routing and observability (e.g., "notification", "llm\_conversation", "metering"). Required. **payload** `map[string, any]` Arbitrary JSON payload forwarded verbatim to the target. **state** `any` Lifecycle status controlling whether the scheduled job can trigger. Lifecycle condition that determines whether a scheduled job may trigger: active, paused, or deleted. This is separate from the outcome of an individual scheduled-job execution.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCHEDULE_STATUS_ACTIVE` | 0 | Canonical | The schedule is active and can trigger at its next matching time. | | `SCHEDULE_STATUS_PAUSED` | 1 | Canonical | The schedule is paused and does not trigger until resumed. | | `SCHEDULE_STATUS_DELETED` | 2 | Canonical | The schedule has been deleted; this is a schedule condition, not an execution outcome. |
Exactly one of: Variant 1: Type: `string` Enum: `SCHEDULE_STATUS_ACTIVE`, `SCHEDULE_STATUS_PAUSED`, `SCHEDULE_STATUS_DELETED` Variant 2: Type: `integer(int32)` **retryPolicy** `any` Attempt limits and backoff settings for the scheduled target. All of: Variant 1: RetryPolicy controls how failed executions are retried. Model reference: [RetryPolicy](/api/models/schema-1l9ki2op1i#response). **maxAttempts** `string(int64)` Maximum delivery attempts (including the initial attempt). Default 10. Pattern: ^-?\d+$ **initialBackoffMs** `string(int64)` Initial backoff before the first retry, in milliseconds. Default 5000. Pattern: ^-?\d+$ **maxBackoffMs** `string(int64)` Maximum backoff cap, in milliseconds. Default 1800000 (30 min). Pattern: ^-?\d+$ **metadata** `map[string, any]` Application-defined JSON metadata attached to the scheduled job. **autoPauseThreshold** `string(int64)` If consecutive\_failure\_count reaches this threshold the job is auto-paused (state PAUSED, paused\_by\_subject "system\:auto-pause"). It is compared against consecutive\_failure\_count, NOT failure\_count. failure\_count is cumulative for the schedule's whole life, so a healthy schedule that collects scattered failures over months would eventually exceed any threshold and pause itself forever. A stored threshold of 0 disables auto-pause; otherwise the threshold is from 3 through 100. The public create request uses 0 or omission to select the default of 10, and the public update request uses 0 or omission to leave the current threshold unchanged. These public requests do not provide a disable control. Pattern: ^-?\d+$ **externalId** `string` Client-supplied external id. Echoed back when set; empty otherwise. Optional, immutable, unique within (tenant\_id, project\_id) among live schedules. Never starts with the reserved system-id prefix "sched\_". **createdAt** `string(date-time)` Time at which the scheduled job was created. **createdBySubject** `string` Subject identifier recorded when the schedule was created. **updatedAt** `string(date-time)` Time this record was most recently updated. **updatedBySubject** `string` Subject identifier recorded when the schedule was last updated. **pausedAt** `string(date-time)` Time at which the schedule was paused. **pausedBySubject** `string` Subject identifier recorded for the schedule pause. **pausedReason** `string` Explanation recorded for the schedule pause. **resumedAt** `string(date-time)` Time at which the schedule was most recently resumed. **resumedBySubject** `string` Subject identifier recorded for the schedule resume. **deletedAt** `string(date-time)` Time at which the schedule was deleted. **deletedBySubject** `string` Subject identifier recorded for the schedule deletion. **lastTriggeredAt** `string(date-time)` Time when the schedule was last triggered. Trigger and failure counters advance at most once per scheduled firing on its first attempt; retrying that firing does not inflate them. **nextTriggerAt** `string(date-time)` Time calculated for the next scheduled trigger. **triggerCount** `string(int64)` Scheduled times that ran, cumulative for the schedule's whole life. Pattern: ^-?\d+$ **failureCount** `string(int64)` Scheduled times whose first attempt failed, cumulative for the schedule's whole life. A firing that fails on attempt 1 and succeeds on retry still counts here — a failure was observed. This counter does NOT drive auto-pause. See consecutive\_failure\_count. Pattern: ^-?\d+$ **consecutiveFailureCount** `string(int64)` Current run of consecutive failed firings. This is the counter auto\_pause\_threshold is compared against. Incremented when a firing's first attempt fails; reset to 0 as soon as any attempt of any firing succeeds. So a firing that fails on attempt 1 and succeeds on retry has net zero effect here while still advancing failure\_count — the target recovered, so the run is over. A non-success terminal outcome counts as a failure, including a firing cancelled on a terminal 4xx. Pattern: ^-?\d+$ **nextPageToken** `string` Opaque cursor token for the next page. Empty when no further pages exist. **totalCount** `string(int64)` Total number of records reported for this listing. Pattern: ^-?\d+$ #### scheduled-jobs-listJobs-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "schedules": [ { "scheduleId": "sched_a1b2c3d4e5f60718", "tenantId": "example_123", "projectId": "example_123", "ownerSubject": "example", "name": "example", "description": "example", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * *", "timezone": "example", "scheduledAt": "2026-09-16T12:00:00Z", "intervalSeconds": 1, "target": { "url": "https://example.com/callback", "method": "example", "kind": "example" }, "state": "SCHEDULE_STATUS_ACTIVE", "retryPolicy": { "maxAttempts": 1, "initialBackoffMs": 1, "maxBackoffMs": 1 }, "metadata": { "example": "value" }, "autoPauseThreshold": 1, "externalId": "example_123", "createdAt": "2026-09-16T12:00:00Z", "createdBySubject": "example", "updatedAt": "2026-09-16T12:00:00Z", "updatedBySubject": "example", "pausedAt": "2026-09-16T12:00:00Z", "pausedBySubject": "example", "pausedReason": "example", "resumedAt": "2026-09-16T12:00:00Z", "resumedBySubject": "example", "deletedAt": "2026-09-16T12:00:00Z", "deletedBySubject": "example", "lastTriggeredAt": "2026-09-16T12:00:00Z", "nextTriggerAt": "2026-09-16T12:00:00Z", "triggerCount": "1", "failureCount": "1", "consecutiveFailureCount": "1" } ], "nextPageToken": "example", "totalCount": 1 } ``` Document ID: `DOC-CP-scheduling-api-listJobs`. [Section identities and revisions](/documentation-manifest.json). - List scheduled jobs: `DOC-CP-scheduling-api-listJobs#overview` - Request: `DOC-CP-scheduling-api-listJobs#request` - Responses: `DOC-CP-scheduling-api-listJobs#responses` --- # Pause a scheduled job URL: https://docs.travila.ai/api/scheduled-jobs/pause-job **POST** `/api/v1/scheduler/pause-job` Pauses future scheduling for the job. A dispatch already admitted or in flight can still complete; pausing is not remote-effect cancellation. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Manage jobs](/core-platform/scheduling/managing) ## Authentication One of: - API Key via `X-API-Key` header parameter - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for pausing a scheduled job and its trigger settings. Exactly one of schedule\_id or external\_id must be nonempty. Supplying neither or both does not satisfy this condition. **scheduleId** `string` Identifier of the scheduled job. **reason** `string` Explanation recorded for pausing the scheduled job. **externalId** `string` Caller-assigned correlation identifier for the scheduled job. #### scheduled-jobs-pauseJob-request Replace scheduleId with the ID returned when the job was created. ```json { "scheduleId": "sched_a1b2c3d4e5f60718" } ``` #### cookbook-core-platform-scheduling-managing-04-1-request Guide request for 3. Let the user take a temporary break. Replace example resource identifiers with your own authorized values. ```json { "scheduleId": "sched_a1b2c3d4e5f60718", "reason": "Target service under maintenance" } ``` ## Responses ### 200 — Scheduled job paused Content type: `application/json` Schedule is the canonical representation of a scheduled job. Creating any schedule type returns the `Schedule` resource directly, with the same shape used by get, pause and resume operations. [`triggerCount`](/api/models/schema-1ld0l8rmvg#response-field-triggercount): Cumulative firings. [`failureCount`](/api/models/schema-1ld0l8rmvg#response-field-failurecount): Cumulative failed first attempts; a later successful retry does not erase the earlier failure. [`consecutiveFailureCount`](/api/models/schema-1ld0l8rmvg#response-field-consecutivefailurecount): Current sequence of failed firings; a successful attempt resets it. This counter drives auto-pause. Zero-valued counters can be omitted. Nonzero 64-bit counters are decimal JSON strings; preserve their integer precision. Model reference: [Schedule](/api/models/schema-1ld0l8rmvg#response). **scheduleId** `string` Server-assigned identifier of the scheduled job, prefixed with "sched\_". **tenantId** `string` Identifier of the tenant that owns or scopes this record. **projectId** `string` Identifier of the project within the tenant that scopes this record. **ownerSubject** `string` Subject identifier of the owning user or service account. **name** `string` Human-readable name assigned to the scheduled job. **description** `string` Human-readable explanation of the scheduled job. **scheduleType** `any` Schedule type and expression. Expression format that determines when a scheduled job fires.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCHEDULE_TYPE_CRON` | 0 | Canonical | Fire according to the configured cron expression and timezone. For example, `0 9 * * 1-5` selects 09:00 on weekdays in that timezone. | | `SCHEDULE_TYPE_ONCE` | 1 | Canonical | Fire once at the configured scheduled timestamp. | | `SCHEDULE_TYPE_RECURRING_INTERVAL` | 2 | Canonical | Fire repeatedly at the configured interval in seconds. |
Exactly one of: Variant 1: Type: `string` Enum: `SCHEDULE_TYPE_CRON`, `SCHEDULE_TYPE_ONCE`, `SCHEDULE_TYPE_RECURRING_INTERVAL` Variant 2: Type: `integer(int32)` **cronExpression** `string` Cron expression. Populated when schedule\_type is SCHEDULE\_TYPE\_CRON. **timezone** `string` IANA timezone for cron evaluation. Default "UTC". **scheduledAt** `string(date-time)` Exact fire time. Populated when schedule\_type is SCHEDULE\_TYPE\_ONCE. **intervalSeconds** `string(int64)` Interval between firings in seconds. Populated when schedule\_type is SCHEDULE\_TYPE\_RECURRING\_INTERVAL. Pattern: ^-?\d+$ **target** `any` Destination and invocation settings for the scheduled job. All of: Variant 1: ScheduleTarget describes the HTTP endpoint that receives each job invocation. Model reference: [ScheduleTarget](/api/models/schema-1lbkptb5rj#response). **url** `string` Destination URL. Must be a valid absolute URI. **method** `string` HTTP method to use. Defaults to "POST". **kind** `string` Logical kind used for routing and observability (e.g., "notification", "llm\_conversation", "metering"). Required. **payload** `map[string, any]` Arbitrary JSON payload forwarded verbatim to the target. **state** `any` Lifecycle status controlling whether the scheduled job can trigger. Lifecycle condition that determines whether a scheduled job may trigger: active, paused, or deleted. This is separate from the outcome of an individual scheduled-job execution.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCHEDULE_STATUS_ACTIVE` | 0 | Canonical | The schedule is active and can trigger at its next matching time. | | `SCHEDULE_STATUS_PAUSED` | 1 | Canonical | The schedule is paused and does not trigger until resumed. | | `SCHEDULE_STATUS_DELETED` | 2 | Canonical | The schedule has been deleted; this is a schedule condition, not an execution outcome. |
Exactly one of: Variant 1: Type: `string` Enum: `SCHEDULE_STATUS_ACTIVE`, `SCHEDULE_STATUS_PAUSED`, `SCHEDULE_STATUS_DELETED` Variant 2: Type: `integer(int32)` **retryPolicy** `any` Attempt limits and backoff settings for the scheduled target. All of: Variant 1: RetryPolicy controls how failed executions are retried. Model reference: [RetryPolicy](/api/models/schema-1l9ki2op1i#response). **maxAttempts** `string(int64)` Maximum delivery attempts (including the initial attempt). Default 10. Pattern: ^-?\d+$ **initialBackoffMs** `string(int64)` Initial backoff before the first retry, in milliseconds. Default 5000. Pattern: ^-?\d+$ **maxBackoffMs** `string(int64)` Maximum backoff cap, in milliseconds. Default 1800000 (30 min). Pattern: ^-?\d+$ **metadata** `map[string, any]` Application-defined JSON metadata attached to the scheduled job. **autoPauseThreshold** `string(int64)` If consecutive\_failure\_count reaches this threshold the job is auto-paused (state PAUSED, paused\_by\_subject "system\:auto-pause"). It is compared against consecutive\_failure\_count, NOT failure\_count. failure\_count is cumulative for the schedule's whole life, so a healthy schedule that collects scattered failures over months would eventually exceed any threshold and pause itself forever. A stored threshold of 0 disables auto-pause; otherwise the threshold is from 3 through 100. The public create request uses 0 or omission to select the default of 10, and the public update request uses 0 or omission to leave the current threshold unchanged. These public requests do not provide a disable control. Pattern: ^-?\d+$ **externalId** `string` Client-supplied external id. Echoed back when set; empty otherwise. Optional, immutable, unique within (tenant\_id, project\_id) among live schedules. Never starts with the reserved system-id prefix "sched\_". **createdAt** `string(date-time)` Time at which the scheduled job was created. **createdBySubject** `string` Subject identifier recorded when the schedule was created. **updatedAt** `string(date-time)` Time this record was most recently updated. **updatedBySubject** `string` Subject identifier recorded when the schedule was last updated. **pausedAt** `string(date-time)` Time at which the schedule was paused. **pausedBySubject** `string` Subject identifier recorded for the schedule pause. **pausedReason** `string` Explanation recorded for the schedule pause. **resumedAt** `string(date-time)` Time at which the schedule was most recently resumed. **resumedBySubject** `string` Subject identifier recorded for the schedule resume. **deletedAt** `string(date-time)` Time at which the schedule was deleted. **deletedBySubject** `string` Subject identifier recorded for the schedule deletion. **lastTriggeredAt** `string(date-time)` Time when the schedule was last triggered. Trigger and failure counters advance at most once per scheduled firing on its first attempt; retrying that firing does not inflate them. **nextTriggerAt** `string(date-time)` Time calculated for the next scheduled trigger. **triggerCount** `string(int64)` Scheduled times that ran, cumulative for the schedule's whole life. Pattern: ^-?\d+$ **failureCount** `string(int64)` Scheduled times whose first attempt failed, cumulative for the schedule's whole life. A firing that fails on attempt 1 and succeeds on retry still counts here — a failure was observed. This counter does NOT drive auto-pause. See consecutive\_failure\_count. Pattern: ^-?\d+$ **consecutiveFailureCount** `string(int64)` Current run of consecutive failed firings. This is the counter auto\_pause\_threshold is compared against. Incremented when a firing's first attempt fails; reset to 0 as soon as any attempt of any firing succeeds. So a firing that fails on attempt 1 and succeeds on retry has net zero effect here while still advancing failure\_count — the target recovered, so the run is over. A non-success terminal outcome counts as a failure, including a firing cancelled on a terminal 4xx. Pattern: ^-?\d+$ #### scheduled-jobs-pauseJob-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "scheduleId": "sched_a1b2c3d4e5f60718", "tenantId": "example_123", "projectId": "example_123", "ownerSubject": "example", "name": "example", "description": "example", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * *", "timezone": "example", "scheduledAt": "2026-09-16T12:00:00Z", "intervalSeconds": 1, "target": { "url": "https://example.com/callback", "method": "example", "kind": "example", "payload": { "example": "value" } }, "state": "SCHEDULE_STATUS_ACTIVE", "retryPolicy": { "maxAttempts": 1, "initialBackoffMs": 1, "maxBackoffMs": 1 }, "metadata": { "example": "value" }, "autoPauseThreshold": 1, "externalId": "example_123", "createdAt": "2026-09-16T12:00:00Z", "createdBySubject": "example", "updatedAt": "2026-09-16T12:00:00Z", "updatedBySubject": "example", "pausedAt": "2026-09-16T12:00:00Z", "pausedBySubject": "example", "pausedReason": "example", "resumedAt": "2026-09-16T12:00:00Z", "resumedBySubject": "example", "deletedAt": "2026-09-16T12:00:00Z", "deletedBySubject": "example", "lastTriggeredAt": "2026-09-16T12:00:00Z", "nextTriggerAt": "2026-09-16T12:00:00Z", "triggerCount": "1", "failureCount": "1", "consecutiveFailureCount": "1" } ``` Document ID: `DOC-CP-scheduling-api-pauseJob`. [Section identities and revisions](/documentation-manifest.json). - Pause a scheduled job: `DOC-CP-scheduling-api-pauseJob#overview` - Request: `DOC-CP-scheduling-api-pauseJob#request` - Responses: `DOC-CP-scheduling-api-pauseJob#responses` --- # Resume a scheduled job URL: https://docs.travila.ai/api/scheduled-jobs/resume-job **POST** `/api/v1/scheduler/resume-job` Resumes a previously paused scheduled job, returning it to the active state. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Manage jobs](/core-platform/scheduling/managing) ## Authentication One of: - API Key via `X-API-Key` header parameter - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for resuming a scheduled job and its trigger settings. ### Input constraints ### Record relationship Exactly one of schedule\_id or external\_id must be nonempty. Supplying neither or supplying both does not satisfy this condition. **scheduleId** `string` Identifier of the scheduled job. **externalId** `string` Caller-assigned correlation identifier for the scheduled job. #### scheduled-jobs-resumeJob-request Replace scheduleId with the ID returned when the job was created. ```json { "scheduleId": "sched_a1b2c3d4e5f60718" } ``` #### cookbook-core-platform-scheduling-managing-04-2-request Guide request for 3. Let the user take a temporary break. Replace example resource identifiers with your own authorized values. ```json { "scheduleId": "sched_a1b2c3d4e5f60718" } ``` ## Responses ### 200 — Scheduled job resumed Content type: `application/json` Schedule is the canonical representation of a scheduled job. Creating any schedule type returns the `Schedule` resource directly, with the same shape used by get, pause and resume operations. [`triggerCount`](/api/models/schema-1ld0l8rmvg#response-field-triggercount): Cumulative firings. [`failureCount`](/api/models/schema-1ld0l8rmvg#response-field-failurecount): Cumulative failed first attempts; a later successful retry does not erase the earlier failure. [`consecutiveFailureCount`](/api/models/schema-1ld0l8rmvg#response-field-consecutivefailurecount): Current sequence of failed firings; a successful attempt resets it. This counter drives auto-pause. Zero-valued counters can be omitted. Nonzero 64-bit counters are decimal JSON strings; preserve their integer precision. Model reference: [Schedule](/api/models/schema-1ld0l8rmvg#response). **scheduleId** `string` Server-assigned identifier of the scheduled job, prefixed with "sched\_". **tenantId** `string` Identifier of the tenant that owns or scopes this record. **projectId** `string` Identifier of the project within the tenant that scopes this record. **ownerSubject** `string` Subject identifier of the owning user or service account. **name** `string` Human-readable name assigned to the scheduled job. **description** `string` Human-readable explanation of the scheduled job. **scheduleType** `any` Schedule type and expression. Expression format that determines when a scheduled job fires.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCHEDULE_TYPE_CRON` | 0 | Canonical | Fire according to the configured cron expression and timezone. For example, `0 9 * * 1-5` selects 09:00 on weekdays in that timezone. | | `SCHEDULE_TYPE_ONCE` | 1 | Canonical | Fire once at the configured scheduled timestamp. | | `SCHEDULE_TYPE_RECURRING_INTERVAL` | 2 | Canonical | Fire repeatedly at the configured interval in seconds. |
Exactly one of: Variant 1: Type: `string` Enum: `SCHEDULE_TYPE_CRON`, `SCHEDULE_TYPE_ONCE`, `SCHEDULE_TYPE_RECURRING_INTERVAL` Variant 2: Type: `integer(int32)` **cronExpression** `string` Cron expression. Populated when schedule\_type is SCHEDULE\_TYPE\_CRON. **timezone** `string` IANA timezone for cron evaluation. Default "UTC". **scheduledAt** `string(date-time)` Exact fire time. Populated when schedule\_type is SCHEDULE\_TYPE\_ONCE. **intervalSeconds** `string(int64)` Interval between firings in seconds. Populated when schedule\_type is SCHEDULE\_TYPE\_RECURRING\_INTERVAL. Pattern: ^-?\d+$ **target** `any` Destination and invocation settings for the scheduled job. All of: Variant 1: ScheduleTarget describes the HTTP endpoint that receives each job invocation. Model reference: [ScheduleTarget](/api/models/schema-1lbkptb5rj#response). **url** `string` Destination URL. Must be a valid absolute URI. **method** `string` HTTP method to use. Defaults to "POST". **kind** `string` Logical kind used for routing and observability (e.g., "notification", "llm\_conversation", "metering"). Required. **payload** `map[string, any]` Arbitrary JSON payload forwarded verbatim to the target. **state** `any` Lifecycle status controlling whether the scheduled job can trigger. Lifecycle condition that determines whether a scheduled job may trigger: active, paused, or deleted. This is separate from the outcome of an individual scheduled-job execution.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCHEDULE_STATUS_ACTIVE` | 0 | Canonical | The schedule is active and can trigger at its next matching time. | | `SCHEDULE_STATUS_PAUSED` | 1 | Canonical | The schedule is paused and does not trigger until resumed. | | `SCHEDULE_STATUS_DELETED` | 2 | Canonical | The schedule has been deleted; this is a schedule condition, not an execution outcome. |
Exactly one of: Variant 1: Type: `string` Enum: `SCHEDULE_STATUS_ACTIVE`, `SCHEDULE_STATUS_PAUSED`, `SCHEDULE_STATUS_DELETED` Variant 2: Type: `integer(int32)` **retryPolicy** `any` Attempt limits and backoff settings for the scheduled target. All of: Variant 1: RetryPolicy controls how failed executions are retried. Model reference: [RetryPolicy](/api/models/schema-1l9ki2op1i#response). **maxAttempts** `string(int64)` Maximum delivery attempts (including the initial attempt). Default 10. Pattern: ^-?\d+$ **initialBackoffMs** `string(int64)` Initial backoff before the first retry, in milliseconds. Default 5000. Pattern: ^-?\d+$ **maxBackoffMs** `string(int64)` Maximum backoff cap, in milliseconds. Default 1800000 (30 min). Pattern: ^-?\d+$ **metadata** `map[string, any]` Application-defined JSON metadata attached to the scheduled job. **autoPauseThreshold** `string(int64)` If consecutive\_failure\_count reaches this threshold the job is auto-paused (state PAUSED, paused\_by\_subject "system\:auto-pause"). It is compared against consecutive\_failure\_count, NOT failure\_count. failure\_count is cumulative for the schedule's whole life, so a healthy schedule that collects scattered failures over months would eventually exceed any threshold and pause itself forever. A stored threshold of 0 disables auto-pause; otherwise the threshold is from 3 through 100. The public create request uses 0 or omission to select the default of 10, and the public update request uses 0 or omission to leave the current threshold unchanged. These public requests do not provide a disable control. Pattern: ^-?\d+$ **externalId** `string` Client-supplied external id. Echoed back when set; empty otherwise. Optional, immutable, unique within (tenant\_id, project\_id) among live schedules. Never starts with the reserved system-id prefix "sched\_". **createdAt** `string(date-time)` Time at which the scheduled job was created. **createdBySubject** `string` Subject identifier recorded when the schedule was created. **updatedAt** `string(date-time)` Time this record was most recently updated. **updatedBySubject** `string` Subject identifier recorded when the schedule was last updated. **pausedAt** `string(date-time)` Time at which the schedule was paused. **pausedBySubject** `string` Subject identifier recorded for the schedule pause. **pausedReason** `string` Explanation recorded for the schedule pause. **resumedAt** `string(date-time)` Time at which the schedule was most recently resumed. **resumedBySubject** `string` Subject identifier recorded for the schedule resume. **deletedAt** `string(date-time)` Time at which the schedule was deleted. **deletedBySubject** `string` Subject identifier recorded for the schedule deletion. **lastTriggeredAt** `string(date-time)` Time when the schedule was last triggered. Trigger and failure counters advance at most once per scheduled firing on its first attempt; retrying that firing does not inflate them. **nextTriggerAt** `string(date-time)` Time calculated for the next scheduled trigger. **triggerCount** `string(int64)` Scheduled times that ran, cumulative for the schedule's whole life. Pattern: ^-?\d+$ **failureCount** `string(int64)` Scheduled times whose first attempt failed, cumulative for the schedule's whole life. A firing that fails on attempt 1 and succeeds on retry still counts here — a failure was observed. This counter does NOT drive auto-pause. See consecutive\_failure\_count. Pattern: ^-?\d+$ **consecutiveFailureCount** `string(int64)` Current run of consecutive failed firings. This is the counter auto\_pause\_threshold is compared against. Incremented when a firing's first attempt fails; reset to 0 as soon as any attempt of any firing succeeds. So a firing that fails on attempt 1 and succeeds on retry has net zero effect here while still advancing failure\_count — the target recovered, so the run is over. A non-success terminal outcome counts as a failure, including a firing cancelled on a terminal 4xx. Pattern: ^-?\d+$ #### scheduled-jobs-resumeJob-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "scheduleId": "sched_a1b2c3d4e5f60718", "tenantId": "example_123", "projectId": "example_123", "ownerSubject": "example", "name": "example", "description": "example", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * *", "timezone": "example", "scheduledAt": "2026-09-16T12:00:00Z", "intervalSeconds": 1, "target": { "url": "https://example.com/callback", "method": "example", "kind": "example", "payload": { "example": "value" } }, "state": "SCHEDULE_STATUS_ACTIVE", "retryPolicy": { "maxAttempts": 1, "initialBackoffMs": 1, "maxBackoffMs": 1 }, "metadata": { "example": "value" }, "autoPauseThreshold": 1, "externalId": "example_123", "createdAt": "2026-09-16T12:00:00Z", "createdBySubject": "example", "updatedAt": "2026-09-16T12:00:00Z", "updatedBySubject": "example", "pausedAt": "2026-09-16T12:00:00Z", "pausedBySubject": "example", "pausedReason": "example", "resumedAt": "2026-09-16T12:00:00Z", "resumedBySubject": "example", "deletedAt": "2026-09-16T12:00:00Z", "deletedBySubject": "example", "lastTriggeredAt": "2026-09-16T12:00:00Z", "nextTriggerAt": "2026-09-16T12:00:00Z", "triggerCount": "1", "failureCount": "1", "consecutiveFailureCount": "1" } ``` Document ID: `DOC-CP-scheduling-api-resumeJob`. [Section identities and revisions](/documentation-manifest.json). - Resume a scheduled job: `DOC-CP-scheduling-api-resumeJob#overview` - Request: `DOC-CP-scheduling-api-resumeJob#request` - Responses: `DOC-CP-scheduling-api-resumeJob#responses` --- # Scheduler APIs URL: https://docs.travila.ai/api/scheduled-jobs Version: `aju17f20mq` Use the reference below for request and response fields and operation-specific requirements. # Overview \{#overview} Create and manage schedules that invoke HTTPS targets. A firing is a logical scheduled event and can have retry attempts. Target acceptance does not prove completion of the customer’s business operation. Follow the operation's scope: backend `sk_…` calls can carry an authorized `X-On-Behalf-Of` beneficiary, while client `pk_…` calls require the configured user's JWT. Owner-cleanup operations require a beneficiary; project teardown requires a subjectless backend request. The API also permits subjectless backend context. A console JWT belongs to a separate surface. See [Authentication](https://docs.travila.ai/core-platform/identity-access/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. Authenticate deliveries using the [receiver verification guide](https://docs.travila.ai/core-platform/scheduling/verifying). A valid token alone does not bind an arbitrary submitted body: verify the trusted schedule, payload and delivery identity before admitting work. Pause or deletion affects pending work and cannot undo effects already dispatched. Logout does not delete a user’s schedules. **Related guide:** [Scheduling](https://docs.travila.ai/core-platform/scheduling) ### JSON conventions \{#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](https://docs.travila.ai/api). ## Authentication \{#authentication} ## Job Lifecycle \{#reference-group-1} Create, manage, pause, resume, and delete scheduled jobs. See the [Scheduled Jobs guide](https://docs.travila.ai/core-platform/scheduling) for cron, one-shot, and recurring-interval patterns with retry and auto-pause. * [Create a scheduled job](/api/scheduled-jobs/create-job) * [Get a scheduled job](/api/scheduled-jobs/get-job) * [List scheduled jobs](/api/scheduled-jobs/list-jobs) * [Update a scheduled job](/api/scheduled-jobs/update-job) * [Pause a scheduled job](/api/scheduled-jobs/pause-job) * [Resume a scheduled job](/api/scheduled-jobs/resume-job) * [Delete a scheduled job](/api/scheduled-jobs/delete-job) * [Delete all scheduled jobs for a project](/api/scheduled-jobs/delete-jobs-for-project) * [Delete all scheduled jobs for the calling owner](/api/scheduled-jobs/delete-jobs-for-owner) ## Execution History \{#reference-group-2} Query execution records and delivery history. See the [Scheduled Jobs guide](https://docs.travila.ai/core-platform/scheduling) for status values, retry policy details, and response capture fields. * [List executions for a scheduled job](/api/scheduled-jobs/list-executions) ## Server 1 \{#reference-server-1} Travila API [https://api.travila.ai](https://api.travila.ai) ## X-API-Key \{#authentication-apiKeyAuth} API key for the configured deployment. Backend `sk_…` calls can use authorized on-behalf-of context; a client `pk_…` key requires the configured user's JWT. Owner operations and project teardown have different beneficiary requirements. Keep secret keys out of client apps. ## X-On-Behalf-Of \{#authentication-onBehalfOf} The end user this backend call acts for. An authorized `sk_…` request can omit this header where the operation permits a subjectless caller. In the current public integration, that caller can operate across owners in its authenticated tenant's `default` project. The key does not select an independently isolated project. Supplying this header requires `users:impersonate` and scopes ordinary reads and mutations to that user. `create-job` uses that beneficiary; a different `ownerSubject` is rejected. Without a beneficiary, creation requires `ownerSubject` in the request body. `delete-jobs-for-owner` requires a beneficiary. `delete-jobs-for-project` requires a subjectless backend request and removes schedules across owners in the current tenant/default-project scope. Check each operation before choosing the credential context. Keep secret keys on the backend. ## Authorization: Bearer \{#authentication-bearerAuth} 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

### apiKeyAuth Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-API-Key` ### onBehalfOf Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-On-Behalf-Of` ### bearerAuth Security scheme type: `http` HTTP authorization scheme: `bearer` ## Operations - [Create a scheduled job](/api/scheduled-jobs/create-job) — `POST /api/v1/scheduler/create-job` - [Get a scheduled job](/api/scheduled-jobs/get-job) — `POST /api/v1/scheduler/get-job` - [List scheduled jobs](/api/scheduled-jobs/list-jobs) — `POST /api/v1/scheduler/list-jobs` - [Update a scheduled job](/api/scheduled-jobs/update-job) — `POST /api/v1/scheduler/update-job` - [Pause a scheduled job](/api/scheduled-jobs/pause-job) — `POST /api/v1/scheduler/pause-job` - [Resume a scheduled job](/api/scheduled-jobs/resume-job) — `POST /api/v1/scheduler/resume-job` - [Delete a scheduled job](/api/scheduled-jobs/delete-job) — `POST /api/v1/scheduler/delete-job` - [Delete all scheduled jobs for a project](/api/scheduled-jobs/delete-jobs-for-project) — `POST /api/v1/scheduler/delete-jobs-for-project` - [Delete all scheduled jobs for the calling owner](/api/scheduled-jobs/delete-jobs-for-owner) — `POST /api/v1/scheduler/delete-jobs-for-owner` - [List executions for a scheduled job](/api/scheduled-jobs/list-executions) — `POST /api/v1/scheduler/list-executions` Document ID: `DOC-API-scheduled-jobs-overview`. [Section identities and revisions](/documentation-manifest.json). - Overview: `DOC-API-scheduled-jobs-overview#overview` - JSON conventions: `DOC-API-scheduled-jobs-overview#json-conventions` - Authentication: `DOC-API-scheduled-jobs-overview#authentication` - Job Lifecycle: `DOC-API-scheduled-jobs-overview#reference-group-1` - Execution History: `DOC-API-scheduled-jobs-overview#reference-group-2` - Server 1: `DOC-API-scheduled-jobs-overview#reference-server-1` - X-API-Key: `DOC-API-scheduled-jobs-overview#authentication-apiKeyAuth` - X-On-Behalf-Of: `DOC-API-scheduled-jobs-overview#authentication-onBehalfOf` - Authorization: Bearer: `DOC-API-scheduled-jobs-overview#authentication-bearerAuth` --- # Update a scheduled job URL: https://docs.travila.ai/api/scheduled-jobs/update-job **POST** `/api/v1/scheduler/update-job` Updates the provided schedule settings. Only included fields change; omitted fields remain unchanged. ### Timing changes The scheduler applies timing edits before returning by cancelling and reinserting the scheduled entry. This cannot undo an HTTP callback already dispatched or a business action your receiver has accepted. [`nextTriggerAt`](/api/models/schema-1ld0l8rmvg#response-field-nexttriggerat) on the returned job is the scheduling snapshot after the update; it can change as work advances. Do not infer wall-clock firing precision or business completion from that timestamp. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action. Use this in a guide: [Manage jobs](/core-platform/scheduling/managing) ## Authentication One of: - API Key via `X-API-Key` header parameter - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for updating a scheduled job and its trigger settings. ### Input constraints ### Record relationship Exactly one of schedule\_id or external\_id must be nonempty. Supplying neither or supplying both does not satisfy this condition. ### cron\_expression The cron\_expression may be empty text. Otherwise it must have one of two shapes. The first starts with @ followed by one or more ASCII letters, digits, or underscores; it may optionally continue with one separator character and then one or more characters other than line feed. The second has exactly five or six nonempty groups of non-separator characters, separated by one or more separator characters, with no leading or trailing separator. For this constraint, separator characters are ASCII space, horizontal tab, line feed, form feed, and carriage return. The shorthand tail may contain these characters except line feed after its first separator. ### interval\_seconds The interval\_seconds value must be zero, meaning no change for this update request, or at least 60 seconds. ### auto\_pause\_threshold The auto\_pause\_threshold value must be zero, or between 3 and 100 inclusive. **scheduleId** `string` Identifier of the scheduled job. **name** `string` Human-readable name assigned to the scheduled job. Maximum length: 256 **description** `string` Human-readable explanation of the scheduled job. **cronExpression** `string` Cron expression defining when the scheduled job runs. Maximum length: 128 Pattern: ^$|^@\w+(\s.+)?$|^\S+(\s+\S+){4,5}$ **timezone** `string` IANA time zone used by the scheduled job. **scheduledAt** `string(date-time)` Instant at which a one-time scheduled job should run. **intervalSeconds** `string(int64)` Interval between scheduled triggers, in seconds. Pattern: ^-?\d+$ **target** `any` Destination and invocation settings for the scheduled job. All of: Variant 1: ScheduleTarget describes the HTTP endpoint that receives each job invocation. Model reference: [ScheduleTarget](/api/models/schema-1lbkptb5rj#request). **url** `string(uri)` **required** Destination URL. Must be a valid absolute URI. Minimum length: 1 **method** `string` HTTP method to use. Defaults to "POST". **kind** `string` **required** Logical kind used for routing and observability (e.g., "notification", "llm\_conversation", "metering"). Required. Minimum length: 1 **payload** `map[string, any]` Arbitrary JSON payload forwarded verbatim to the target. **retryPolicy** `any` Attempt limits and backoff settings for the scheduled target. All of: Variant 1: RetryPolicy controls how failed executions are retried. Model reference: [RetryPolicy](/api/models/schema-1l9ki2op1i#request). **maxAttempts** `string(int64)` Maximum delivery attempts (including the initial attempt). Default 10. Pattern: ^-?\d+$ **initialBackoffMs** `string(int64)` Initial backoff before the first retry, in milliseconds. Default 5000. Pattern: ^-?\d+$ **maxBackoffMs** `string(int64)` Maximum backoff cap, in milliseconds. Default 1800000 (30 min). Pattern: ^-?\d+$ **metadata** `map[string, any]` Application-defined JSON metadata attached to the scheduled job. **autoPauseThreshold** `string(int64)` Consecutive failure threshold used to pause the scheduled job. Omission or zero leaves the existing threshold unchanged. A nonzero override must be from 3 through 100. This update request does not expose a value that disables auto-pause. Pattern: ^-?\d+$ **externalId** `string` Lookup reference only. Exactly one of schedule\_id / external\_id must be set. #### scheduled-jobs-updateJob-request Rename an existing job using its returned scheduleId. ```json { "scheduleId": "sched_a1b2c3d4e5f60718", "name": "Weekday morning digest" } ``` #### cookbook-core-platform-scheduling-managing-03-request Guide request for 2. Save a new delivery time. Replace example resource identifiers with your own authorized values. ```json { "scheduleId": "sched_a1b2c3d4e5f60718", "cronExpression": "0 10 * * 1-5" } ``` ## Responses ### 200 — Scheduled job updated Content type: `application/json` UpdateJob keeps a dedicated response wrapper (rather than the bare Schedule the other mutations return) because it carries response-only metadata that is not part of the persisted resource. **schedule** `any` Scheduled job returned by the operation. All of: Variant 1: Schedule is the canonical representation of a scheduled job. Creating any schedule type returns the `Schedule` resource directly, with the same shape used by get, pause and resume operations. [`triggerCount`](/api/models/schema-1ld0l8rmvg#response-field-triggercount): Cumulative firings. [`failureCount`](/api/models/schema-1ld0l8rmvg#response-field-failurecount): Cumulative failed first attempts; a later successful retry does not erase the earlier failure. [`consecutiveFailureCount`](/api/models/schema-1ld0l8rmvg#response-field-consecutivefailurecount): Current sequence of failed firings; a successful attempt resets it. This counter drives auto-pause. Zero-valued counters can be omitted. Nonzero 64-bit counters are decimal JSON strings; preserve their integer precision. Model reference: [Schedule](/api/models/schema-1ld0l8rmvg#response). **scheduleId** `string` Server-assigned identifier of the scheduled job, prefixed with "sched\_". **tenantId** `string` Identifier of the tenant that owns or scopes this record. **projectId** `string` Identifier of the project within the tenant that scopes this record. **ownerSubject** `string` Subject identifier of the owning user or service account. **name** `string` Human-readable name assigned to the scheduled job. **description** `string` Human-readable explanation of the scheduled job. **scheduleType** `any` Schedule type and expression. Expression format that determines when a scheduled job fires.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCHEDULE_TYPE_CRON` | 0 | Canonical | Fire according to the configured cron expression and timezone. For example, `0 9 * * 1-5` selects 09:00 on weekdays in that timezone. | | `SCHEDULE_TYPE_ONCE` | 1 | Canonical | Fire once at the configured scheduled timestamp. | | `SCHEDULE_TYPE_RECURRING_INTERVAL` | 2 | Canonical | Fire repeatedly at the configured interval in seconds. |
Exactly one of: Variant 1: Type: `string` Enum: `SCHEDULE_TYPE_CRON`, `SCHEDULE_TYPE_ONCE`, `SCHEDULE_TYPE_RECURRING_INTERVAL` Variant 2: Type: `integer(int32)` **cronExpression** `string` Cron expression. Populated when schedule\_type is SCHEDULE\_TYPE\_CRON. **timezone** `string` IANA timezone for cron evaluation. Default "UTC". **scheduledAt** `string(date-time)` Exact fire time. Populated when schedule\_type is SCHEDULE\_TYPE\_ONCE. **intervalSeconds** `string(int64)` Interval between firings in seconds. Populated when schedule\_type is SCHEDULE\_TYPE\_RECURRING\_INTERVAL. Pattern: ^-?\d+$ **target** `any` Destination and invocation settings for the scheduled job. All of: Variant 1: ScheduleTarget describes the HTTP endpoint that receives each job invocation. Model reference: [ScheduleTarget](/api/models/schema-1lbkptb5rj#response). **url** `string` Destination URL. Must be a valid absolute URI. **method** `string` HTTP method to use. Defaults to "POST". **kind** `string` Logical kind used for routing and observability (e.g., "notification", "llm\_conversation", "metering"). Required. **payload** `map[string, any]` Arbitrary JSON payload forwarded verbatim to the target. **state** `any` Lifecycle status controlling whether the scheduled job can trigger. Lifecycle condition that determines whether a scheduled job may trigger: active, paused, or deleted. This is separate from the outcome of an individual scheduled-job execution.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCHEDULE_STATUS_ACTIVE` | 0 | Canonical | The schedule is active and can trigger at its next matching time. | | `SCHEDULE_STATUS_PAUSED` | 1 | Canonical | The schedule is paused and does not trigger until resumed. | | `SCHEDULE_STATUS_DELETED` | 2 | Canonical | The schedule has been deleted; this is a schedule condition, not an execution outcome. |
Exactly one of: Variant 1: Type: `string` Enum: `SCHEDULE_STATUS_ACTIVE`, `SCHEDULE_STATUS_PAUSED`, `SCHEDULE_STATUS_DELETED` Variant 2: Type: `integer(int32)` **retryPolicy** `any` Attempt limits and backoff settings for the scheduled target. All of: Variant 1: RetryPolicy controls how failed executions are retried. Model reference: [RetryPolicy](/api/models/schema-1l9ki2op1i#response). **maxAttempts** `string(int64)` Maximum delivery attempts (including the initial attempt). Default 10. Pattern: ^-?\d+$ **initialBackoffMs** `string(int64)` Initial backoff before the first retry, in milliseconds. Default 5000. Pattern: ^-?\d+$ **maxBackoffMs** `string(int64)` Maximum backoff cap, in milliseconds. Default 1800000 (30 min). Pattern: ^-?\d+$ **metadata** `map[string, any]` Application-defined JSON metadata attached to the scheduled job. **autoPauseThreshold** `string(int64)` If consecutive\_failure\_count reaches this threshold the job is auto-paused (state PAUSED, paused\_by\_subject "system\:auto-pause"). It is compared against consecutive\_failure\_count, NOT failure\_count. failure\_count is cumulative for the schedule's whole life, so a healthy schedule that collects scattered failures over months would eventually exceed any threshold and pause itself forever. A stored threshold of 0 disables auto-pause; otherwise the threshold is from 3 through 100. The public create request uses 0 or omission to select the default of 10, and the public update request uses 0 or omission to leave the current threshold unchanged. These public requests do not provide a disable control. Pattern: ^-?\d+$ **externalId** `string` Client-supplied external id. Echoed back when set; empty otherwise. Optional, immutable, unique within (tenant\_id, project\_id) among live schedules. Never starts with the reserved system-id prefix "sched\_". **createdAt** `string(date-time)` Time at which the scheduled job was created. **createdBySubject** `string` Subject identifier recorded when the schedule was created. **updatedAt** `string(date-time)` Time this record was most recently updated. **updatedBySubject** `string` Subject identifier recorded when the schedule was last updated. **pausedAt** `string(date-time)` Time at which the schedule was paused. **pausedBySubject** `string` Subject identifier recorded for the schedule pause. **pausedReason** `string` Explanation recorded for the schedule pause. **resumedAt** `string(date-time)` Time at which the schedule was most recently resumed. **resumedBySubject** `string` Subject identifier recorded for the schedule resume. **deletedAt** `string(date-time)` Time at which the schedule was deleted. **deletedBySubject** `string` Subject identifier recorded for the schedule deletion. **lastTriggeredAt** `string(date-time)` Time when the schedule was last triggered. Trigger and failure counters advance at most once per scheduled firing on its first attempt; retrying that firing does not inflate them. **nextTriggerAt** `string(date-time)` Time calculated for the next scheduled trigger. **triggerCount** `string(int64)` Scheduled times that ran, cumulative for the schedule's whole life. Pattern: ^-?\d+$ **failureCount** `string(int64)` Scheduled times whose first attempt failed, cumulative for the schedule's whole life. A firing that fails on attempt 1 and succeeds on retry still counts here — a failure was observed. This counter does NOT drive auto-pause. See consecutive\_failure\_count. Pattern: ^-?\d+$ **consecutiveFailureCount** `string(int64)` Current run of consecutive failed firings. This is the counter auto\_pause\_threshold is compared against. Incremented when a firing's first attempt fails; reset to 0 as soon as any attempt of any firing succeeds. So a firing that fails on attempt 1 and succeeds on retry has net zero effect here while still advancing failure\_count — the target recovered, so the run is over. A non-success terminal outcome counts as a failure, including a firing cancelled on a terminal 4xx. Pattern: ^-?\d+$ **effectiveAt** `string` When the update takes effect. Current updates return immediate; next\_resync and next\_worker\_deployment are not emitted. The returned schedule’s next\_trigger\_at identifies its next firing. #### scheduled-jobs-updateJob-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "schedule": { "scheduleId": "sched_a1b2c3d4e5f60718", "tenantId": "example_123", "projectId": "example_123", "ownerSubject": "example", "name": "example", "description": "example", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * *", "timezone": "example", "scheduledAt": "2026-09-16T12:00:00Z", "intervalSeconds": 1, "target": { "url": "https://example.com/callback", "method": "example", "kind": "example" }, "state": "SCHEDULE_STATUS_ACTIVE", "retryPolicy": { "maxAttempts": 1, "initialBackoffMs": 1, "maxBackoffMs": 1 }, "metadata": { "example": "value" }, "autoPauseThreshold": 1, "externalId": "example_123", "createdAt": "2026-09-16T12:00:00Z", "createdBySubject": "example", "updatedAt": "2026-09-16T12:00:00Z", "updatedBySubject": "example", "pausedAt": "2026-09-16T12:00:00Z", "pausedBySubject": "example", "pausedReason": "example", "resumedAt": "2026-09-16T12:00:00Z", "resumedBySubject": "example", "deletedAt": "2026-09-16T12:00:00Z", "deletedBySubject": "example", "lastTriggeredAt": "2026-09-16T12:00:00Z", "nextTriggerAt": "2026-09-16T12:00:00Z", "triggerCount": "1", "failureCount": "1", "consecutiveFailureCount": "1" }, "effectiveAt": "example" } ``` Document ID: `DOC-CP-scheduling-api-updateJob`. [Section identities and revisions](/documentation-manifest.json). - Update a scheduled job: `DOC-CP-scheduling-api-updateJob#overview` - Request: `DOC-CP-scheduling-api-updateJob#request` - Responses: `DOC-CP-scheduling-api-updateJob#responses` --- # Delete a secret URL: https://docs.travila.ai/api/secrets/delete-secret **POST** `/api/v1/secrets/delete` Deletes the stored value before its metadata. An absent secret is an idempotent success with `deleted` false, which may be omitted. A failure does not prove the previous value remains intact. Known custom MCP references block deletion with 409 unless `force` is used. Detach or rebind those consumers first where possible. The reference list covers tracked custom servers, not every possible external consumer. Forced deletion can break future credential resolution; it does not recall cached or already dispatched use, revoke the credential at its issuer, or attest to backup erasure. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized tenant project secret administration. Use this in a guide: [Connect a private tool without putting its credential in prompts](/core-platform/secrets) · [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers) · [Secret values and credential references](/api/secrets/credentials) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Selects a project secret to delete and whether to override reference checks. ### Input constraints ### name The name must contain one through 63 characters. Its first character must be a lowercase ASCII letter or digit. Every remaining character must be a lowercase ASCII letter, digit, period, underscore, or hyphen. **name** `string` **required** Name identifying the secret within its project. Pattern: ^[a-z0-9][a-z0-9._-]{0,62}$ **force** `boolean` Delete even when custom MCP servers still reference this secret. Those servers then fail closed the next time they try to resolve it. #### secrets-deleteSecret-request Use the name of an existing secret in the authenticated project. ```json { "name": "travel-provider-api-key" } ``` ## Responses ### 200 — Delete processed Content type: `application/json` Result of deleting a project secret. **deleted** `boolean` False when the secret did not exist; the call still succeeds. #### secrets-deleteSecret-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "deleted": true } ``` Document ID: `DOC-CP-secrets-api-deleteSecret`. [Section identities and revisions](/documentation-manifest.json). - Delete a secret: `DOC-CP-secrets-api-deleteSecret#overview` - Request: `DOC-CP-secrets-api-deleteSecret#request` - Responses: `DOC-CP-secrets-api-deleteSecret#responses` --- # Get a secret's metadata URL: https://docs.travila.ai/api/secrets/get-secret-metadata **POST** `/api/v1/secrets/get-metadata` Returns the secret’s metadata without exposing the credential. Unknown names return 404. The metadata revision records that row; after a partially failed write it is not independent proof of the actual stored credential version. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized tenant project secret administration. Use this in a guide: [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers) · [Secret values and credential references](/api/secrets/credentials) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Selects a project secret whose metadata is returned without its value. ### Input constraints ### name The name must contain one through 63 characters. Its first character must be a lowercase ASCII letter or digit. Every remaining character must be a lowercase ASCII letter, digit, period, underscore, or hyphen. **name** `string` **required** Name identifying the secret within its project. Pattern: ^[a-z0-9][a-z0-9._-]{0,62}$ #### secrets-getSecretMetadata-request Use the name of an existing secret in the authenticated project. ```json { "name": "travel-provider-api-key" } ``` ## Responses ### 200 — Metadata returned Content type: `application/json` Result of retrieving metadata for a project secret without its secret value. **metadata** `any` Stored secret metadata; the secret value is not returned. All of: Variant 1: Metadata returned by secret read operations. Secret values are not included. Model reference: [SecretMetadata](/api/models/schema-1lhjc44i8n#response). **name** `string` Name identifying the secret within its project. **projectId** `string` Identifier of the project within the tenant that scopes this secret. `default` identifies the default project. **description** `string` Human-readable explanation of the secret. **labels** `map[string, string]` Free-form labels used to organize and identify secrets. Free-form, e.g. \{"kind": "mcp-auth"}. **version** `string(int64)` Version number of the stored secret metadata. Increments on every PutSecret. Pattern: ^-?\d+$ **createdBy** `string` Subject identifier recorded for the creator of this record. Subject from the X-User-ID header, when present. **createdAt** `string(date-time)` Time this record was created. **updatedAt** `string(date-time)` Time this record was most recently updated. #### secrets-getSecretMetadata-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "metadata": { "name": "example", "projectId": "example_123", "description": "example", "labels": {}, "version": "1", "createdBy": "example", "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z" } } ``` Document ID: `DOC-CP-secrets-api-getSecretMetadata`. [Section identities and revisions](/documentation-manifest.json). - Get a secret's metadata: `DOC-CP-secrets-api-getSecretMetadata#overview` - Request: `DOC-CP-secrets-api-getSecretMetadata#request` - Responses: `DOC-CP-secrets-api-getSecretMetadata#responses` --- # List secrets URL: https://docs.travila.ai/api/secrets/list-secrets **POST** `/api/v1/secrets/list` Returns metadata for every secret in the project, paginated. Values are not included, and there is no parameter that would include them. Send `{}` for the first page at the server's default size. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized tenant project secret administration. Use this in a guide: [Secret values and credential references](/api/secrets/credentials) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Pagination settings for listing secret metadata within the current project. **page** `string(int64)` Page number requested from the backing service. Pattern: ^-?\d+$ **pageSize** `string(int64)` Number of secret metadata entries requested per page. Zero or omission lets the server choose the page size. Pattern: ^-?\d+$ #### secrets-listSecrets-request List the first page of secret metadata for the authenticated project. ```json { "page": 0, "pageSize": 20 } ``` ## Responses ### 200 — Page of secret metadata Content type: `application/json` Page of metadata for project secrets, without their values. **secrets** `array[platform_v1_services_secretmanager_v1_SecretMetadata]` Secret metadata records returned by the listing; secret values are excluded. Metadata returned by secret read operations. Secret values are not included. Model reference: [SecretMetadata](/api/models/schema-1lhjc44i8n#response). **name** `string` Name identifying the secret within its project. **projectId** `string` Identifier of the project within the tenant that scopes this secret. `default` identifies the default project. **description** `string` Human-readable explanation of the secret. **labels** `map[string, string]` Free-form labels used to organize and identify secrets. Free-form, e.g. \{"kind": "mcp-auth"}. **version** `string(int64)` Version number of the stored secret metadata. Increments on every PutSecret. Pattern: ^-?\d+$ **createdBy** `string` Subject identifier recorded for the creator of this record. Subject from the X-User-ID header, when present. **createdAt** `string(date-time)` Time this record was created. **updatedAt** `string(date-time)` Time this record was most recently updated. **total** `string(int64)` Total number of records reported for this listing. Pattern: ^-?\d+$ #### secrets-listSecrets-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "secrets": [ { "name": "example", "projectId": "example_123", "description": "example", "labels": {}, "version": "1", "createdBy": "example", "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z" } ], "total": 1 } ``` Document ID: `DOC-CP-secrets-api-listSecrets`. [Section identities and revisions](/documentation-manifest.json). - List secrets: `DOC-CP-secrets-api-listSecrets#overview` - Request: `DOC-CP-secrets-api-listSecrets#request` - Responses: `DOC-CP-secrets-api-listSecrets#responses` --- # Create or update a secret URL: https://docs.travila.ai/api/secrets/put-secret **POST** `/api/v1/secrets/put` Writes or replaces a value under `name`; this upsert also rotates the stored credential. The response contains metadata only, and no public read endpoint returns the value. Name-based bindings remain the same, but consumers can retain prior values in caches or in-flight work; this is not upstream credential revocation. Value storage and metadata updates are separate steps. On an error, metadata alone cannot confirm which value is current. Stop using the affected binding and contact your Travila operator before retrying. The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized tenant project secret administration. Use this in a guide: [Connect a private tool without putting its credential in prompts](/core-platform/secrets) · [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers) · [Secret values and credential references](/api/secrets/credentials) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for writing a project secret and its metadata. ### Input constraints ### name The name must contain one through 63 characters. Its first character must be a lowercase ASCII letter or digit. Every remaining character must be a lowercase ASCII letter, digit, period, underscore, or hyphen. **name** `string` **required** Name identifying the secret within its project. Pattern: ^[a-z0-9][a-z0-9._-]{0,62}$ **value** `string` **required** Secret value, limited to 64 KiB of UTF-8 bytes. Binary material is supplied as base64 by caller convention. Read operations return metadata without the secret value. Minimum length: 1 **description** `string` Human-readable explanation of the secret. Maximum length: 1024 **labels** `map[string, string]` Free-form labels used to organize and identify secrets. #### secrets-putSecret-request Store an example-named provider credential; replace the placeholder with the value to store. ```json { "name": "travel-provider-api-key", "value": "replace-with-provider-api-key", "description": "API key for the travel provider" } ``` #### cookbook-integrations-tools-connections-custom-mcp-servers-01-request Guide request for 1. Store the Firecrawl credential. Replace example resource identifiers with your own authorized values. ```json { "name": "firecrawl-api-key", "value": "fc-your-token-here", "description": "Firecrawl bearer token", "labels": { "kind": "mcp-auth" } } ``` #### cookbook-integrations-tools-connections-custom-mcp-servers-06-request Guide request for Rotate the credential. Replace example resource identifiers with your own authorized values. ```json { "name": "firecrawl-api-key", "value": "fc-the-new-token" } ``` ## Responses ### 200 — Secret written; metadata only Content type: `application/json` Stored metadata returned after writing a project secret; the secret value is not returned. **metadata** `any` Stored secret metadata; the secret value is not returned. All of: Variant 1: Metadata returned by secret read operations. Secret values are not included. Model reference: [SecretMetadata](/api/models/schema-1lhjc44i8n#response). **name** `string` Name identifying the secret within its project. **projectId** `string` Identifier of the project within the tenant that scopes this secret. `default` identifies the default project. **description** `string` Human-readable explanation of the secret. **labels** `map[string, string]` Free-form labels used to organize and identify secrets. Free-form, e.g. \{"kind": "mcp-auth"}. **version** `string(int64)` Version number of the stored secret metadata. Increments on every PutSecret. Pattern: ^-?\d+$ **createdBy** `string` Subject identifier recorded for the creator of this record. Subject from the X-User-ID header, when present. **createdAt** `string(date-time)` Time this record was created. **updatedAt** `string(date-time)` Time this record was most recently updated. #### secrets-putSecret-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "metadata": { "name": "example", "projectId": "example_123", "description": "example", "labels": {}, "version": "1", "createdBy": "example", "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z" } } ``` Document ID: `DOC-CP-secrets-api-putSecret`. [Section identities and revisions](/documentation-manifest.json). - Create or update a secret: `DOC-CP-secrets-api-putSecret#overview` - Request: `DOC-CP-secrets-api-putSecret#request` - Responses: `DOC-CP-secrets-api-putSecret#responses` --- # Project Secret APIs URL: https://docs.travila.ai/api/secrets Version: `aju17f20mq` Use the reference below for request and response fields and operation-specific requirements. # Overview \{#overview} Write credentials and inspect their metadata and known references. There is no public endpoint to retrieve a stored secret value. Backend consumers resolve bindings when they use a credential. ## Authentication \{#authentication} Use an authorized backend `sk_…` key in `X-API-Key`; these configuration operations do not need an end-user identity. A console JWT belongs to the separate console surface. See [Authentication](https://docs.travila.ai/core-platform/identity-access/authentication). ## Scoping \{#scoping} 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. ## Rotation \{#rotation} This API lacks complete per-action secret permissions. Restrict access to the key-management and secrets-management surfaces. Public write-only behavior does not prove that values are absent from internal storage, journals or diagnostics. A failed write can leave the credential and its metadata inconsistent. Stop using the affected binding and ask your Travila operator to resolve its state before retrying; metadata alone cannot confirm which value is stored. **Related guide:** [Store and rotate credentials](https://docs.travila.ai/core-platform/secrets) ### JSON conventions \{#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](https://docs.travila.ai/api). ## Secrets \{#reference-group-1} Write, inspect, list, and delete project secrets. * [Create or update a secret](/api/secrets/put-secret) * [Get a secret's metadata](/api/secrets/get-secret-metadata) * [List secrets](/api/secrets/list-secrets) * [Delete a secret](/api/secrets/delete-secret) ## Server 1 \{#reference-server-1} Travila API [https://api.travila.ai](https://api.travila.ai) ## X-API-Key \{#authentication-apiKeyAuth} Authorized tenant backend secret key (`sk_…`). No end-user identity is needed for these tenant/project configuration operations. Keep the key out of client apps; authorization and provisioning still apply.

Authentication credentials

### apiKeyAuth Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-API-Key` ### onBehalfOf Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-On-Behalf-Of` ### bearerAuth Security scheme type: `http` HTTP authorization scheme: `bearer` ## Operations - [Create or update a secret](/api/secrets/put-secret) — `POST /api/v1/secrets/put` - [Get a secret's metadata](/api/secrets/get-secret-metadata) — `POST /api/v1/secrets/get-metadata` - [List secrets](/api/secrets/list-secrets) — `POST /api/v1/secrets/list` - [Delete a secret](/api/secrets/delete-secret) — `POST /api/v1/secrets/delete` Document ID: `DOC-API-secrets-overview`. [Section identities and revisions](/documentation-manifest.json). - Overview: `DOC-API-secrets-overview#overview` - Authentication: `DOC-API-secrets-overview#authentication` - Scoping: `DOC-API-secrets-overview#scoping` - Rotation: `DOC-API-secrets-overview#rotation` - JSON conventions: `DOC-API-secrets-overview#json-conventions` - Secrets: `DOC-API-secrets-overview#reference-group-1` - Server 1: `DOC-API-secrets-overview#reference-server-1` - X-API-Key: `DOC-API-secrets-overview#authentication-apiKeyAuth` --- # Generate pre-signed download URLs for multiple files URL: https://docs.travila.ai/api/storage/batch-generate-download-urls **POST** `/api/v1/storage/batch-generate-download-urls` Generates download URLs in a batch. Inspect each result’s `success === true` and match by fileId; order is not guaranteed. Per-file errors can be returned independently, but malformed requests, authentication and request-level backend failures can still fail the whole call. URLs remain sensitive bearer credentials. The following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing. Use this in a guide: [Add file attachments to a support request](/core-platform/files-data/files) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for issuing signed download URLs for a collection of files. **fileIds** `array[string]` **required** File IDs to resolve (1-50 per batch). Minimum items: 1 Maximum items: 50 Type: `string` **expiresSeconds** `string(int64)` Requested lifetime of the signed URL, in seconds. Pattern: ^-?\d+$ #### storage-batchGenerateDownloadUrls-request Resolve existing file IDs together; inspect each result separately. ```json { "fileIds": [ "0123456789abcdef0123456789abcdef" ], "expiresSeconds": 900 } ``` #### cookbook-core-platform-files-data-files-05-request Guide request for Show several attachments on the case. Replace example resource identifiers with your own authorized values. ```json { "fileIds": [ "a1b2c3d4e5f60718293a4b5c6d7e8f90", "b2c3d4e5f60718293a4b5c6d7e8f901a" ], "expiresSeconds": 3600 } ``` ## Responses ### 200 — Per-file download URL results returned Content type: `application/json` Result payload for issuing signed download URLs for a collection of files. **results** `array[storage_v1_services_gateway_v1_FileUrlResult]` Signed download URL or item-specific error for each requested file. Signed download URL or item-specific error for one requested file. Model reference: [FileUrlResult](/api/models/schema-oq46sv4kha#response). **fileId** `string` Stable identifier of the stored file. **url** `string` Signed download URL for the requested file. **success** `boolean` Whether the operation reports a successful result. **error** `string` Error information reported for this operation or item. **contentType** `string` MIME type (e.g. "image/jpeg"); lets consumers pick the right content-part shape (IMAGE\_URL vs FILE\_URL). Empty when success = false or unknown. #### storage-batchGenerateDownloadUrls-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "results": [ { "fileId": "example_123", "url": "https://example.com/resource", "success": true, "error": "example", "contentType": "Example text" } ] } ``` #### cookbook-core-platform-files-data-files-json-04-response Illustrative response for Show several attachments on the case. Replace example resource identifiers with your own authorized values. ```json { "results": [ { "fileId": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "url": "https://storage.googleapis.com/bucket/...", "success": true, "contentType": "video/mp4" }, { "fileId": "b2c3d4e5f60718293a4b5c6d7e8f901a", "error": "file not found" } ] } ``` Document ID: `DOC-CP-files-data-api-batchGenerateDownloadUrls`. [Section identities and revisions](/documentation-manifest.json). - Generate pre-signed download URLs for multiple files: `DOC-CP-files-data-api-batchGenerateDownloadUrls#overview` - Request: `DOC-CP-files-data-api-batchGenerateDownloadUrls#request` - Responses: `DOC-CP-files-data-api-batchGenerateDownloadUrls#responses` --- # Create a new folder URL: https://docs.travila.ai/api/storage/create-folder **POST** `/api/v1/storage/create-folder` Creates the requested folder entry at the specified path. It does not create intermediate parent entries; create those explicitly when needed. The following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing. Use this in a guide: [Organize a customer’s project documents](/core-platform/files-data/folders) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for creating a folder entry in the user’s storage namespace. **folderPath** `string` Path of the folder within the user’s storage namespace. **metadata** `map[string, string]` Additional attributes associated with the resource. #### storage-createFolder-request Create a reports folder in the authenticated user’s storage namespace. ```json { "folderPath": "reports" } ``` #### cookbook-core-platform-files-data-folders-01-request Guide request for Prepare a folder and add the first document. Replace example resource identifiers with your own authorized values. ```json { "folderPath": "/documents/work" } ``` ## Responses ### 200 — Folder created (or already existed) Content type: `application/json` Result payload for creating a folder entry in the user’s storage namespace. **folder** `any` Metadata for the folder affected by the operation. All of: Variant 1: FolderInfo contains metadata about a folder Model reference: [FolderInfo](/api/models/schema-opsbitjge1#response). **folderId** `string` Unique folder ID. **name** `string` Name of the folder within its parent folder. Folder name **path** `string` Full path (e.g., "/documents/work"). **parentPath** `string` Parent folder path. **createdAt** `string` RFC3339 timestamp. **modifiedAt** `string` RFC3339 timestamp. **metadata** `map[string, string]` Custom metadata. **fileCount** `string(int64)` Number of files (direct children). Pattern: ^-?\d+$ **subfolderCount** `string(int64)` Number of subfolders. Pattern: ^-?\d+$ **totalSizeBytes** `string(int64)` Total size of all files in folder (recursive). Pattern: ^-?\d+$ **created** `boolean` Whether this operation created a new folder. #### storage-createFolder-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "folder": { "folderId": "example_123", "name": "example", "path": "documents/example.txt", "parentPath": "documents/example.txt", "createdAt": "example", "modifiedAt": "example", "metadata": {}, "fileCount": 1, "subfolderCount": 1, "totalSizeBytes": "1" }, "created": true } ``` Document ID: `DOC-CP-files-data-api-createFolder`. [Section identities and revisions](/documentation-manifest.json). - Create a new folder: `DOC-CP-files-data-api-createFolder#overview` - Request: `DOC-CP-files-data-api-createFolder#request` - Responses: `DOC-CP-files-data-api-createFolder#responses` --- # Delete a file URL: https://docs.travila.ai/api/storage/delete-file **POST** `/api/v1/storage/delete-file` Deletes the stored object and tracked file metadata, releasing tracked quota on successful completion. This does not prove removal from backups, invalidate every copied URL immediately, or undo a download already in flight. Reconcile partial failures. The following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing. Use this in a guide: [Build a searchable document library](/core-platform/files-data/managing) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for removing a stored file and its tracked metadata. **fileId** `string` Stable identifier of the stored file. #### storage-deleteFile-request Replace fileId with an existing file returned by upload or listing. ```json { "fileId": "0123456789abcdef0123456789abcdef" } ``` #### cookbook-core-platform-files-data-managing-06-request Guide request for Delete a document the customer no longer needs. Replace example resource identifiers with your own authorized values. ```json { "fileId": "a1b2c3d4e5f60718293a4b5c6d7e8f90" } ``` ## Responses ### 200 — File deleted Content type: `application/json` Result payload for removing a stored file and its tracked metadata. **deleted** `boolean` Whether the deletion operation reports the resource removed. **spaceFreedBytes** `string(int64)` Storage capacity reported freed by deletion, in bytes. Pattern: ^-?\d+$ #### storage-deleteFile-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "deleted": true, "spaceFreedBytes": "1" } ``` Document ID: `DOC-CP-files-data-api-deleteFile`. [Section identities and revisions](/documentation-manifest.json). - Delete a file: `DOC-CP-files-data-api-deleteFile#overview` - Request: `DOC-CP-files-data-api-deleteFile#request` - Responses: `DOC-CP-files-data-api-deleteFile#responses` --- # Delete a folder URL: https://docs.travila.ai/api/storage/delete-folder **POST** `/api/v1/storage/delete-folder` Deletes the selected folder entry and reports deletion counts on success. With `recursive` false or omitted, the operation leaves descendants in place and does not require an empty folder. This option cannot safely test whether the project still contains documents. With `recursive: true`, it also attempts descendant file and folder deletion. A failure can follow earlier object deletions, so inspect the resulting state before recovery. The following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing. Use this in a guide: [Organize a customer’s project documents](/core-platform/files-data/folders) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for removing a folder entry and optionally its descendant content. **folderPath** `string` Path of the folder within the user’s storage namespace. **recursive** `boolean` Whether the operation includes descendant folders and their contents. #### storage-deleteFolder-request Delete the selected empty folder; recursive deletion is not requested. ```json { "folderPath": "reports", "recursive": false } ``` #### cookbook-core-platform-files-data-folders-02-request Guide request for Remove the project’s documents when the customer chooses. Replace example resource identifiers with your own authorized values. ```json { "folderPath": "/documents/work", "recursive": true } ``` ## Responses ### 200 — Folder deleted Content type: `application/json` Result payload for removing a folder entry and optionally its descendant content. **deleted** `boolean` Whether the deletion operation reports the resource removed. **filesDeleted** `string(int64)` Number of files reported deleted by the operation. Pattern: ^-?\d+$ **foldersDeleted** `string(int64)` Number of folders reported deleted by the operation. Pattern: ^-?\d+$ #### storage-deleteFolder-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "deleted": true, "filesDeleted": 1, "foldersDeleted": 1 } ``` Document ID: `DOC-CP-files-data-api-deleteFolder`. [Section identities and revisions](/documentation-manifest.json). - Delete a folder: `DOC-CP-files-data-api-deleteFolder#overview` - Request: `DOC-CP-files-data-api-deleteFolder#request` - Responses: `DOC-CP-files-data-api-deleteFolder#responses` --- # Generate a pre-signed download URL URL: https://docs.travila.ai/api/storage/generate-download-url **POST** `/api/v1/storage/generate-download-url` Generates a time-limited pre-signed URL for downloading a file directly from the storage backend. The following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing. Use this in a guide: [Add file attachments to a support request](/core-platform/files-data/files) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for issuing a signed URL for downloading a stored file. **fileId** `string` Stable file ID to resolve to a signed URL. **expiresSeconds** `string(int64)` Requested lifetime of the signed URL, in seconds. Pattern: ^-?\d+$ **responseContentDisposition** `string` Content-Disposition override requested for the signed download response. Use attachment with a filename to request a download under that name. #### storage-generateDownloadUrl-request Request a short-lived download URL for an existing file. ```json { "fileId": "0123456789abcdef0123456789abcdef", "expiresSeconds": 900 } ``` #### cookbook-core-platform-files-data-files-04-request Guide request for Let the customer reopen the attachment. Replace example resource identifiers with your own authorized values. ```json { "fileId": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "expiresSeconds": 3600 } ``` #### cookbook-core-platform-files-data-files-json-03-request Guide request for Let the customer reopen the attachment. Replace example resource identifiers with your own authorized values. ```json { "fileId": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "responseContentDisposition": "attachment; filename=my-video.mp4" } ``` ## Responses ### 200 — Download URL generated Content type: `application/json` Result payload for issuing a signed URL for downloading a stored file. **url** `string` URL associated with the resource or outbound request. **file** `any` Metadata for the file affected or retrieved by the operation. All of: Variant 1: FileInfo contains metadata about a file Model reference: [FileInfo](/api/models/schema-1lls6fo8p7#response). **fileId** `string` Stable identifier of the stored file. **name** `string` Name of the file within its containing folder. **path** `string` Full path (e.g., "/documents/report.pdf"). **folderPath** `string` Parent folder path. **sizeBytes** `string(int64)` Size of the file content, in bytes. Pattern: ^-?\d+$ **contentType** `string` Media type of the file content. **uploadedAt** `string` RFC3339 timestamp. **modifiedAt** `string` RFC3339 timestamp. **metadata** `map[string, string]` Custom metadata. **tags** `array[string]` User-defined tags. Type: `string` **description** `string` Optional description. **storageRef** `any` Reference to actual storage location. All of: Variant 1: ObjectRef references an object in storage Model reference: [ObjectRef](/api/models/schema-1lj1ellabu#response). **bucket** `string` Storage bucket containing the object. **key** `string` Object key within the selected storage bucket. **provider** `any` Storage provider used to access the object. Backend that stores the file bytes associated with a storage record.
| Value | No. | Form | Meaning | |---|---|---|---| | `STORAGE_PROVIDER_GCS` | 0 | Canonical | Google Cloud Storage. | | `STORAGE_PROVIDER_S3` | 1 | Canonical | See meaning below. | | `STORAGE_PROVIDER_FILESYSTEM` | 2 | Canonical | See meaning below. | | `STORAGE_PROVIDER_AZURE_BLOB` | 3 | Canonical | Azure Blob Storage. | **`STORAGE_PROVIDER_S3`** Amazon S3 or a storage service implementing the S3 interface. Amazon S3 (and compatibles) **`STORAGE_PROVIDER_FILESYSTEM`** A filesystem accessible to the storage service. Local filesystem
Exactly one of: Variant 1: Type: `string` Enum: `STORAGE_PROVIDER_GCS`, `STORAGE_PROVIDER_S3`, `STORAGE_PROVIDER_FILESYSTEM`, `STORAGE_PROVIDER_AZURE_BLOB` Variant 2: Type: `integer(int32)` **checksum** `string` File checksum (SHA256). **version** `string(int64)` Version number (for versioning support). Pattern: ^-?\d+$ #### storage-generateDownloadUrl-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "url": "https://example.com/resource", "file": { "fileId": "example_123", "name": "example", "path": "documents/example.txt", "folderPath": "documents/example.txt", "sizeBytes": "1", "contentType": "Example text", "uploadedAt": "example", "modifiedAt": "example", "metadata": {}, "tags": [ "example" ], "description": "example", "storageRef": { "bucket": "example", "key": "example_123", "provider": "STORAGE_PROVIDER_GCS" }, "checksum": "example", "version": 1 } } ``` #### cookbook-core-platform-files-data-files-json-02-response Illustrative response for Let the customer reopen the attachment. Replace example resource identifiers with your own authorized values. ```json { "url": "https://storage.googleapis.com/bucket/...", "file": { "name": "video.mp4", "path": "/media/video.mp4", "sizeBytes": "52428800", "contentType": "video/mp4" } } ``` Document ID: `DOC-CP-files-data-api-generateDownloadUrl`. [Section identities and revisions](/documentation-manifest.json). - Generate a pre-signed download URL: `DOC-CP-files-data-api-generateDownloadUrl#overview` - Request: `DOC-CP-files-data-api-generateDownloadUrl#request` - Responses: `DOC-CP-files-data-api-generateDownloadUrl#responses` --- # Generate a pre-signed upload URL URL: https://docs.travila.ai/api/storage/generate-upload-url **POST** `/api/v1/storage/generate-upload-url` Step 1: issues a time-limited signed URL for direct upload. `sizeBytes` is checked against current tracked quota and used as the signed upper size bound; it is not an atomic reservation or an exact-size assertion. Send the returned required headers, upload, and then register the returned fileId. The URL can be reused until expiry; treat it as a credential. The following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing. Use this in a guide: [Add file attachments to a support request](/core-platform/files-data/files) · [Organize a customer’s project documents](/core-platform/files-data/folders) · [Summarize a customer’s uploaded report](/managed-agents/conversations/attachments) · [Build a signed-in support chat that survives reconnects](/managed-agents/conversations/build-chat-assistant) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for issuing a signed URL for a direct file upload. **folderPath** `string` Path of the folder within the user’s storage namespace. **fileName** `string` File name to use within the selected folder. **contentType** `string` Media type describing the file or response body. **expiresSeconds** `string(int64)` Requested lifetime of the signed URL, in seconds. Pattern: ^-?\d+$ **metadata** `map[string, string]` Additional attributes associated with the resource. **sizeBytes** `string(int64)` **required** Declared upload size in bytes. Required (> 0): pre-checked against quota and bound into the signed URL via x-goog-content-length-range so GCS itself rejects larger uploads. Pattern: ^-?\d+$ #### storage-generateUploadUrl-request Request a signed upload for the six bytes Hello plus newline; send the returned required headers during upload. ```json { "folderPath": "reports", "fileName": "welcome.txt", "contentType": "text/plain", "sizeBytes": "6", "expiresSeconds": 900 } ``` #### cookbook-core-platform-files-data-files-01-request Guide request for Upload and confirm the recording. Replace example resource identifiers with your own authorized values. ```json { "folderPath": "/media", "fileName": "video.mp4", "contentType": "video/mp4", "sizeBytes": 52428800, "expiresSeconds": 3600 } ``` ## Responses ### 200 — Upload URL generated Content type: `application/json` Result payload for issuing a signed URL for a direct file upload. **url** `string` Signed URL used for direct file upload. **fileId** `string` Stable identifier of the stored file. **fullPath** `string` Complete object path allocated for the upload. **requiredHeaders** `map[string, string]` HTTP headers the client must send with the signed upload request. #### storage-generateUploadUrl-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "url": "https://example.com/resource", "fileId": "example_123", "fullPath": "documents/example.txt", "requiredHeaders": {} } ``` #### cookbook-core-platform-files-data-files-json-01-response Illustrative response for Upload and confirm the recording. Replace example resource identifiers with your own authorized values. ```json { "url": "https://storage.googleapis.com/bucket/...", "fileId": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "fullPath": "/media/video.mp4", "requiredHeaders": { "content-type": "video/mp4", "x-goog-content-length-range": "0,52428800" } } ``` Document ID: `DOC-CP-files-data-api-generateUploadUrl`. [Section identities and revisions](/documentation-manifest.json). - Generate a pre-signed upload URL: `DOC-CP-files-data-api-generateUploadUrl#overview` - Request: `DOC-CP-files-data-api-generateUploadUrl#request` - Responses: `DOC-CP-files-data-api-generateUploadUrl#responses` --- # Get file metadata URL: https://docs.travila.ai/api/storage/get-file-metadata **POST** `/api/v1/storage/get-file-metadata` Retrieves a file's tracked metadata without downloading its content. The following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing. Use this in a guide: [Build a searchable document library](/core-platform/files-data/managing) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for reading a stored file’s attributes without downloading its content. **fileId** `string` Stable identifier of the stored file. #### storage-getFileMetadata-request Read metadata for an existing file returned by upload or listing. ```json { "fileId": "0123456789abcdef0123456789abcdef" } ``` #### cookbook-core-platform-files-data-managing-03-request Guide request for Open the selected document’s details. Replace example resource identifiers with your own authorized values. ```json { "fileId": "a1b2c3d4e5f60718293a4b5c6d7e8f90" } ``` ## Responses ### 200 — File metadata returned Content type: `application/json` Result payload for reading a stored file’s attributes without downloading its content. **file** `any` Metadata for the file affected or retrieved by the operation. All of: Variant 1: FileInfo contains metadata about a file Model reference: [FileInfo](/api/models/schema-1lls6fo8p7#response). **fileId** `string` Stable identifier of the stored file. **name** `string` Name of the file within its containing folder. **path** `string` Full path (e.g., "/documents/report.pdf"). **folderPath** `string` Parent folder path. **sizeBytes** `string(int64)` Size of the file content, in bytes. Pattern: ^-?\d+$ **contentType** `string` Media type of the file content. **uploadedAt** `string` RFC3339 timestamp. **modifiedAt** `string` RFC3339 timestamp. **metadata** `map[string, string]` Custom metadata. **tags** `array[string]` User-defined tags. Type: `string` **description** `string` Optional description. **storageRef** `any` Reference to actual storage location. All of: Variant 1: ObjectRef references an object in storage Model reference: [ObjectRef](/api/models/schema-1lj1ellabu#response). **bucket** `string` Storage bucket containing the object. **key** `string` Object key within the selected storage bucket. **provider** `any` Storage provider used to access the object. Backend that stores the file bytes associated with a storage record.
| Value | No. | Form | Meaning | |---|---|---|---| | `STORAGE_PROVIDER_GCS` | 0 | Canonical | Google Cloud Storage. | | `STORAGE_PROVIDER_S3` | 1 | Canonical | See meaning below. | | `STORAGE_PROVIDER_FILESYSTEM` | 2 | Canonical | See meaning below. | | `STORAGE_PROVIDER_AZURE_BLOB` | 3 | Canonical | Azure Blob Storage. | **`STORAGE_PROVIDER_S3`** Amazon S3 or a storage service implementing the S3 interface. Amazon S3 (and compatibles) **`STORAGE_PROVIDER_FILESYSTEM`** A filesystem accessible to the storage service. Local filesystem
Exactly one of: Variant 1: Type: `string` Enum: `STORAGE_PROVIDER_GCS`, `STORAGE_PROVIDER_S3`, `STORAGE_PROVIDER_FILESYSTEM`, `STORAGE_PROVIDER_AZURE_BLOB` Variant 2: Type: `integer(int32)` **checksum** `string` File checksum (SHA256). **version** `string(int64)` Version number (for versioning support). Pattern: ^-?\d+$ #### storage-getFileMetadata-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "file": { "fileId": "example_123", "name": "example", "path": "documents/example.txt", "folderPath": "documents/example.txt", "sizeBytes": "1", "contentType": "Example text", "uploadedAt": "example", "modifiedAt": "example", "metadata": {}, "tags": [ "example" ], "description": "example", "storageRef": { "bucket": "example", "key": "example_123", "provider": "STORAGE_PROVIDER_GCS" }, "checksum": "example", "version": 1 } } ``` Document ID: `DOC-CP-files-data-api-getFileMetadata`. [Section identities and revisions](/documentation-manifest.json). - Get file metadata: `DOC-CP-files-data-api-getFileMetadata#overview` - Request: `DOC-CP-files-data-api-getFileMetadata#request` - Responses: `DOC-CP-files-data-api-getFileMetadata#responses` --- # Get storage state URL: https://docs.travila.ai/api/storage/get-state **POST** `/api/v1/storage/get-state` Returns the effective user’s full tracked storage state without pagination. Intended for restricted debugging; large accounts can produce large responses. A storage record is not an inventory or erasure certificate for every object/backend copy. The following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing. Use this in a guide: [Build a searchable document library](/core-platform/files-data/managing) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for reading the file and folder registry state in object storage. #### storage-getState-request Read the authenticated user’s storage state; no file or folder selector is needed. ```json {} ``` ## Responses ### 200 — Full state returned Content type: `application/json` Result payload for reading the file and folder registry state in object storage. **state** `any` Current storage state for the effective owner. All of: Variant 1: Tracked files, folders and storage usage for the effective storage owner. Model reference: [StorageManagerState](/api/models/schema-phpid7698e#response). **userId** `string` Identifier of the user associated with the operation. **folders** `map[string, storage_v1_common_v1_FolderInfo]` Path -> FolderInfo. Map values: FolderInfo contains metadata about a folder Model reference: [FolderInfo](/api/models/schema-opsbitjge1#response). **folderId** `string` Unique folder ID. **name** `string` Name of the folder within its parent folder. Folder name **path** `string` Full path (e.g., "/documents/work"). **parentPath** `string` Parent folder path. **createdAt** `string` RFC3339 timestamp. **modifiedAt** `string` RFC3339 timestamp. **metadata** `map[string, string]` Custom metadata. **fileCount** `string(int64)` Number of files (direct children). Pattern: ^-?\d+$ **subfolderCount** `string(int64)` Number of subfolders. Pattern: ^-?\d+$ **totalSizeBytes** `string(int64)` Total size of all files in folder (recursive). Pattern: ^-?\d+$ **files** `map[string, storage_v1_common_v1_FileInfo]` Path -> FileInfo. Map values: FileInfo contains metadata about a file Model reference: [FileInfo](/api/models/schema-1lls6fo8p7#response). **fileId** `string` Stable identifier of the stored file. **name** `string` Name of the file within its containing folder. **path** `string` Full path (e.g., "/documents/report.pdf"). **folderPath** `string` Parent folder path. **sizeBytes** `string(int64)` Size of the file content, in bytes. Pattern: ^-?\d+$ **contentType** `string` Media type of the file content. **uploadedAt** `string` RFC3339 timestamp. **modifiedAt** `string` RFC3339 timestamp. **metadata** `map[string, string]` Custom metadata. **tags** `array[string]` User-defined tags. Type: `string` **description** `string` Optional description. **storageRef** `any` Reference to actual storage location. All of: Variant 1: ObjectRef references an object in storage Model reference: [ObjectRef](/api/models/schema-1lj1ellabu#response). **bucket** `string` Storage bucket containing the object. **key** `string` Object key within the selected storage bucket. **provider** `any` Storage provider used to access the object. Backend that stores the file bytes associated with a storage record.
| Value | No. | Form | Meaning | |---|---|---|---| | `STORAGE_PROVIDER_GCS` | 0 | Canonical | Google Cloud Storage. | | `STORAGE_PROVIDER_S3` | 1 | Canonical | See meaning below. | | `STORAGE_PROVIDER_FILESYSTEM` | 2 | Canonical | See meaning below. | | `STORAGE_PROVIDER_AZURE_BLOB` | 3 | Canonical | Azure Blob Storage. | **`STORAGE_PROVIDER_S3`** Amazon S3 or a storage service implementing the S3 interface. Amazon S3 (and compatibles) **`STORAGE_PROVIDER_FILESYSTEM`** A filesystem accessible to the storage service. Local filesystem
Exactly one of: Variant 1: Type: `string` Enum: `STORAGE_PROVIDER_GCS`, `STORAGE_PROVIDER_S3`, `STORAGE_PROVIDER_FILESYSTEM`, `STORAGE_PROVIDER_AZURE_BLOB` Variant 2: Type: `integer(int32)` **checksum** `string` File checksum (SHA256). **version** `string(int64)` Version number (for versioning support). Pattern: ^-?\d+$ **totalSizeBytes** `string(int64)` Combined size of the represented files, in bytes. Pattern: ^-?\d+$ **quotaBytes** `string(int64)` Storage capacity allocated to the user, in bytes. Pattern: ^-?\d+$ **totalFileCount** `string(int64)` Number of files tracked in the storage state. Pattern: ^-?\d+$ **totalFolderCount** `string(int64)` Number of folders tracked in the storage state. Pattern: ^-?\d+$ **createdAt** `string` When user's storage was initialized. **lastModified** `string` Last modification timestamp. #### storage-getState-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "state": { "userId": "example_123", "folders": {}, "files": {}, "totalSizeBytes": "1", "quotaBytes": "1", "totalFileCount": 1, "totalFolderCount": 1, "createdAt": "example", "lastModified": "example" } } ``` Document ID: `DOC-CP-files-data-api-getState`. [Section identities and revisions](/documentation-manifest.json). - Get storage state: `DOC-CP-files-data-api-getState#overview` - Request: `DOC-CP-files-data-api-getState#request` - Responses: `DOC-CP-files-data-api-getState#responses` --- # Get storage usage and quota URL: https://docs.travila.ai/api/storage/get-storage-quota **POST** `/api/v1/storage/get-storage-quota` Returns the authenticated user's current tracked storage usage and quota. The following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing. Use this in a guide: [Build a searchable document library](/core-platform/files-data/managing) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for reading the user’s allocated capacity and current storage usage. #### storage-getStorageQuota-request Read quota and usage for the authenticated user’s storage namespace. ```json {} ``` ## Responses ### 200 — Quota information returned Content type: `application/json` Result payload for reading the user’s allocated capacity and current storage usage. **usedBytes** `string(int64)` Storage capacity currently attributed to the user, in bytes. Pattern: ^-?\d+$ **quotaBytes** `string(int64)` Storage capacity allocated to the user, in bytes. Pattern: ^-?\d+$ **fileCount** `string(int64)` Number of files represented by this quota snapshot. Pattern: ^-?\d+$ **folderCount** `string(int64)` Number of folders represented by the quota snapshot. Pattern: ^-?\d+$ **usagePercentage** `any` Storage usage expressed as a percentage of the quota. Exactly one of: Variant 1: Type: `number(double)` Variant 2: Type: `string` Enum: `NaN`, `Infinity`, `-Infinity` #### storage-getStorageQuota-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "usedBytes": "1", "quotaBytes": "1", "fileCount": 1, "folderCount": 1, "usagePercentage": 1 } ``` #### cookbook-core-platform-files-data-managing-json-02-response Illustrative response for Make room for another attachment. Replace example resource identifiers with your own authorized values. ```json { "usedBytes": "1048576", "quotaBytes": "1073741824", "fileCount": 15, "folderCount": 4, "usagePercentage": 0.098 } ``` Document ID: `DOC-CP-files-data-api-getStorageQuota`. [Section identities and revisions](/documentation-manifest.json). - Get storage usage and quota: `DOC-CP-files-data-api-getStorageQuota#overview` - Request: `DOC-CP-files-data-api-getStorageQuota#request` - Responses: `DOC-CP-files-data-api-getStorageQuota#responses` --- # List files and folders in a directory URL: https://docs.travila.ai/api/storage/list-files **POST** `/api/v1/storage/list-files` Lists files and subfolders under the given folder path. The current file filter accepts upload-date fields but does not enforce them; do not rely on those fields to exclude records. The following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing. Use this in a guide: [Build a searchable document library](/core-platform/files-data/managing) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for paging through files and subfolders with metadata filters. **folderPath** `string` Path of the folder within the user’s storage namespace. **recursive** `boolean` Whether the operation includes descendant folders and their contents. **pageSize** `string(int64)` Maximum number of entries requested per page. Pattern: ^-?\d+$ **pageToken** `string` Continuation token from a preceding page of results. **filter** `any` Selection criteria applied to the listing. All of: Variant 1: Name, extension, tag and size criteria for selecting stored files. Upload-time fields are accepted but are not applied by the current list and search handlers. Model reference: [FileFilter](/api/models/schema-oq26kmqtvq#request). **extensions** `array[string]` File extensions used to restrict matching files. Type: `string` **tags** `array[string]` Labels associated with the resource for organization or filtering. Type: `string` **minSizeBytes** `string(int64)` Minimum file size included by the filter, in bytes. Pattern: ^-?\d+$ **maxSizeBytes** `string(int64)` Maximum file size included by the filter, in bytes. Pattern: ^-?\d+$ **uploadedAfter** `string` Declared lower upload-time bound. The current list-files and search-files handlers accept this field but do not apply it. Do not rely on it to exclude files by date; inspect returned timestamps and the operation’s result limits. **uploadedBefore** `string` Declared upper upload-time bound. The current list-files and search-files handlers accept this field but do not apply it. Do not rely on it to exclude files by date; inspect returned timestamps and the operation’s result limits. **nameContains** `string` Text that must occur in the selected file’s name. #### storage-listFiles-request List a bounded page of files from the reports folder. ```json { "folderPath": "reports", "pageSize": 20 } ``` #### cookbook-core-platform-files-data-managing-01-request Guide request for Populate the folder view. Replace example resource identifiers with your own authorized values. ```json { "folderPath": "/documents", "recursive": true, "pageSize": 20 } ``` #### cookbook-core-platform-files-data-managing-json-01-request Guide request for Populate the folder view. Replace example resource identifiers with your own authorized values. ```json { "folderPath": "/", "recursive": true, "filter": { "extensions": [ ".pdf", ".docx" ], "tags": [ "work" ], "minSizeBytes": 1024, "nameContains": "report" } } ``` ## Responses ### 200 — File listing returned Content type: `application/json` Result payload for paging through files and subfolders with metadata filters. **files** `array[storage_v1_common_v1_FileInfo]` File metadata records returned by the listing or search. FileInfo contains metadata about a file Model reference: [FileInfo](/api/models/schema-1lls6fo8p7#response). **fileId** `string` Stable identifier of the stored file. **name** `string` Name of the file within its containing folder. **path** `string` Full path (e.g., "/documents/report.pdf"). **folderPath** `string` Parent folder path. **sizeBytes** `string(int64)` Size of the file content, in bytes. Pattern: ^-?\d+$ **contentType** `string` Media type of the file content. **uploadedAt** `string` RFC3339 timestamp. **modifiedAt** `string` RFC3339 timestamp. **metadata** `map[string, string]` Custom metadata. **tags** `array[string]` User-defined tags. Type: `string` **description** `string` Optional description. **storageRef** `any` Reference to actual storage location. All of: Variant 1: ObjectRef references an object in storage Model reference: [ObjectRef](/api/models/schema-1lj1ellabu#response). **bucket** `string` Storage bucket containing the object. **key** `string` Object key within the selected storage bucket. **provider** `any` Storage provider used to access the object. Backend that stores the file bytes associated with a storage record.
| Value | No. | Form | Meaning | |---|---|---|---| | `STORAGE_PROVIDER_GCS` | 0 | Canonical | Google Cloud Storage. | | `STORAGE_PROVIDER_S3` | 1 | Canonical | See meaning below. | | `STORAGE_PROVIDER_FILESYSTEM` | 2 | Canonical | See meaning below. | | `STORAGE_PROVIDER_AZURE_BLOB` | 3 | Canonical | Azure Blob Storage. | **`STORAGE_PROVIDER_S3`** Amazon S3 or a storage service implementing the S3 interface. Amazon S3 (and compatibles) **`STORAGE_PROVIDER_FILESYSTEM`** A filesystem accessible to the storage service. Local filesystem
Exactly one of: Variant 1: Type: `string` Enum: `STORAGE_PROVIDER_GCS`, `STORAGE_PROVIDER_S3`, `STORAGE_PROVIDER_FILESYSTEM`, `STORAGE_PROVIDER_AZURE_BLOB` Variant 2: Type: `integer(int32)` **checksum** `string` File checksum (SHA256). **version** `string(int64)` Version number (for versioning support). Pattern: ^-?\d+$ **folders** `array[storage_v1_common_v1_FolderInfo]` Folder metadata records returned by the listing. FolderInfo contains metadata about a folder Model reference: [FolderInfo](/api/models/schema-opsbitjge1#response). **folderId** `string` Unique folder ID. **name** `string` Name of the folder within its parent folder. Folder name **path** `string` Full path (e.g., "/documents/work"). **parentPath** `string` Parent folder path. **createdAt** `string` RFC3339 timestamp. **modifiedAt** `string` RFC3339 timestamp. **metadata** `map[string, string]` Custom metadata. **fileCount** `string(int64)` Number of files (direct children). Pattern: ^-?\d+$ **subfolderCount** `string(int64)` Number of subfolders. Pattern: ^-?\d+$ **totalSizeBytes** `string(int64)` Total size of all files in folder (recursive). Pattern: ^-?\d+$ **nextPageToken** `string` Continuation token returned for retrieving the next page. **totalCount** `string(int64)` Total number of matching entries reported by the operation. Pattern: ^-?\d+$ #### storage-listFiles-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "files": [ { "fileId": "example_123", "name": "example", "path": "documents/example.txt", "folderPath": "documents/example.txt", "sizeBytes": "1", "contentType": "Example text", "uploadedAt": "example", "modifiedAt": "example", "metadata": {}, "tags": [ "example" ], "description": "example", "storageRef": { "bucket": "example", "key": "example_123", "provider": "STORAGE_PROVIDER_GCS" }, "checksum": "example", "version": 1 } ], "folders": [ { "folderId": "example_123", "name": "example", "path": "documents/example.txt", "parentPath": "documents/example.txt", "createdAt": "example", "modifiedAt": "example", "metadata": {}, "fileCount": 1, "subfolderCount": 1, "totalSizeBytes": "1" } ], "nextPageToken": "example", "totalCount": 1 } ``` Document ID: `DOC-CP-files-data-api-listFiles`. [Section identities and revisions](/documentation-manifest.json). - List files and folders in a directory: `DOC-CP-files-data-api-listFiles#overview` - Request: `DOC-CP-files-data-api-listFiles#request` - Responses: `DOC-CP-files-data-api-listFiles#responses` --- # Move or rename a file URL: https://docs.travila.ai/api/storage/move-file **POST** `/api/v1/storage/move-file` Moves or renames a stored file while preserving its identity. The following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing. Use this in a guide: [Build a searchable document library](/core-platform/files-data/managing) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` MoveFileRequest moves/renames a file (identity is the file\_id; path is a label) **fileId** `string` Stable identifier of the stored file. **destinationFolder** `string` Destination folder path for the file move. **newName** `string` Replacement file name for the moved file. Omit to preserve its current name. #### storage-moveFile-request Move an existing file to the archive folder and rename it. ```json { "fileId": "0123456789abcdef0123456789abcdef", "destinationFolder": "archive", "newName": "welcome-archived.txt" } ``` #### cookbook-core-platform-files-data-managing-05-request Guide request for Archive a completed document. Replace example resource identifiers with your own authorized values. ```json { "fileId": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "destinationFolder": "/archive", "newName": "notes-2025-q1.txt" } ``` ## Responses ### 200 — File moved Content type: `application/json` Result payload for changing a stored file’s folder location and optional name. **file** `any` Metadata for the file affected or retrieved by the operation. All of: Variant 1: FileInfo contains metadata about a file Model reference: [FileInfo](/api/models/schema-1lls6fo8p7#response). **fileId** `string` Stable identifier of the stored file. **name** `string` Name of the file within its containing folder. **path** `string` Full path (e.g., "/documents/report.pdf"). **folderPath** `string` Parent folder path. **sizeBytes** `string(int64)` Size of the file content, in bytes. Pattern: ^-?\d+$ **contentType** `string` Media type of the file content. **uploadedAt** `string` RFC3339 timestamp. **modifiedAt** `string` RFC3339 timestamp. **metadata** `map[string, string]` Custom metadata. **tags** `array[string]` User-defined tags. Type: `string` **description** `string` Optional description. **storageRef** `any` Reference to actual storage location. All of: Variant 1: ObjectRef references an object in storage Model reference: [ObjectRef](/api/models/schema-1lj1ellabu#response). **bucket** `string` Storage bucket containing the object. **key** `string` Object key within the selected storage bucket. **provider** `any` Storage provider used to access the object. Backend that stores the file bytes associated with a storage record.
| Value | No. | Form | Meaning | |---|---|---|---| | `STORAGE_PROVIDER_GCS` | 0 | Canonical | Google Cloud Storage. | | `STORAGE_PROVIDER_S3` | 1 | Canonical | See meaning below. | | `STORAGE_PROVIDER_FILESYSTEM` | 2 | Canonical | See meaning below. | | `STORAGE_PROVIDER_AZURE_BLOB` | 3 | Canonical | Azure Blob Storage. | **`STORAGE_PROVIDER_S3`** Amazon S3 or a storage service implementing the S3 interface. Amazon S3 (and compatibles) **`STORAGE_PROVIDER_FILESYSTEM`** A filesystem accessible to the storage service. Local filesystem
Exactly one of: Variant 1: Type: `string` Enum: `STORAGE_PROVIDER_GCS`, `STORAGE_PROVIDER_S3`, `STORAGE_PROVIDER_FILESYSTEM`, `STORAGE_PROVIDER_AZURE_BLOB` Variant 2: Type: `integer(int32)` **checksum** `string` File checksum (SHA256). **version** `string(int64)` Version number (for versioning support). Pattern: ^-?\d+$ **moved** `boolean` Whether the file move operation reports completion. #### storage-moveFile-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "file": { "fileId": "example_123", "name": "example", "path": "documents/example.txt", "folderPath": "documents/example.txt", "sizeBytes": "1", "contentType": "Example text", "uploadedAt": "example", "modifiedAt": "example", "metadata": {}, "tags": [ "example" ], "description": "example", "storageRef": { "bucket": "example", "key": "example_123", "provider": "STORAGE_PROVIDER_GCS" }, "checksum": "example", "version": 1 }, "moved": true } ``` Document ID: `DOC-CP-files-data-api-moveFile`. [Section identities and revisions](/documentation-manifest.json). - Move or rename a file: `DOC-CP-files-data-api-moveFile#overview` - Request: `DOC-CP-files-data-api-moveFile#request` - Responses: `DOC-CP-files-data-api-moveFile#responses` --- # Register a file uploaded via pre-signed URL URL: https://docs.travila.ai/api/storage/register-uploaded-file **POST** `/api/v1/storage/register-uploaded-file` Step 3: after uploading, register the fileId with the same folderPath and intended fileName. The backend checks the object at the derived caller-scoped path and reads its stored size and content-type metadata. MIME metadata can be supplied by the uploader and is not byte/content validation. The signed-upload path does not compute a checksum. An already registered fileId returns the existing record with registered false, which may be omitted. This retry behavior does not prove that a reused signed URL cannot subsequently alter the object. Missing uploaded objects return 404; quota and backend failures require reconciliation. The following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing. Use this in a guide: [Add file attachments to a support request](/core-platform/files-data/files) · [Organize a customer’s project documents](/core-platform/files-data/folders) · [Upload registration and URL expiry](/api/storage/uploads) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` RegisterUploadedFileRequest completes the signed-URL upload flow (step 3 of 3): after PUTting bytes to the URL from GenerateUploadUrl, register the object so it becomes visible to ListFiles/GetFileMetadata/GenerateDownloadUrl. **fileId** `string` **required** file\_id returned by GenerateUploadUrl (32 lowercase hex chars). The GCS key is recomputed server-side from the caller-scoped folder\_path + file\_id, so a caller can only ever register objects under its own prefix. Pattern: ^[a-f0-9]{32}$ **folderPath** `string` Must match the folder\_path passed to GenerateUploadUrl. **fileName** `string` **required** File name to use within the selected folder. Minimum length: 1 **metadata** `map[string, string]` Additional attributes associated with the resource. **tags** `array[string]` Labels associated with the resource for organization or filtering. Type: `string` #### storage-registerUploadedFile-request After uploading, use the fileId returned by generate-upload-url and the same folderPath and fileName. ```json { "fileId": "0123456789abcdef0123456789abcdef", "folderPath": "reports", "fileName": "welcome.txt" } ``` #### cookbook-core-platform-files-data-files-03-request Guide request for Upload and confirm the recording. Replace example resource identifiers with your own authorized values. ```json { "fileId": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "folderPath": "/media", "fileName": "video.mp4" } ``` ## Responses ### 200 — File registered (or already registered) Content type: `application/json` Result payload for recording metadata for a file uploaded directly to storage. **file** `any` Metadata for the file affected or retrieved by the operation. All of: Variant 1: FileInfo contains metadata about a file Model reference: [FileInfo](/api/models/schema-1lls6fo8p7#response). **fileId** `string` Stable identifier of the stored file. **name** `string` Name of the file within its containing folder. **path** `string` Full path (e.g., "/documents/report.pdf"). **folderPath** `string` Parent folder path. **sizeBytes** `string(int64)` Size of the file content, in bytes. Pattern: ^-?\d+$ **contentType** `string` Media type of the file content. **uploadedAt** `string` RFC3339 timestamp. **modifiedAt** `string` RFC3339 timestamp. **metadata** `map[string, string]` Custom metadata. **tags** `array[string]` User-defined tags. Type: `string` **description** `string` Optional description. **storageRef** `any` Reference to actual storage location. All of: Variant 1: ObjectRef references an object in storage Model reference: [ObjectRef](/api/models/schema-1lj1ellabu#response). **bucket** `string` Storage bucket containing the object. **key** `string` Object key within the selected storage bucket. **provider** `any` Storage provider used to access the object. Backend that stores the file bytes associated with a storage record.
| Value | No. | Form | Meaning | |---|---|---|---| | `STORAGE_PROVIDER_GCS` | 0 | Canonical | Google Cloud Storage. | | `STORAGE_PROVIDER_S3` | 1 | Canonical | See meaning below. | | `STORAGE_PROVIDER_FILESYSTEM` | 2 | Canonical | See meaning below. | | `STORAGE_PROVIDER_AZURE_BLOB` | 3 | Canonical | Azure Blob Storage. | **`STORAGE_PROVIDER_S3`** Amazon S3 or a storage service implementing the S3 interface. Amazon S3 (and compatibles) **`STORAGE_PROVIDER_FILESYSTEM`** A filesystem accessible to the storage service. Local filesystem
Exactly one of: Variant 1: Type: `string` Enum: `STORAGE_PROVIDER_GCS`, `STORAGE_PROVIDER_S3`, `STORAGE_PROVIDER_FILESYSTEM`, `STORAGE_PROVIDER_AZURE_BLOB` Variant 2: Type: `integer(int32)` **checksum** `string` File checksum (SHA256). **version** `string(int64)` Version number (for versioning support). Pattern: ^-?\d+$ **registered** `boolean` true when newly registered; false when the file\_id was already registered (idempotent retry — the existing FileInfo is returned unchanged). #### storage-registerUploadedFile-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "file": { "fileId": "example_123", "name": "example", "path": "documents/example.txt", "folderPath": "documents/example.txt", "sizeBytes": "1", "contentType": "Example text", "uploadedAt": "example", "modifiedAt": "example", "metadata": {}, "tags": [ "example" ], "description": "example", "storageRef": { "bucket": "example", "key": "example_123", "provider": "STORAGE_PROVIDER_GCS" }, "checksum": "example", "version": 1 }, "registered": true } ``` ### 404 — No uploaded object found for this `fileId` (PUT the file first) Document ID: `DOC-CP-files-data-api-registerUploadedFile`. [Section identities and revisions](/documentation-manifest.json). - Register a file uploaded via pre-signed URL: `DOC-CP-files-data-api-registerUploadedFile#overview` - Request: `DOC-CP-files-data-api-registerUploadedFile#request` - Responses: `DOC-CP-files-data-api-registerUploadedFile#responses` --- # Search files URL: https://docs.travila.ai/api/storage/search-files **POST** `/api/v1/storage/search-files` Searches the effective user's tracked files using a case-insensitive filename substring or a case-insensitive complete tag. File contents, such as text inside a PDF, are not searched. Supported `FileFilter` fields narrow candidates before the query is applied, and all listed tags must be present. The date filters [`uploadedAfter`](/api/models/schema-oq26kmqtvq#request-field-uploadedafter) and [`uploadedBefore`](/api/models/schema-oq26kmqtvq#request-field-uploadedbefore) are accepted but currently not enforced; do not offer a date range as an effective filter. [`maxResults`](/api/storage/search-files#request-field-maxresults) caps a single response; search does not paginate. If results are too broad, let the customer refine the name, tag or folder rather than promising a complete result set. The following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing. Use this in a guide: [Build a searchable document library](/core-platform/files-data/managing) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for finding stored files by query text and metadata constraints. **query** `string` Search expression used to select matching entries. **filter** `any` Selection criteria applied to the listing. All of: Variant 1: Name, extension, tag and size criteria for selecting stored files. Upload-time fields are accepted but are not applied by the current list and search handlers. Model reference: [FileFilter](/api/models/schema-oq26kmqtvq#request). **extensions** `array[string]` File extensions used to restrict matching files. Type: `string` **tags** `array[string]` Labels associated with the resource for organization or filtering. Type: `string` **minSizeBytes** `string(int64)` Minimum file size included by the filter, in bytes. Pattern: ^-?\d+$ **maxSizeBytes** `string(int64)` Maximum file size included by the filter, in bytes. Pattern: ^-?\d+$ **uploadedAfter** `string` Declared lower upload-time bound. The current list-files and search-files handlers accept this field but do not apply it. Do not rely on it to exclude files by date; inspect returned timestamps and the operation’s result limits. **uploadedBefore** `string` Declared upper upload-time bound. The current list-files and search-files handlers accept this field but do not apply it. Do not rely on it to exclude files by date; inspect returned timestamps and the operation’s result limits. **nameContains** `string` Text that must occur in the selected file’s name. **maxResults** `string(int64)` Maximum number of file matches requested. Pattern: ^-?\d+$ #### storage-searchFiles-request Find matching files within the authenticated user’s storage namespace. ```json { "query": "welcome", "maxResults": 20 } ``` #### cookbook-core-platform-files-data-managing-02-request Guide request for Find a report when its folder is unknown. Replace example resource identifiers with your own authorized values. ```json { "query": "quarterly report", "maxResults": 10, "filter": { "extensions": [ ".pdf" ], "tags": [ "finance" ], "minSizeBytes": 1024, "maxSizeBytes": 52428800, "nameContains": "Q1" } } ``` ## Responses ### 200 — Search results returned Content type: `application/json` Result payload for finding stored files by query text and metadata constraints. **files** `array[storage_v1_common_v1_FileInfo]` File metadata records returned by the listing or search. FileInfo contains metadata about a file Model reference: [FileInfo](/api/models/schema-1lls6fo8p7#response). **fileId** `string` Stable identifier of the stored file. **name** `string` Name of the file within its containing folder. **path** `string` Full path (e.g., "/documents/report.pdf"). **folderPath** `string` Parent folder path. **sizeBytes** `string(int64)` Size of the file content, in bytes. Pattern: ^-?\d+$ **contentType** `string` Media type of the file content. **uploadedAt** `string` RFC3339 timestamp. **modifiedAt** `string` RFC3339 timestamp. **metadata** `map[string, string]` Custom metadata. **tags** `array[string]` User-defined tags. Type: `string` **description** `string` Optional description. **storageRef** `any` Reference to actual storage location. All of: Variant 1: ObjectRef references an object in storage Model reference: [ObjectRef](/api/models/schema-1lj1ellabu#response). **bucket** `string` Storage bucket containing the object. **key** `string` Object key within the selected storage bucket. **provider** `any` Storage provider used to access the object. Backend that stores the file bytes associated with a storage record.
| Value | No. | Form | Meaning | |---|---|---|---| | `STORAGE_PROVIDER_GCS` | 0 | Canonical | Google Cloud Storage. | | `STORAGE_PROVIDER_S3` | 1 | Canonical | See meaning below. | | `STORAGE_PROVIDER_FILESYSTEM` | 2 | Canonical | See meaning below. | | `STORAGE_PROVIDER_AZURE_BLOB` | 3 | Canonical | Azure Blob Storage. | **`STORAGE_PROVIDER_S3`** Amazon S3 or a storage service implementing the S3 interface. Amazon S3 (and compatibles) **`STORAGE_PROVIDER_FILESYSTEM`** A filesystem accessible to the storage service. Local filesystem
Exactly one of: Variant 1: Type: `string` Enum: `STORAGE_PROVIDER_GCS`, `STORAGE_PROVIDER_S3`, `STORAGE_PROVIDER_FILESYSTEM`, `STORAGE_PROVIDER_AZURE_BLOB` Variant 2: Type: `integer(int32)` **checksum** `string` File checksum (SHA256). **version** `string(int64)` Version number (for versioning support). Pattern: ^-?\d+$ **totalMatches** `string(int64)` Number of files reported to match the search criteria. Pattern: ^-?\d+$ #### storage-searchFiles-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "files": [ { "fileId": "example_123", "name": "example", "path": "documents/example.txt", "folderPath": "documents/example.txt", "sizeBytes": "1", "contentType": "Example text", "uploadedAt": "example", "modifiedAt": "example", "metadata": {}, "tags": [ "example" ], "description": "example", "storageRef": { "bucket": "example", "key": "example_123", "provider": "STORAGE_PROVIDER_GCS" }, "checksum": "example", "version": 1 } ], "totalMatches": 1 } ``` Document ID: `DOC-CP-files-data-api-searchFiles`. [Section identities and revisions](/documentation-manifest.json). - Search files: `DOC-CP-files-data-api-searchFiles#overview` - Request: `DOC-CP-files-data-api-searchFiles#request` - Responses: `DOC-CP-files-data-api-searchFiles#responses` --- # Storage APIs URL: https://docs.travila.ai/api/storage Version: `aju17f20mq` Use the reference below for request and response fields and operation-specific requirements. # Overview \{#overview} Manage files and folders, issue signed upload/download URLs, and inspect tracked storage usage. ## Authentication \{#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](https://docs.travila.ai/core-platform/identity-access/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. Signed URLs are bearer credentials and can be reused until their expiry. An upload URL is followed by direct upload and registration; issuing the URL neither registers the file nor reserves quota. Registration checks the stored object’s size. Its MIME metadata is not content validation. **Related guide:** [Files and storage](https://docs.travila.ai/core-platform/files-data) ### JSON conventions \{#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](https://docs.travila.ai/api). ## Folders \{#reference-group-1} Folder management — create and delete directory containers. See the [Storage guide](https://docs.travila.ai/core-platform/files-data). * [Create a new folder](/api/storage/create-folder) * [Delete a folder](/api/storage/delete-folder) ## Uploads & Downloads \{#reference-group-2} File upload (inline and pre-signed) and pre-signed download URLs. See the [Storage guide](https://docs.travila.ai/core-platform/files-data) for both inline and large-file patterns. * [Generate a pre-signed upload URL](/api/storage/generate-upload-url) * [Register a file uploaded via pre-signed URL](/api/storage/register-uploaded-file) * [Generate a pre-signed download URL](/api/storage/generate-download-url) * [Generate pre-signed download URLs for multiple files](/api/storage/batch-generate-download-urls) ## Files \{#reference-group-3} File listing, search, move, and delete. See the [Storage guide](https://docs.travila.ai/core-platform/files-data). * [List files and folders in a directory](/api/storage/list-files) * [Upload a file (deprecated)](/api/storage/upload-file) * [Delete a file](/api/storage/delete-file) * [Move or rename a file](/api/storage/move-file) * [Search files](/api/storage/search-files) ## Metadata \{#reference-group-4} File metadata and tag management. See the [Storage guide](https://docs.travila.ai/core-platform/files-data). * [Get file metadata](/api/storage/get-file-metadata) * [Update file metadata](/api/storage/update-file-metadata) ## Quota & State \{#reference-group-5} Storage quota usage and account state. See the [Storage guide](https://docs.travila.ai/core-platform/files-data). * [Get storage usage and quota](/api/storage/get-storage-quota) * [Get storage state](/api/storage/get-state) ## Server 1 \{#reference-server-1} Travila API [https://api.travila.ai](https://api.travila.ai) ## X-API-Key \{#authentication-apiKeyAuth} 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 \{#authentication-onBehalfOf} 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 \{#authentication-bearerAuth} 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

### apiKeyAuth Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-API-Key` ### onBehalfOf Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-On-Behalf-Of` ### bearerAuth Security scheme type: `http` HTTP authorization scheme: `bearer` ## Operations - [Create a new folder](/api/storage/create-folder) — `POST /api/v1/storage/create-folder` - [Delete a folder](/api/storage/delete-folder) — `POST /api/v1/storage/delete-folder` - [List files and folders in a directory](/api/storage/list-files) — `POST /api/v1/storage/list-files` - [Upload a file (deprecated)](/api/storage/upload-file) — `POST /api/v1/storage/upload-file` - [Delete a file](/api/storage/delete-file) — `POST /api/v1/storage/delete-file` - [Move or rename a file](/api/storage/move-file) — `POST /api/v1/storage/move-file` - [Get file metadata](/api/storage/get-file-metadata) — `POST /api/v1/storage/get-file-metadata` - [Update file metadata](/api/storage/update-file-metadata) — `POST /api/v1/storage/update-file-metadata` - [Get storage usage and quota](/api/storage/get-storage-quota) — `POST /api/v1/storage/get-storage-quota` - [Search files](/api/storage/search-files) — `POST /api/v1/storage/search-files` - [Generate a pre-signed upload URL](/api/storage/generate-upload-url) — `POST /api/v1/storage/generate-upload-url` - [Register a file uploaded via pre-signed URL](/api/storage/register-uploaded-file) — `POST /api/v1/storage/register-uploaded-file` - [Generate a pre-signed download URL](/api/storage/generate-download-url) — `POST /api/v1/storage/generate-download-url` - [Generate pre-signed download URLs for multiple files](/api/storage/batch-generate-download-urls) — `POST /api/v1/storage/batch-generate-download-urls` - [Get storage state](/api/storage/get-state) — `POST /api/v1/storage/get-state` Document ID: `DOC-API-storage-overview`. [Section identities and revisions](/documentation-manifest.json). - Overview: `DOC-API-storage-overview#overview` - Authentication: `DOC-API-storage-overview#authentication` - JSON conventions: `DOC-API-storage-overview#json-conventions` - Folders: `DOC-API-storage-overview#reference-group-1` - Uploads & Downloads: `DOC-API-storage-overview#reference-group-2` - Files: `DOC-API-storage-overview#reference-group-3` - Metadata: `DOC-API-storage-overview#reference-group-4` - Quota & State: `DOC-API-storage-overview#reference-group-5` - Server 1: `DOC-API-storage-overview#reference-server-1` - X-API-Key: `DOC-API-storage-overview#authentication-apiKeyAuth` - X-On-Behalf-Of: `DOC-API-storage-overview#authentication-onBehalfOf` - Authorization: Bearer: `DOC-API-storage-overview#authentication-bearerAuth` --- # Update file metadata URL: https://docs.travila.ai/api/storage/update-file-metadata **POST** `/api/v1/storage/update-file-metadata` Replaces the metadata map and tag list when they survive decoding as nonnil values; it does not merge individual map keys. A nonempty description replaces the old description. This public shape has no reliable explicit clear operation for every empty value. Read the current record and submit the complete intended map/list; concurrent updates can overwrite one another. ### Update metadata This operation cannot clear tags with `[]`; an empty description leaves the previous description unchanged. The following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing. Use this in a guide: [Build a searchable document library](/core-platform/files-data/managing) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for changing labels, description, or custom attributes of a stored file. **fileId** `string` Stable identifier of the stored file. **metadata** `map[string, string]` Additional attributes associated with the resource. **tags** `array[string]` Labels associated with the resource for organization or filtering. Type: `string` **description** `string` Human-readable description of the resource. #### storage-updateFileMetadata-request Set descriptive metadata on an existing file. ```json { "fileId": "0123456789abcdef0123456789abcdef", "description": "Welcome message", "tags": [ "onboarding" ], "metadata": { "category": "help" } } ``` #### cookbook-core-platform-files-data-managing-04-request Guide request for Save the review labels without erasing other labels. Replace example resource identifiers with your own authorized values. ```json { "fileId": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "metadata": { "reviewed": "true", "category": "internal" }, "tags": [ "notes", "reviewed" ], "description": "Meeting notes from Q1 planning" } ``` ## Responses ### 200 — File metadata updated Content type: `application/json` Result payload for changing labels, description, or custom attributes of a stored file. **file** `any` Metadata for the file affected or retrieved by the operation. All of: Variant 1: FileInfo contains metadata about a file Model reference: [FileInfo](/api/models/schema-1lls6fo8p7#response). **fileId** `string` Stable identifier of the stored file. **name** `string` Name of the file within its containing folder. **path** `string` Full path (e.g., "/documents/report.pdf"). **folderPath** `string` Parent folder path. **sizeBytes** `string(int64)` Size of the file content, in bytes. Pattern: ^-?\d+$ **contentType** `string` Media type of the file content. **uploadedAt** `string` RFC3339 timestamp. **modifiedAt** `string` RFC3339 timestamp. **metadata** `map[string, string]` Custom metadata. **tags** `array[string]` User-defined tags. Type: `string` **description** `string` Optional description. **storageRef** `any` Reference to actual storage location. All of: Variant 1: ObjectRef references an object in storage Model reference: [ObjectRef](/api/models/schema-1lj1ellabu#response). **bucket** `string` Storage bucket containing the object. **key** `string` Object key within the selected storage bucket. **provider** `any` Storage provider used to access the object. Backend that stores the file bytes associated with a storage record.
| Value | No. | Form | Meaning | |---|---|---|---| | `STORAGE_PROVIDER_GCS` | 0 | Canonical | Google Cloud Storage. | | `STORAGE_PROVIDER_S3` | 1 | Canonical | See meaning below. | | `STORAGE_PROVIDER_FILESYSTEM` | 2 | Canonical | See meaning below. | | `STORAGE_PROVIDER_AZURE_BLOB` | 3 | Canonical | Azure Blob Storage. | **`STORAGE_PROVIDER_S3`** Amazon S3 or a storage service implementing the S3 interface. Amazon S3 (and compatibles) **`STORAGE_PROVIDER_FILESYSTEM`** A filesystem accessible to the storage service. Local filesystem
Exactly one of: Variant 1: Type: `string` Enum: `STORAGE_PROVIDER_GCS`, `STORAGE_PROVIDER_S3`, `STORAGE_PROVIDER_FILESYSTEM`, `STORAGE_PROVIDER_AZURE_BLOB` Variant 2: Type: `integer(int32)` **checksum** `string` File checksum (SHA256). **version** `string(int64)` Version number (for versioning support). Pattern: ^-?\d+$ **updated** `boolean` Whether the file metadata update reports a change. #### storage-updateFileMetadata-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "file": { "fileId": "example_123", "name": "example", "path": "documents/example.txt", "folderPath": "documents/example.txt", "sizeBytes": "1", "contentType": "Example text", "uploadedAt": "example", "modifiedAt": "example", "metadata": {}, "tags": [ "example" ], "description": "example", "storageRef": { "bucket": "example", "key": "example_123", "provider": "STORAGE_PROVIDER_GCS" }, "checksum": "example", "version": 1 }, "updated": true } ``` Document ID: `DOC-CP-files-data-api-updateFileMetadata`. [Section identities and revisions](/documentation-manifest.json). - Update file metadata: `DOC-CP-files-data-api-updateFileMetadata#overview` - Request: `DOC-CP-files-data-api-updateFileMetadata#request` - Responses: `DOC-CP-files-data-api-updateFileMetadata#responses` --- # Upload a file (deprecated) URL: https://docs.travila.ai/api/storage/upload-file **POST** `/api/v1/storage/upload-file` Deprecated. **Deprecated — use the 3-step pre-signed flow instead** (`generate-upload-url` → `PUT` → `register-uploaded-file`). Uploads file content synchronously to the specified folder. For large files, prefer the pre-signed flow to avoid sending the full content through this operation. The following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing. Use this in a guide: [Add file attachments to a support request](/core-platform/files-data/files) ## Authentication One of: - API Key via `X-API-Key` header parameter AND API Key via `X-On-Behalf-Of` header parameter - API Key via `X-API-Key` header parameter AND HTTP Bearer via `Authorization: Bearer ` ## Request Body *Required* Content type: `application/json` Inputs for uploading file content and recording its metadata in the selected folder. **folderPath** `string` Path of the folder within the user’s storage namespace. **fileName** `string` File name to use within the selected folder. **content** `string(byte)` Raw bytes of the file being uploaded. **contentType** `string` Media type of the uploaded file. **metadata** `map[string, string]` Additional attributes associated with the resource. **tags** `array[string]` Labels associated with the resource for organization or filtering. Type: `string` #### storage-uploadFile-request Upload the base64 encoding of Hello followed by a newline. ```json { "folderPath": "reports", "fileName": "welcome.txt", "content": "SGVsbG8K", "contentType": "text/plain" } ``` ## Responses ### 200 — File uploaded successfully Content type: `application/json` Result payload for uploading file content and recording its metadata in the selected folder. **file** `any` Metadata for the file affected or retrieved by the operation. All of: Variant 1: FileInfo contains metadata about a file Model reference: [FileInfo](/api/models/schema-1lls6fo8p7#response). **fileId** `string` Stable identifier of the stored file. **name** `string` Name of the file within its containing folder. **path** `string` Full path (e.g., "/documents/report.pdf"). **folderPath** `string` Parent folder path. **sizeBytes** `string(int64)` Size of the file content, in bytes. Pattern: ^-?\d+$ **contentType** `string` Media type of the file content. **uploadedAt** `string` RFC3339 timestamp. **modifiedAt** `string` RFC3339 timestamp. **metadata** `map[string, string]` Custom metadata. **tags** `array[string]` User-defined tags. Type: `string` **description** `string` Optional description. **storageRef** `any` Reference to actual storage location. All of: Variant 1: ObjectRef references an object in storage Model reference: [ObjectRef](/api/models/schema-1lj1ellabu#response). **bucket** `string` Storage bucket containing the object. **key** `string` Object key within the selected storage bucket. **provider** `any` Storage provider used to access the object. Backend that stores the file bytes associated with a storage record.
| Value | No. | Form | Meaning | |---|---|---|---| | `STORAGE_PROVIDER_GCS` | 0 | Canonical | Google Cloud Storage. | | `STORAGE_PROVIDER_S3` | 1 | Canonical | See meaning below. | | `STORAGE_PROVIDER_FILESYSTEM` | 2 | Canonical | See meaning below. | | `STORAGE_PROVIDER_AZURE_BLOB` | 3 | Canonical | Azure Blob Storage. | **`STORAGE_PROVIDER_S3`** Amazon S3 or a storage service implementing the S3 interface. Amazon S3 (and compatibles) **`STORAGE_PROVIDER_FILESYSTEM`** A filesystem accessible to the storage service. Local filesystem
Exactly one of: Variant 1: Type: `string` Enum: `STORAGE_PROVIDER_GCS`, `STORAGE_PROVIDER_S3`, `STORAGE_PROVIDER_FILESYSTEM`, `STORAGE_PROVIDER_AZURE_BLOB` Variant 2: Type: `integer(int32)` **checksum** `string` File checksum (SHA256). **version** `string(int64)` Version number (for versioning support). Pattern: ^-?\d+$ **uploaded** `boolean` Whether the file upload operation reports completion. #### storage-uploadFile-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "file": { "fileId": "example_123", "name": "example", "path": "documents/example.txt", "folderPath": "documents/example.txt", "sizeBytes": "1", "contentType": "Example text", "uploadedAt": "example", "modifiedAt": "example", "metadata": {}, "tags": [ "example" ], "description": "example", "storageRef": { "bucket": "example", "key": "example_123", "provider": "STORAGE_PROVIDER_GCS" }, "checksum": "example", "version": 1 }, "uploaded": true } ``` Document ID: `DOC-CP-files-data-api-uploadFile`. [Section identities and revisions](/documentation-manifest.json). - Upload a file (deprecated): `DOC-CP-files-data-api-uploadFile#overview` - Request: `DOC-CP-files-data-api-uploadFile#request` - Responses: `DOC-CP-files-data-api-uploadFile#responses` --- # Create a webhook endpoint URL: https://docs.travila.ai/api/webhooks/create-webhook-endpoint **POST** `/api/v1/webhooks/create-endpoint` Creates an endpoint and optionally attempts a subscription when eventTypes is provided. These provider writes are separate and can partially succeed. Reconcile the endpoint and subscriptions before retrying to avoid orphaned endpoints or duplicate deliveries. The following access conditions are preserved as declared intent and are not implemented by generated code: Tenant request context, Tenant-scoped webhook ownership. Use this in a guide: [Event catalog](/api/events) · [Automate recurring agent work](/core-platform/scheduling/build-scheduled-agents) · [Receive a completed order summary in your backend](/integrations/webhooks/endpoints) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for registering a tenant webhook destination and its initial event subscription. ### Input constraints ### url The url value must be a valid absolute URI. **name** `string` **required** Display name of the tenant’s webhook delivery destination. Minimum length: 1 **url** `string(uri)` **required** URL of the tenant’s webhook delivery destination. **description** `string` Human-readable description of the resource. **eventTypes** `array[string]` Convenience: auto-create subscription. Type: `string` #### webhooks-createWebhookEndpoint-request Create a receiver for generation completion; replace the URL with your verified receiver. ```json { "name": "Generation events", "url": "https://api.example.com/hooks/travila", "eventTypes": [ "llm.generation_completed" ] } ``` #### cookbook-core-platform-scheduling-build-scheduled-agents-03-request Guide request for Step 5: Subscribe to the results webhook (Optional). Replace example resource identifiers with your own authorized values. ```json { "name": "scheduled-agent-results", "url": "https://api.example.com/hooks/agent-results", "description": "Receives assistant messages from scheduled agent runs", "eventTypes": [ "llm.message_published" ] } ``` #### cookbook-integrations-webhooks-endpoints-01-request Guide request for 1. Register the receiver for completed runs. Replace example resource identifiers with your own authorized values. ```json { "name": "orders-service", "url": "https://api.example.com/hooks/travila", "description": "Order pipeline consumer", "eventTypes": [ "llm.generation_completed" ] } ``` ## Responses ### 200 — Endpoint created successfully Content type: `application/json` Result payload for registering a tenant webhook destination and its initial event subscription. **endpoint** `any` Webhook endpoint returned by the provider operation. All of: Variant 1: Provider record describing a webhook delivery destination and its delivery settings. Model reference: [Endpoint](/api/models/schema-1ffl20kv2k#response). **id** `string` Identifier of the endpoint record. **name** `string` Display name of the webhook delivery destination. **url** `string` URL of the webhook delivery destination. **description** `string` Human-readable description of the resource. **status** `any` Current state of the webhook endpoint. Enums Lifecycle condition reported for a webhook delivery endpoint.
| Value | No. | Form | Meaning | |---|---|---|---| | `ENDPOINT_STATUS_ACTIVE` | 0 | Canonical | The endpoint is marked active for webhook delivery. | | `ENDPOINT_STATUS_INACTIVE` | 1 | Canonical | The endpoint is marked inactive by the delivery backend. | | `ENDPOINT_STATUS_PAUSED` | 2 | Canonical | Delivery to the endpoint is paused. | | `ENDPOINT_STATUS_PENDING` | 3 | Canonical | The endpoint is pending activation in the delivery backend. |
Exactly one of: Variant 1: Type: `string` Enum: `ENDPOINT_STATUS_ACTIVE`, `ENDPOINT_STATUS_INACTIVE`, `ENDPOINT_STATUS_PAUSED`, `ENDPOINT_STATUS_PENDING` Variant 2: Type: `integer(int32)` **secret** `string` Secret associated with the webhook endpoint. **httpTimeout** `string(int64)` Timeout for an individual webhook HTTP delivery, in seconds. Pattern: ^-?\d+$ **rateLimit** `string(int64)` Maximum delivery rate configured for the webhook endpoint. Pattern: ^-?\d+$ **rateLimitDuration** `string` Delivery-rate window returned as a seconds-suffixed duration string (for example, 60s). **createdAt** `string(date-time)` Time when this record was created. **updatedAt** `string(date-time)` Time when this record was last updated. **subscription** `any` If event\_types provided. All of: Variant 1: Webhook event selection and retry settings associated with an endpoint. Model reference: [Subscription](/api/models/schema-1fn66l17fv#response). **id** `string` Identifier of the subscription record. **name** `string` Display name of the webhook event subscription. **endpointId** `string` Identifier of the webhook endpoint receiving deliveries. **eventTypes** `array[string]` Event type names selected for the webhook subscription. Type: `string` **filter** `any` Event-body and header conditions used to select webhook events for this subscription. All of: Variant 1: Event-body and header conditions selecting webhook events for a subscription. Model reference: [SubscriptionFilter](/api/models/schema-1fl5depe11#response). **body** `map[string, string]` Event-body matching rules used by the webhook subscription filter. **headers** `map[string, string]` Header-matching rules used to select events for the webhook subscription. **retryConfig** `any` Retry policy applied to the webhook subscription. All of: Variant 1: Retry strategy, attempt limit, and interval for failed webhook deliveries. Model reference: [RetryConfig](/api/models/schema-1fkul0p8vd#response). **strategy** `any` Webhook retry strategy selected in the provider configuration. Backoff strategy applied between webhook delivery attempts.
| Value | No. | Form | Meaning | |---|---|---|---| | `RETRY_STRATEGY_LINEAR` | 0 | Canonical | Retry using the configured linear interval strategy. | | `RETRY_STRATEGY_EXPONENTIAL` | 1 | Canonical | Increase the delay between retries using exponential backoff. |
Exactly one of: Variant 1: Type: `string` Enum: `RETRY_STRATEGY_LINEAR`, `RETRY_STRATEGY_EXPONENTIAL` Variant 2: Type: `integer(int32)` **retryCount** `string(int64)` Maximum retry count configured for webhook delivery. Pattern: ^-?\d+$ **intervalSeconds** `string(int64)` Delay between webhook delivery retries, in seconds. Pattern: ^-?\d+$ **createdAt** `string(date-time)` Time when this record was created. **externalId** `string` Client-supplied external subscription identifier. Empty when none was supplied. **updatedAt** `string(date-time)` Time when this record was last updated; equals created\_at until the first accepted update. #### webhooks-createWebhookEndpoint-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "endpoint": { "id": "example_123", "name": "example", "url": "https://example.com/resource", "description": "example", "status": "ENDPOINT_STATUS_ACTIVE", "secret": "example", "httpTimeout": 1, "rateLimit": 1, "rateLimitDuration": "example", "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z" }, "subscription": { "id": "example_123", "name": "example", "endpointId": "https://example.com/resource", "eventTypes": [ "example" ], "filter": {}, "retryConfig": { "strategy": "RETRY_STRATEGY_LINEAR", "retryCount": 1, "intervalSeconds": 1 }, "createdAt": "2026-09-16T12:00:00Z", "externalId": "example_123", "updatedAt": "2026-09-16T12:00:00Z" } } ``` #### cookbook-core-platform-scheduling-build-scheduled-agents-json-04-response Illustrative response for Step 5: Subscribe to the results webhook (Optional). Replace example resource identifiers with your own authorized values. ```json { "endpoint": { "id": "ep_abc123", "name": "scheduled-agent-results", "url": "https://api.example.com/hooks/agent-results", "status": "ENDPOINT_STATUS_ACTIVE", "secret": "whsec_…" }, "subscription": { "id": "sub_def456", "endpointId": "ep_abc123", "eventTypes": [ "llm.message_published" ] } } ``` Document ID: `DOC-IN-webhooks-api-createWebhookEndpoint`. [Section identities and revisions](/documentation-manifest.json). - Create a webhook endpoint: `DOC-IN-webhooks-api-createWebhookEndpoint#overview` - Request: `DOC-IN-webhooks-api-createWebhookEndpoint#request` - Responses: `DOC-IN-webhooks-api-createWebhookEndpoint#responses` --- # Create a webhook subscription URL: https://docs.travila.ai/api/webhooks/create-webhook-subscription **POST** `/api/v1/webhooks/create-subscription` Creates a new event subscription on an existing webhook endpoint. The subscription filters events by the specified event types and delivers matching events to the endpoint URL. ### One subscription per endpoint Only one live subscription is allowed per endpoint; a second fails with `ALREADY_EXISTS`. There is no public update-subscription operation. [Delete the old subscription](/api/webhooks/delete-webhook-subscription) and create its replacement when a delivery gap is acceptable. The following access conditions are preserved as declared intent and are not implemented by generated code: Tenant request context, Tenant-scoped webhook ownership. Use this in a guide: [Event catalog](/api/events) · [Receive a completed order summary in your backend](/integrations/webhooks/endpoints) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for subscribing a tenant webhook endpoint to selected event types. **endpointId** `string` **required** Identifier of the webhook endpoint receiving deliveries. Minimum length: 1 **eventTypes** `array[string]` **required** Event type names selected for the webhook subscription. Minimum items: 1 Type: `string` **externalId** `string` Optional client-supplied identifier, unique among the tenant’s live subscriptions. Use it to address deletion by a name your application manages; it becomes reusable after deletion. Maximum length: 255 #### webhooks-createWebhookSubscription-request Subscribe an existing endpoint that does not already have a live subscription. ```json { "endpointId": "ep_abc123", "eventTypes": [ "llm.generation_completed" ] } ``` ## Responses ### 200 — Subscription created successfully Content type: `application/json` Result payload for subscribing a tenant webhook endpoint to selected event types. **subscription** `any` Webhook subscription returned by the provider operation. All of: Variant 1: Webhook event selection and retry settings associated with an endpoint. Model reference: [Subscription](/api/models/schema-1fn66l17fv#response). **id** `string` Identifier of the subscription record. **name** `string` Display name of the webhook event subscription. **endpointId** `string` Identifier of the webhook endpoint receiving deliveries. **eventTypes** `array[string]` Event type names selected for the webhook subscription. Type: `string` **filter** `any` Event-body and header conditions used to select webhook events for this subscription. All of: Variant 1: Event-body and header conditions selecting webhook events for a subscription. Model reference: [SubscriptionFilter](/api/models/schema-1fl5depe11#response). **body** `map[string, string]` Event-body matching rules used by the webhook subscription filter. **headers** `map[string, string]` Header-matching rules used to select events for the webhook subscription. **retryConfig** `any` Retry policy applied to the webhook subscription. All of: Variant 1: Retry strategy, attempt limit, and interval for failed webhook deliveries. Model reference: [RetryConfig](/api/models/schema-1fkul0p8vd#response). **strategy** `any` Webhook retry strategy selected in the provider configuration. Backoff strategy applied between webhook delivery attempts.
| Value | No. | Form | Meaning | |---|---|---|---| | `RETRY_STRATEGY_LINEAR` | 0 | Canonical | Retry using the configured linear interval strategy. | | `RETRY_STRATEGY_EXPONENTIAL` | 1 | Canonical | Increase the delay between retries using exponential backoff. |
Exactly one of: Variant 1: Type: `string` Enum: `RETRY_STRATEGY_LINEAR`, `RETRY_STRATEGY_EXPONENTIAL` Variant 2: Type: `integer(int32)` **retryCount** `string(int64)` Maximum retry count configured for webhook delivery. Pattern: ^-?\d+$ **intervalSeconds** `string(int64)` Delay between webhook delivery retries, in seconds. Pattern: ^-?\d+$ **createdAt** `string(date-time)` Time when this record was created. **externalId** `string` Client-supplied external subscription identifier. Empty when none was supplied. **updatedAt** `string(date-time)` Time when this record was last updated; equals created\_at until the first accepted update. #### webhooks-createWebhookSubscription-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "subscription": { "id": "example_123", "name": "example", "endpointId": "https://example.com/resource", "eventTypes": [ "example" ], "filter": {}, "retryConfig": { "strategy": "RETRY_STRATEGY_LINEAR", "retryCount": 1, "intervalSeconds": 1 }, "createdAt": "2026-09-16T12:00:00Z", "externalId": "example_123", "updatedAt": "2026-09-16T12:00:00Z" } } ``` Document ID: `DOC-IN-webhooks-api-createWebhookSubscription`. [Section identities and revisions](/documentation-manifest.json). - Create a webhook subscription: `DOC-IN-webhooks-api-createWebhookSubscription#overview` - Request: `DOC-IN-webhooks-api-createWebhookSubscription#request` - Responses: `DOC-IN-webhooks-api-createWebhookSubscription#responses` --- # Delete a webhook endpoint URL: https://docs.travila.ai/api/webhooks/delete-webhook-endpoint **POST** `/api/v1/webhooks/delete-endpoint` Deletes the endpoint and its associated provider subscriptions. Already dispatched deliveries can still reach the receiver; deletion does not attest to erasure of historical deliveries or backups. The following access conditions are preserved as declared intent and are not implemented by generated code: Tenant request context, Tenant-scoped webhook ownership. Use this in a guide: [Receive a completed order summary in your backend](/integrations/webhooks/endpoints) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for removing a tenant’s webhook delivery destination. **endpointId** `string` **required** Identifier of the webhook endpoint receiving deliveries. Minimum length: 1 #### webhooks-deleteWebhookEndpoint-request Use an existing endpointId when retiring a receiver. ```json { "endpointId": "ep_abc123" } ``` ## Responses ### 200 — Endpoint deleted successfully Content type: `application/json` Response schema for removing a tenant’s webhook delivery destination; no response fields are declared. #### webhooks-deleteWebhookEndpoint-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json {} ``` Document ID: `DOC-IN-webhooks-api-deleteWebhookEndpoint`. [Section identities and revisions](/documentation-manifest.json). - Delete a webhook endpoint: `DOC-IN-webhooks-api-deleteWebhookEndpoint#overview` - Request: `DOC-IN-webhooks-api-deleteWebhookEndpoint#request` - Responses: `DOC-IN-webhooks-api-deleteWebhookEndpoint#responses` --- # Delete a webhook subscription URL: https://docs.travila.ai/api/webhooks/delete-webhook-subscription **POST** `/api/v1/webhooks/delete-subscription` Deletes the subscription without deleting its endpoint. Pending/in-flight provider deliveries and retained history require separate handling; deletion is not remote-effect rollback. The following access conditions are preserved as declared intent and are not implemented by generated code: Tenant request context, Tenant-scoped webhook ownership. ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for removing a tenant webhook subscription by its external identifier. **subscriptionId** `string` Identifier of the subscription to delete. Supply exactly one of subscription\_id or external\_id. **externalId** `string` Stable external identifier used to address the webhook subscription. Maximum length: 255 #### webhooks-deleteWebhookSubscription-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "subscriptionId": "example_123" } ``` ## Responses ### 200 — Subscription deleted successfully Content type: `application/json` Response schema for removing a tenant webhook subscription by its external identifier; no response fields are declared. #### webhooks-deleteWebhookSubscription-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json {} ``` Document ID: `DOC-IN-webhooks-api-deleteWebhookSubscription`. [Section identities and revisions](/documentation-manifest.json). - Delete a webhook subscription: `DOC-IN-webhooks-api-deleteWebhookSubscription#overview` - Request: `DOC-IN-webhooks-api-deleteWebhookSubscription#request` - Responses: `DOC-IN-webhooks-api-deleteWebhookSubscription#responses` --- # List webhook event deliveries URL: https://docs.travila.ai/api/webhooks/list-webhook-deliveries **POST** `/api/v1/webhooks/list-deliveries` Returns paginated delivery records. A record is not a complete log of every HTTP attempt. The following access conditions are preserved as declared intent and are not implemented by generated code: Tenant request context, Tenant-scoped webhook ownership. Use this in a guide: [Recover a missing backend update](/integrations/webhooks/deliveries) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for querying delivery attempts visible through the tenant webhook gateway. **endpointId** `string` Optional: filter by endpoint. **subscriptionId** `string` Optional: filter by subscription. **eventId** `string` Optional: filter by event. **status** `any` Delivery status used to restrict the tenant webhook-delivery query. Optional: filter by status Current delivery state of a webhook event sent to an endpoint.
| Value | No. | Form | Meaning | |---|---|---|---| | `DELIVERY_STATUS_SCHEDULED` | 0 | Canonical | The delivery is scheduled and waiting for processing. | | `DELIVERY_STATUS_PROCESSING` | 1 | Canonical | The delivery backend is processing a delivery attempt. | | `DELIVERY_STATUS_COMPLETED` | 2 | Canonical | See meaning below. | | `DELIVERY_STATUS_RETRY` | 3 | Canonical | The delivery is awaiting another attempt after a retryable failure. | | `DELIVERY_STATUS_FAILED` | 4 | Canonical | The delivery is reported as failed by the backend. | | `DELIVERY_STATUS_DISCARDED` | 5 | Canonical | The delivery backend discarded the event instead of completing delivery. | **`DELIVERY_STATUS_COMPLETED`** The webhook delivery completed successfully. Terminal.
Exactly one of: Variant 1: Type: `string` Enum: `DELIVERY_STATUS_SCHEDULED`, `DELIVERY_STATUS_PROCESSING`, `DELIVERY_STATUS_COMPLETED`, `DELIVERY_STATUS_RETRY`, `DELIVERY_STATUS_FAILED`, `DELIVERY_STATUS_DISCARDED` Variant 2: Type: `integer(int32)` **createdAfter** `string(date-time)` Optional: filter by creation time. **createdBefore** `string(date-time)` Optional: filter by creation time. **page** `string(int64)` Page number used by this listing operation. Pattern: ^-?\d+$ **perPage** `string(int64)` Number of entries requested per page. Pattern: ^-?\d+$ #### webhooks-listWebhookDeliveries-request Inspect a bounded page of deliveries for an existing endpoint. ```json { "endpointId": "ep_abc123", "page": 1, "perPage": 25 } ``` #### cookbook-integrations-webhooks-deliveries-01-request Guide request for 1. Find where the update stopped. Replace example resource identifiers with your own authorized values. ```json { "endpointId": "ep_abc123", "status": "DELIVERY_STATUS_FAILED", "createdAfter": "2026-08-01T00:00:00Z", "perPage": 50 } ``` ## Responses ### 200 — Deliveries listed successfully Content type: `application/json` Result payload for querying delivery attempts visible through the tenant webhook gateway. **deliveries** `array[integrations_v1_services_webhook_v1_EventDelivery]` Webhook delivery records matching the listing query. Delivery-attempt state and response information for a webhook event. Model reference: [EventDelivery](/api/models/schema-1fiv947q56#response). **id** `string` Identifier of the event delivery record. **eventId** `string` Identifier of the webhook event being delivered. **endpointId** `string` Identifier of the webhook endpoint receiving deliveries. **status** `any` Current delivery status reported for this webhook event attempt. Current delivery state of a webhook event sent to an endpoint.
| Value | No. | Form | Meaning | |---|---|---|---| | `DELIVERY_STATUS_SCHEDULED` | 0 | Canonical | The delivery is scheduled and waiting for processing. | | `DELIVERY_STATUS_PROCESSING` | 1 | Canonical | The delivery backend is processing a delivery attempt. | | `DELIVERY_STATUS_COMPLETED` | 2 | Canonical | See meaning below. | | `DELIVERY_STATUS_RETRY` | 3 | Canonical | The delivery is awaiting another attempt after a retryable failure. | | `DELIVERY_STATUS_FAILED` | 4 | Canonical | The delivery is reported as failed by the backend. | | `DELIVERY_STATUS_DISCARDED` | 5 | Canonical | The delivery backend discarded the event instead of completing delivery. | **`DELIVERY_STATUS_COMPLETED`** The webhook delivery completed successfully. Terminal.
Exactly one of: Variant 1: Type: `string` Enum: `DELIVERY_STATUS_SCHEDULED`, `DELIVERY_STATUS_PROCESSING`, `DELIVERY_STATUS_COMPLETED`, `DELIVERY_STATUS_RETRY`, `DELIVERY_STATUS_FAILED`, `DELIVERY_STATUS_DISCARDED` Variant 2: Type: `integer(int32)` **attempts** `string(int64)` Number of delivery attempts reported for the webhook event. Pattern: ^-?\d+$ **eventType** `string` Type of the webhook event represented by this delivery. **createdAt** `string(date-time)` Time when this record was created. **updatedAt** `string(date-time)` Time when this record was last updated. **httpStatus** `string(int64)` HTTP response status reported for the delivery attempt. Pattern: ^-?\d+$ **responseData** `string` Response body reported by the webhook delivery target. **error** `string` Error information reported for this operation or item. **pagination** `any` Page position and total counts reported with the listing. All of: Variant 1: Page position and aggregate counts accompanying a paginated provider listing. Model reference: [PaginationInfo](/api/models/schema-ohggnansec#response). **total** `string(int64)` Total number of entries reported by the listing. Pattern: ^-?\d+$ **page** `string(int64)` Page number used by this listing operation. Pattern: ^-?\d+$ **perPage** `string(int64)` Number of entries requested per page. Pattern: ^-?\d+$ **totalPages** `string(int64)` Total number of pages reported for the current query. Pattern: ^-?\d+$ #### webhooks-listWebhookDeliveries-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "deliveries": [ { "id": "example_123", "eventId": "example_123", "endpointId": "https://example.com/resource", "status": "DELIVERY_STATUS_SCHEDULED", "attempts": 1, "eventType": "example", "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z", "httpStatus": 1, "responseData": "example", "error": "example" } ], "pagination": { "total": 1, "page": 1, "perPage": 1, "totalPages": 1 } } ``` Document ID: `DOC-IN-webhooks-api-listWebhookDeliveries`. [Section identities and revisions](/documentation-manifest.json). - List webhook event deliveries: `DOC-IN-webhooks-api-listWebhookDeliveries#overview` - Request: `DOC-IN-webhooks-api-listWebhookDeliveries#request` - Responses: `DOC-IN-webhooks-api-listWebhookDeliveries#responses` --- # List webhook endpoints URL: https://docs.travila.ai/api/webhooks/list-webhook-endpoints **POST** `/api/v1/webhooks/list-endpoints` Returns a paginated list of all webhook endpoints belonging to the authenticated tenant. The following access conditions are preserved as declared intent and are not implemented by generated code: Tenant request context, Tenant-scoped webhook ownership. Use this in a guide: [Recover a missing backend update](/integrations/webhooks/deliveries) · [Receive a completed order summary in your backend](/integrations/webhooks/endpoints) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for listing webhook destinations registered for the tenant. **page** `string(int64)` Page number used by this listing operation. Pattern: ^-?\d+$ **perPage** `string(int64)` Number of entries requested per page. Pattern: ^-?\d+$ #### webhooks-listWebhookEndpoints-request List endpoints in the authenticated scope with default paging. ```json {} ``` #### cookbook-integrations-webhooks-endpoints-02-request Guide request for Save the signing secret. Replace example resource identifiers with your own authorized values. ```json { "page": 1, "perPage": 25 } ``` ## Responses ### 200 — Endpoints listed successfully Content type: `application/json` Result payload for listing webhook destinations registered for the tenant. **endpoints** `array[integrations_v1_services_webhook_v1_Endpoint]` Webhook endpoints returned by the listing. Provider record describing a webhook delivery destination and its delivery settings. Model reference: [Endpoint](/api/models/schema-1ffl20kv2k#response). **id** `string` Identifier of the endpoint record. **name** `string` Display name of the webhook delivery destination. **url** `string` URL of the webhook delivery destination. **description** `string` Human-readable description of the resource. **status** `any` Current state of the webhook endpoint. Enums Lifecycle condition reported for a webhook delivery endpoint.
| Value | No. | Form | Meaning | |---|---|---|---| | `ENDPOINT_STATUS_ACTIVE` | 0 | Canonical | The endpoint is marked active for webhook delivery. | | `ENDPOINT_STATUS_INACTIVE` | 1 | Canonical | The endpoint is marked inactive by the delivery backend. | | `ENDPOINT_STATUS_PAUSED` | 2 | Canonical | Delivery to the endpoint is paused. | | `ENDPOINT_STATUS_PENDING` | 3 | Canonical | The endpoint is pending activation in the delivery backend. |
Exactly one of: Variant 1: Type: `string` Enum: `ENDPOINT_STATUS_ACTIVE`, `ENDPOINT_STATUS_INACTIVE`, `ENDPOINT_STATUS_PAUSED`, `ENDPOINT_STATUS_PENDING` Variant 2: Type: `integer(int32)` **secret** `string` Secret associated with the webhook endpoint. **httpTimeout** `string(int64)` Timeout for an individual webhook HTTP delivery, in seconds. Pattern: ^-?\d+$ **rateLimit** `string(int64)` Maximum delivery rate configured for the webhook endpoint. Pattern: ^-?\d+$ **rateLimitDuration** `string` Delivery-rate window returned as a seconds-suffixed duration string (for example, 60s). **createdAt** `string(date-time)` Time when this record was created. **updatedAt** `string(date-time)` Time when this record was last updated. **pagination** `any` Page position and total counts reported with the listing. All of: Variant 1: Page position and aggregate counts accompanying a paginated provider listing. Model reference: [PaginationInfo](/api/models/schema-ohggnansec#response). **total** `string(int64)` Total number of entries reported by the listing. Pattern: ^-?\d+$ **page** `string(int64)` Page number used by this listing operation. Pattern: ^-?\d+$ **perPage** `string(int64)` Number of entries requested per page. Pattern: ^-?\d+$ **totalPages** `string(int64)` Total number of pages reported for the current query. Pattern: ^-?\d+$ #### webhooks-listWebhookEndpoints-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "endpoints": [ { "id": "example_123", "name": "example", "url": "https://example.com/resource", "description": "example", "status": "ENDPOINT_STATUS_ACTIVE", "secret": "example", "httpTimeout": 1, "rateLimit": 1, "rateLimitDuration": "example", "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z" } ], "pagination": { "total": 1, "page": 1, "perPage": 1, "totalPages": 1 } } ``` Document ID: `DOC-IN-webhooks-api-listWebhookEndpoints`. [Section identities and revisions](/documentation-manifest.json). - List webhook endpoints: `DOC-IN-webhooks-api-listWebhookEndpoints#overview` - Request: `DOC-IN-webhooks-api-listWebhookEndpoints#request` - Responses: `DOC-IN-webhooks-api-listWebhookEndpoints#responses` --- # List webhook subscriptions URL: https://docs.travila.ai/api/webhooks/list-webhook-subscriptions **POST** `/api/v1/webhooks/list-subscriptions` Returns a paginated list of webhook subscriptions. Optionally filter by endpoint ID. The following access conditions are preserved as declared intent and are not implemented by generated code: Tenant request context, Tenant-scoped webhook ownership. Use this in a guide: [Recover a missing backend update](/integrations/webhooks/deliveries) · [Receive a completed order summary in your backend](/integrations/webhooks/endpoints) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for listing event subscriptions registered for tenant webhook destinations. **endpointId** `string` Optional: filter by endpoint. **page** `string(int64)` Page number used by this listing operation. Pattern: ^-?\d+$ **perPage** `string(int64)` Number of entries requested per page. Pattern: ^-?\d+$ #### webhooks-listWebhookSubscriptions-request List subscriptions for an existing endpoint. ```json { "endpointId": "ep_abc123", "page": 1, "perPage": 25 } ``` ## Responses ### 200 — Subscriptions listed successfully Content type: `application/json` Result payload for listing event subscriptions registered for tenant webhook destinations. **subscriptions** `array[integrations_v1_services_webhook_v1_Subscription]` Webhook subscriptions returned by the listing. Webhook event selection and retry settings associated with an endpoint. Model reference: [Subscription](/api/models/schema-1fn66l17fv#response). **id** `string` Identifier of the subscription record. **name** `string` Display name of the webhook event subscription. **endpointId** `string` Identifier of the webhook endpoint receiving deliveries. **eventTypes** `array[string]` Event type names selected for the webhook subscription. Type: `string` **filter** `any` Event-body and header conditions used to select webhook events for this subscription. All of: Variant 1: Event-body and header conditions selecting webhook events for a subscription. Model reference: [SubscriptionFilter](/api/models/schema-1fl5depe11#response). **body** `map[string, string]` Event-body matching rules used by the webhook subscription filter. **headers** `map[string, string]` Header-matching rules used to select events for the webhook subscription. **retryConfig** `any` Retry policy applied to the webhook subscription. All of: Variant 1: Retry strategy, attempt limit, and interval for failed webhook deliveries. Model reference: [RetryConfig](/api/models/schema-1fkul0p8vd#response). **strategy** `any` Webhook retry strategy selected in the provider configuration. Backoff strategy applied between webhook delivery attempts.
| Value | No. | Form | Meaning | |---|---|---|---| | `RETRY_STRATEGY_LINEAR` | 0 | Canonical | Retry using the configured linear interval strategy. | | `RETRY_STRATEGY_EXPONENTIAL` | 1 | Canonical | Increase the delay between retries using exponential backoff. |
Exactly one of: Variant 1: Type: `string` Enum: `RETRY_STRATEGY_LINEAR`, `RETRY_STRATEGY_EXPONENTIAL` Variant 2: Type: `integer(int32)` **retryCount** `string(int64)` Maximum retry count configured for webhook delivery. Pattern: ^-?\d+$ **intervalSeconds** `string(int64)` Delay between webhook delivery retries, in seconds. Pattern: ^-?\d+$ **createdAt** `string(date-time)` Time when this record was created. **externalId** `string` Client-supplied external subscription identifier. Empty when none was supplied. **updatedAt** `string(date-time)` Time when this record was last updated; equals created\_at until the first accepted update. **pagination** `any` Page position and total counts reported with the listing. All of: Variant 1: Page position and aggregate counts accompanying a paginated provider listing. Model reference: [PaginationInfo](/api/models/schema-ohggnansec#response). **total** `string(int64)` Total number of entries reported by the listing. Pattern: ^-?\d+$ **page** `string(int64)` Page number used by this listing operation. Pattern: ^-?\d+$ **perPage** `string(int64)` Number of entries requested per page. Pattern: ^-?\d+$ **totalPages** `string(int64)` Total number of pages reported for the current query. Pattern: ^-?\d+$ #### webhooks-listWebhookSubscriptions-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "subscriptions": [ { "id": "example_123", "name": "example", "endpointId": "https://example.com/resource", "eventTypes": [ "example" ], "filter": {}, "retryConfig": { "strategy": "RETRY_STRATEGY_LINEAR", "retryCount": 1, "intervalSeconds": 1 }, "createdAt": "2026-09-16T12:00:00Z", "externalId": "example_123", "updatedAt": "2026-09-16T12:00:00Z" } ], "pagination": { "total": 1, "page": 1, "perPage": 1, "totalPages": 1 } } ``` Document ID: `DOC-IN-webhooks-api-listWebhookSubscriptions`. [Section identities and revisions](/documentation-manifest.json). - List webhook subscriptions: `DOC-IN-webhooks-api-listWebhookSubscriptions#overview` - Request: `DOC-IN-webhooks-api-listWebhookSubscriptions#request` - Responses: `DOC-IN-webhooks-api-listWebhookSubscriptions#responses` --- # Retry a failed webhook delivery URL: https://docs.travila.ai/api/webhooks/retry-webhook-delivery **POST** `/api/v1/webhooks/retry-delivery` Re-queues a previously failed or discarded event delivery for another delivery attempt. A successful response only acknowledges re-queueing. The receiver must deduplicate repeated events and distinguish receipt from completed business work. The following access conditions are preserved as declared intent and are not implemented by generated code: Tenant request context, Tenant-scoped webhook ownership. Use this in a guide: [Recover a missing backend update](/integrations/webhooks/deliveries) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for requesting another attempt for a tenant webhook delivery. **deliveryId** `string` **required** Identifier of the webhook delivery to inspect or retry. Minimum length: 1 #### webhooks-retryWebhookDelivery-request Schema-valid request illustration; replace example identifiers and confirm operation prerequisites. ```json { "deliveryId": "example_123" } ``` #### cookbook-integrations-webhooks-deliveries-02-request Guide request for 3. Replay the original eligible delivery. Replace example resource identifiers with your own authorized values. ```json { "deliveryId": "del_xyz789" } ``` ## Responses ### 200 — Another attempt requested; inspect delivery status for the outcome Content type: `application/json` Result payload for requesting another attempt for a tenant webhook delivery. **delivery** `any` Webhook delivery record returned by the operation. All of: Variant 1: Delivery-attempt state and response information for a webhook event. Model reference: [EventDelivery](/api/models/schema-1fiv947q56#response). **id** `string` Identifier of the event delivery record. **eventId** `string` Identifier of the webhook event being delivered. **endpointId** `string` Identifier of the webhook endpoint receiving deliveries. **status** `any` Current delivery status reported for this webhook event attempt. Current delivery state of a webhook event sent to an endpoint.
| Value | No. | Form | Meaning | |---|---|---|---| | `DELIVERY_STATUS_SCHEDULED` | 0 | Canonical | The delivery is scheduled and waiting for processing. | | `DELIVERY_STATUS_PROCESSING` | 1 | Canonical | The delivery backend is processing a delivery attempt. | | `DELIVERY_STATUS_COMPLETED` | 2 | Canonical | See meaning below. | | `DELIVERY_STATUS_RETRY` | 3 | Canonical | The delivery is awaiting another attempt after a retryable failure. | | `DELIVERY_STATUS_FAILED` | 4 | Canonical | The delivery is reported as failed by the backend. | | `DELIVERY_STATUS_DISCARDED` | 5 | Canonical | The delivery backend discarded the event instead of completing delivery. | **`DELIVERY_STATUS_COMPLETED`** The webhook delivery completed successfully. Terminal.
Exactly one of: Variant 1: Type: `string` Enum: `DELIVERY_STATUS_SCHEDULED`, `DELIVERY_STATUS_PROCESSING`, `DELIVERY_STATUS_COMPLETED`, `DELIVERY_STATUS_RETRY`, `DELIVERY_STATUS_FAILED`, `DELIVERY_STATUS_DISCARDED` Variant 2: Type: `integer(int32)` **attempts** `string(int64)` Number of delivery attempts reported for the webhook event. Pattern: ^-?\d+$ **eventType** `string` Type of the webhook event represented by this delivery. **createdAt** `string(date-time)` Time when this record was created. **updatedAt** `string(date-time)` Time when this record was last updated. **httpStatus** `string(int64)` HTTP response status reported for the delivery attempt. Pattern: ^-?\d+$ **responseData** `string` Response body reported by the webhook delivery target. **error** `string` Error information reported for this operation or item. #### webhooks-retryWebhookDelivery-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "delivery": { "id": "example_123", "eventId": "example_123", "endpointId": "https://example.com/resource", "status": "DELIVERY_STATUS_SCHEDULED", "attempts": 1, "eventType": "example", "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z", "httpStatus": 1, "responseData": "example", "error": "example" } } ``` Document ID: `DOC-IN-webhooks-api-retryWebhookDelivery`. [Section identities and revisions](/documentation-manifest.json). - Retry a failed webhook delivery: `DOC-IN-webhooks-api-retryWebhookDelivery#overview` - Request: `DOC-IN-webhooks-api-retryWebhookDelivery#request` - Responses: `DOC-IN-webhooks-api-retryWebhookDelivery#responses` --- # Update a webhook endpoint URL: https://docs.travila.ai/api/webhooks/update-webhook-endpoint **POST** `/api/v1/webhooks/update-endpoint` Reads the endpoint and overlays nonempty name, URL and description before sending the provider a replacement. Empty strings do not clear fields. There is no public revision precondition, so concurrent changes can overwrite one another. The following access conditions are preserved as declared intent and are not implemented by generated code: Tenant request context, Tenant-scoped webhook ownership. Use this in a guide: [Recover a missing backend update](/integrations/webhooks/deliveries) · [Receive a completed order summary in your backend](/integrations/webhooks/endpoints) ## Authentication Required: - API Key via `X-API-Key` header parameter ## Request Body *Required* Content type: `application/json` Inputs for changing the address or descriptive metadata of a tenant webhook destination. **endpointId** `string` **required** Identifier of the webhook endpoint receiving deliveries. Minimum length: 1 **name** `string` Display name of the tenant’s webhook delivery destination. **url** `string` URL of the tenant’s webhook delivery destination. **description** `string` Human-readable description of the resource. #### webhooks-updateWebhookEndpoint-request Update an existing endpoint after verifying the replacement receiver. ```json { "endpointId": "ep_abc123", "url": "https://api.example.com/hooks/travila-v2" } ``` ## Responses ### 200 — Endpoint updated successfully Content type: `application/json` Result payload for changing the address or descriptive metadata of a tenant webhook destination. **endpoint** `any` Webhook endpoint returned by the provider operation. All of: Variant 1: Provider record describing a webhook delivery destination and its delivery settings. Model reference: [Endpoint](/api/models/schema-1ffl20kv2k#response). **id** `string` Identifier of the endpoint record. **name** `string` Display name of the webhook delivery destination. **url** `string` URL of the webhook delivery destination. **description** `string` Human-readable description of the resource. **status** `any` Current state of the webhook endpoint. Enums Lifecycle condition reported for a webhook delivery endpoint.
| Value | No. | Form | Meaning | |---|---|---|---| | `ENDPOINT_STATUS_ACTIVE` | 0 | Canonical | The endpoint is marked active for webhook delivery. | | `ENDPOINT_STATUS_INACTIVE` | 1 | Canonical | The endpoint is marked inactive by the delivery backend. | | `ENDPOINT_STATUS_PAUSED` | 2 | Canonical | Delivery to the endpoint is paused. | | `ENDPOINT_STATUS_PENDING` | 3 | Canonical | The endpoint is pending activation in the delivery backend. |
Exactly one of: Variant 1: Type: `string` Enum: `ENDPOINT_STATUS_ACTIVE`, `ENDPOINT_STATUS_INACTIVE`, `ENDPOINT_STATUS_PAUSED`, `ENDPOINT_STATUS_PENDING` Variant 2: Type: `integer(int32)` **secret** `string` Secret associated with the webhook endpoint. **httpTimeout** `string(int64)` Timeout for an individual webhook HTTP delivery, in seconds. Pattern: ^-?\d+$ **rateLimit** `string(int64)` Maximum delivery rate configured for the webhook endpoint. Pattern: ^-?\d+$ **rateLimitDuration** `string` Delivery-rate window returned as a seconds-suffixed duration string (for example, 60s). **createdAt** `string(date-time)` Time when this record was created. **updatedAt** `string(date-time)` Time when this record was last updated. #### webhooks-updateWebhookEndpoint-response Illustrative response shape; omitted default fields and actual outcomes depend on the operation. ```json { "endpoint": { "id": "example_123", "name": "example", "url": "https://example.com/resource", "description": "example", "status": "ENDPOINT_STATUS_ACTIVE", "secret": "example", "httpTimeout": 1, "rateLimit": 1, "rateLimitDuration": "example", "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z" } } ``` Document ID: `DOC-IN-webhooks-api-updateWebhookEndpoint`. [Section identities and revisions](/documentation-manifest.json). - Update a webhook endpoint: `DOC-IN-webhooks-api-updateWebhookEndpoint#overview` - Request: `DOC-IN-webhooks-api-updateWebhookEndpoint#request` - Responses: `DOC-IN-webhooks-api-updateWebhookEndpoint#responses` --- # Webhook APIs URL: https://docs.travila.ai/api/webhooks Version: `aju17f20mq` Use the reference below for request and response fields and operation-specific requirements. # Overview \{#overview} Register HTTPS endpoints, subscribe them to events and inspect or retry deliveries. ## Authentication \{#authentication} Use an authorized backend `sk_…` key in `X-API-Key`; these configuration operations do not need an end-user identity. A console JWT belongs to the separate console surface. See [Authentication](https://docs.travila.ai/core-platform/identity-access/authentication). Tenant context comes from the authenticated request. Client-supplied `X-Tenant-Id`, `X-User-Id` or `X-Project-Id` are not an authorization mechanism. 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. ### Endpoints and subscriptions \{#endpoints-and-subscriptions} An endpoint is your receiving URL; a subscription selects its events. Supplying `eventTypes` during endpoint creation also attempts a subscription, but the two writes can partially succeed. Reconcile before retrying. The current platform permits one live subscription per endpoint and rejects a second. Replacement by delete-then-create has a delivery gap; temporary overlap requires a separately created endpoint, receiver deduplication and a qualified cutover. ## Addressing Subscriptions \{#addressing-subscriptions} Subscription references accept exactly one of `subscriptionId` or `externalId` where offered. An external ID is unique among live subscriptions in its current scope and may be reused after deletion; do not treat a reused alias as the original subscription’s immutable identity. Provider cursor traversal can produce estimated totals until exhausted. Re-queue acceptance is not proof of successful delivery or business processing. **Related guide:** [Webhooks](https://docs.travila.ai/integrations/webhooks) ### JSON conventions \{#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](https://docs.travila.ai/api). ## Endpoints \{#reference-group-1} Register and manage the URLs that receive webhook deliveries. * [Create a webhook endpoint](/api/webhooks/create-webhook-endpoint) * [List webhook endpoints](/api/webhooks/list-webhook-endpoints) * [Update a webhook endpoint](/api/webhooks/update-webhook-endpoint) * [Delete a webhook endpoint](/api/webhooks/delete-webhook-endpoint) ## Subscriptions \{#reference-group-2} Bind an endpoint to event types. One live subscription is allowed per endpoint; subscriptions on separate endpoints can receive the same event. * [Create a webhook subscription](/api/webhooks/create-webhook-subscription) * [List webhook subscriptions](/api/webhooks/list-webhook-subscriptions) * [Delete a webhook subscription](/api/webhooks/delete-webhook-subscription) ## Deliveries \{#reference-group-3} Inspect delivery records and request another attempt for eligible retained deliveries. * [List webhook event deliveries](/api/webhooks/list-webhook-deliveries) * [Retry a failed webhook delivery](/api/webhooks/retry-webhook-delivery) ## Server 1 \{#reference-server-1} Travila API [https://api.travila.ai](https://api.travila.ai) ## X-API-Key \{#authentication-apiKeyAuth} Authorized tenant backend secret key (`sk_…`). No end-user identity is needed for these tenant/project configuration operations. Keep the key out of client apps; authorization and provisioning still apply. ## Authorization: Bearer \{#authentication-bearerAuth} 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

### apiKeyAuth Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-API-Key` ### onBehalfOf Security scheme type: `apiKey` Parameter location: `header` Parameter name: `X-On-Behalf-Of` ### bearerAuth Security scheme type: `http` HTTP authorization scheme: `bearer` ## Operations - [Create a webhook endpoint](/api/webhooks/create-webhook-endpoint) — `POST /api/v1/webhooks/create-endpoint` - [List webhook endpoints](/api/webhooks/list-webhook-endpoints) — `POST /api/v1/webhooks/list-endpoints` - [Update a webhook endpoint](/api/webhooks/update-webhook-endpoint) — `POST /api/v1/webhooks/update-endpoint` - [Delete a webhook endpoint](/api/webhooks/delete-webhook-endpoint) — `POST /api/v1/webhooks/delete-endpoint` - [Create a webhook subscription](/api/webhooks/create-webhook-subscription) — `POST /api/v1/webhooks/create-subscription` - [List webhook subscriptions](/api/webhooks/list-webhook-subscriptions) — `POST /api/v1/webhooks/list-subscriptions` - [Delete a webhook subscription](/api/webhooks/delete-webhook-subscription) — `POST /api/v1/webhooks/delete-subscription` - [List webhook event deliveries](/api/webhooks/list-webhook-deliveries) — `POST /api/v1/webhooks/list-deliveries` - [Retry a failed webhook delivery](/api/webhooks/retry-webhook-delivery) — `POST /api/v1/webhooks/retry-delivery` Document ID: `DOC-API-webhooks-overview`. [Section identities and revisions](/documentation-manifest.json). - Overview: `DOC-API-webhooks-overview#overview` - Authentication: `DOC-API-webhooks-overview#authentication` - Endpoints and subscriptions: `DOC-API-webhooks-overview#endpoints-and-subscriptions` - Addressing Subscriptions: `DOC-API-webhooks-overview#addressing-subscriptions` - JSON conventions: `DOC-API-webhooks-overview#json-conventions` - Endpoints: `DOC-API-webhooks-overview#reference-group-1` - Subscriptions: `DOC-API-webhooks-overview#reference-group-2` - Deliveries: `DOC-API-webhooks-overview#reference-group-3` - Server 1: `DOC-API-webhooks-overview#reference-server-1` - X-API-Key: `DOC-API-webhooks-overview#authentication-apiKeyAuth` - Authorization: Bearer: `DOC-API-webhooks-overview#authentication-bearerAuth` --- # Domain models {#overview} URL: https://docs.travila.ai/api/models Reusable business models selected by this publication. Operation pages own their request and response bodies. A selected type describes a data shape, not endpoint availability. Open its definition for full meaning, constraints and the operations that use it. ## shared {#domain-shared} - [Account](/api/models/schema-1fd4ce3lnc) - [AgentProfile](/api/models/schema-1hmbcecg1j) - [AgentProfileLibrary](/api/models/schema-ou55jqfkih) - [AgentProfileMetadata](/api/models/schema-ohmse4h323) - [AgentProfileVersionInfo](/api/models/schema-ohrdb6rrpn) - [Annotation](/api/models/schema-1i0hjer0pd) - [AnnotationQueue](/api/models/schema-1j9496mkdg) - [AnnotationQueueItem](/api/models/schema-ovc35nr9td) - [App](/api/models/schema-oti80oaqc4) - [AppCategory](/api/models/schema-ohbp8u7c1i) - [AuthorizationModel](/api/models/schema-pq9d837o76) - [Backoff](/api/models/schema-1gqlghlp0v) - [BranchMetadata](/api/models/schema-q7dt6t9g53) - [BulkTriggerEvent](/api/models/schema-oiqb7f8bbv) - [BulkTriggerResult](/api/models/schema-oisl2i7j7o) - [ChannelRegistration](/api/models/schema-1kaqut27uf) - [ChannelToggles](/api/models/schema-oj4cvo85fs) - [ClientContext](/api/models/schema-1i2sndrl93) - [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) - [ClientToolResult](/api/models/schema-1i4kndhs46) - [Comment](/api/models/schema-ove4pre5lb) - [Compaction](/api/models/schema-1fpqunnq41) - [CompactionConfig](/api/models/schema-1hbvkcgu5m) - [CompletionTokensDetails](/api/models/schema-1i6q4qpg72) - [ContentPart](/api/models/schema-1hqi9r2bhh) - [ContextManagementSettings](/api/models/schema-1hgrvsu34j) - [ConversationBranch](/api/models/schema-q7hl8fcm9r) - [ConversationSettings](/api/models/schema-ph6avse89k) - [ConversationThread](/api/models/schema-1i84dsgmg6) - [CostDetails](/api/models/schema-1ia0h761lm) - [CursorPageInfo](/api/models/schema-oi1c4l4i8b) - [CustomMCPServer](/api/models/schema-p1cuh9jgfq) - [DailyMeetingTokenProperties](/api/models/schema-1kic2mada4) - [DailyRoomProperties](/api/models/schema-1kp6t31pq7) - [DailySession](/api/models/schema-1ktuo6mcah) - [Dataset](/api/models/schema-1ja63aqvqo) - [DatasetItem](/api/models/schema-1jcdgbb5sm) - [DatasetRun](/api/models/schema-1jehhpchdc) - [DatasetRunItem](/api/models/schema-qbff0c5l2f) - [EmbeddingConfig](/api/models/schema-q81ihe4v3e) - [Endpoint](/api/models/schema-1ffl20kv2k) - [EndUserState](/api/models/schema-1l1et4gp2i) - [ErrorDetails](/api/models/schema-1f7d7kh0s1) - [ErrorInfo](/api/models/schema-1es9uii84j) - [EvalCommentSuppressionState](/api/models/schema-qbs1n8ja02) - [EvalFilter](/api/models/schema-ovg7lvels1) - [EvalOverview](/api/models/schema-1js2bf073d) - [EvaluationPageInfo](/api/models/schema-oi3nhojaso) - [EventDelivery](/api/models/schema-1fiv947q56) - [Execution](/api/models/schema-1l7vrun3li) - [ExperimentContext](/api/models/schema-1icbr3lltu) - [FieldMask](/api/models/schema-oh20e1g6e1) - [FieldViolation](/api/models/schema-1eu5noj3g1) - [FileFilter](/api/models/schema-oq26kmqtvq) - [FileInfo](/api/models/schema-1lls6fo8p7) - [FileResolutionConfig](/api/models/schema-1ftcunpmha) - [FileUrlResult](/api/models/schema-oq46sv4kha) - [FolderInfo](/api/models/schema-opsbitjge1) - [GenerationConfig](/api/models/schema-1h82h7ri5p) - [GenerationContext](/api/models/schema-1im79fphmq) - [GlobalPreferences](/api/models/schema-p20l2ff92r) - [HelpLink](/api/models/schema-1f0qdi91b8) - [HeyGenConfig](/api/models/schema-pd3vbf0eel) - [HeyGenElevenLabsSettings](/api/models/schema-on0k8c8den) - [HeyGenVoiceSettings](/api/models/schema-p3askj7st1) - [InboxFeedFilter](/api/models/schema-ojrenemkui) - [InboxMessage](/api/models/schema-1kescd68ar) - [InboxMessageAction](/api/models/schema-1kcu6c9rot) - [InboxMessageSummary](/api/models/schema-ojt6e86adl) - [LatencyPercentileRow](/api/models/schema-1jgrpr157a) - [LLMGenerationCompletedEvent](/api/models/schema-pntuu08p80) - [LLMGenerationStartedEvent](/api/models/schema-pnv14jb39g) - [LLMMessagePublishedEvent](/api/models/schema-po1qsocerv) - [Location](/api/models/schema-1kvbjenggb) - [MCPServerConfig](/api/models/schema-q8egnnm4a3) - [MCPServerInfo](/api/models/schema-1ipatl4liq) - [MCPServerReference](/api/models/schema-1hik90rmo1) - [MCPServerStatus](/api/models/schema-ou7clc4l5s) - [Memory](/api/models/schema-1k63a85bkp) - [Memory relation](/api/models/schema-1k84aa8jbi) - [MemoryConfig](/api/models/schema-1g8iadjcu1) - [MemoryReference](/api/models/schema-1ie9a4bgk5) - [MemorySearchParams](/api/models/schema-1igd5iut01) - [Message](/api/models/schema-1j3dcf7kvu) - [MessageFeedback](/api/models/schema-1iroqctqt1) - [ModelError](/api/models/schema-1f2939tg20) - [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1) - [NamedCount](/api/models/schema-1jiel5uim6) - [ObjectRef](/api/models/schema-1lj1ellabu) - [Observation](/api/models/schema-1ju9tclufp) - [OperationStatus](/api/models/schema-ok4lj6t1ka) - [PaginationInfo](/api/models/schema-ohggnansec) - [PdfAnnotation](/api/models/schema-1hsi58i6pb) - [PendingChange](/api/models/schema-ok6l245g8f) - [PercentileThreshold](/api/models/schema-1gcuue0out) - [PipedreamPageInfo](/api/models/schema-ohepdcsvjo) - [PluginConfig](/api/models/schema-1g5jvg1icc) - [PluginPDFConfig](/api/models/schema-1fvi4j1t0d) - [PluginWebConfig](/api/models/schema-1g3q0m5uun) - [ProfileQualityRow](/api/models/schema-1jku9efe5c) - [PromotionError](/api/models/schema-okaelqap4k) - [PromptDefinition](/api/models/schema-ou94n9qv48) - [PromptFragment](/api/models/schema-1j5dvgfmr9) - [PromptParameter](/api/models/schema-ohoj3j73c1) - [PromptTokensDetails](/api/models/schema-1ivj82m55o) - [PromptVariableSpec](/api/models/schema-1hkadmq6cl) - [Provider](/api/models/enum-q8qp045fpk) - [ProviderInfo](/api/models/schema-p28bvfiqrb) - [ProviderMaxPrice](/api/models/schema-1geaq4stvt) - [ProviderPreferences](/api/models/schema-1gg690bhqh) - [ReasoningOptions](/api/models/schema-1gi26i7r89) - [ReceiveMessageRequest](/api/models/schema-q69v86pv94) - [RecordingBucketConfig](/api/models/schema-1klrt9eoq8) - [RelationReference](/api/models/schema-1ijit8ceuv) - [Resource](/api/models/schema-pbf83hf239) - [ResponseFormat](/api/models/schema-1g69v4vltg) - [RetryConfig](/api/models/schema-1fkul0p8vd) - [RetryInfo](/api/models/schema-1f439vae2d) - [RetryPolicy](/api/models/schema-1l9ki2op1i) - [RpcError](/api/models/schema-1fajlacjs0) - [Schedule](/api/models/schema-1ld0l8rmvg) - [ScheduledTriggerEnvelope](/api/models/schema-s6i1d2bv7o) - [ScheduleTarget](/api/models/schema-1lbkptb5rj) - [Score](/api/models/schema-1jm5lo00e7) - [ScoreAggregate](/api/models/schema-1jo37n9pqa) - [ScoreConfig](/api/models/schema-1k2h0fdd77) - [ScoreConfigCategory](/api/models/schema-1k0g6fhhqd) - [ScoredVector](/api/models/schema-q8s584s888) - [SecretMetadata](/api/models/schema-1lhjc44i8n) - [SecretRef](/api/models/schema-opqho625u2) - [SelectiveExclusionConfig](/api/models/schema-1hc73qpaio) - [SessionDetail](/api/models/schema-ph83s78vr5) - [SessionSummary](/api/models/schema-pbibjr8tih) - [SocayoAgentConfig](/api/models/schema-phip2o3ju4) - [SourcePromptFragment](/api/models/schema-ohqh497pal) - [SourcePromptTemplate](/api/models/schema-pjk9r8rn5b) - [SparseValues](/api/models/schema-q8ublbqo12) - [StartSessionUserData](/api/models/schema-1kri473p8r) - [StopOnFailureRule](/api/models/schema-1gstrgb39r) - [StorageManagerState](/api/models/schema-phpid7698e) - [Store](/api/models/schema-pqh3ei5p5l) - [StringValue](/api/models/schema-1fc03re4nc) - [StructuredMessage](/api/models/schema-1ho1lk4ndj) - [SubscriberData](/api/models/schema-1kgdnn5p53) - [SubscriberSummary](/api/models/schema-okk1bp39s4) - [Subscription](/api/models/schema-1fn66l17fv) - [SubscriptionFilter](/api/models/schema-1fl5depe11) - [TextDocument](/api/models/schema-q92tfl8qp2) - [ThreadSummary](/api/models/schema-p16s9mefht) - [ThresholdConfig](/api/models/schema-1frig4k431) - [TimeAwareConfig](/api/models/schema-1gkqaobt3t) - [TimeoutPolicy](/api/models/schema-1gu5od417l) - [TimeSeriesPoint](/api/models/schema-1jq6h5scn9) - [ToolApproval](/api/models/schema-1j7jbpfsda) - [ToolCall](/api/models/schema-1it6mqsqoo) - [ToolCallCompletedEvent](/api/models/schema-po3pkfshjg) - [ToolCallStartedEvent](/api/models/schema-po5rioe4il) - [ToolCategory](/api/models/enum-q97i14qn23) - [ToolChoice](/api/models/schema-1gmq0e4ilg) - [ToolDefinition](/api/models/schema-1gomaj79cc) - [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8) - [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4) - [TopicSubscriptionError](/api/models/schema-okmh5pnenu) - [TopicSubscriptionResult](/api/models/schema-p2eb0gb1ln) - [TraceDetail](/api/models/schema-pha7gtif3l) - [TraceSummary](/api/models/schema-1k4mjul65u) - [TranscriptionBucketConfig](/api/models/schema-1knm9ns9ab) - [TransportConfig](/api/models/schema-on4mqk0ok8) - [TTSConfig](/api/models/schema-on2m1c27d9) - [TupleKey](/api/models/schema-pqjdejpl2g) - [TurnContextConfig](/api/models/schema-1h5dj58uph) - [TurnInfo](/api/models/schema-1ilcikuhu8) - [UpdateWorkflowPreferenceRequest](/api/models/schema-p38aqgjs3a) - [UpstreamError](/api/models/schema-1f66rlcp5a) - [UrlCitation](/api/models/schema-1hujls61ng) - [Usage](/api/models/schema-1j1vov2uoh) - [UsageByModel](/api/models/schema-po7orad6ac) - [UsageOptions](/api/models/schema-1h615aquj0) - [UserSet](/api/models/schema-pql723cqr4) - [Vector](/api/models/schema-q9cp251mpk) - [VectorMetric](/api/models/enum-q9e32qbsm3) - [WebSearchOptions](/api/models/schema-1g1r4lmi7m) - [WindowingConfig](/api/models/schema-1he7ulevif) - [WorkflowPreferences](/api/models/schema-p2jctrvcjc) --- # Provider {#overview} URL: https://docs.travila.ai/api/models/enum-q8qp045fpk Target model provider Type-reference view: `API Enum 6tv1pafpa2`. Request and response views describe this type; they do not declare an endpoint. ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). JSON shape: `string` (`PROVIDER_OAI`, `PROVIDER_ANTHROPIC`, `PROVIDER_GOOGLE`, `PROVIDER_COHERE`, `PROVIDER_MISTRAL`) or `integer (int32)`. Target model provider
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_OAI` | 0 | Canonical | See meaning below. | | `PROVIDER_ANTHROPIC` | 1 | Canonical | See meaning below. | | `PROVIDER_GOOGLE` | 2 | Canonical | See meaning below. | | `PROVIDER_COHERE` | 3 | Canonical | See meaning below. | | `PROVIDER_MISTRAL` | 4 | Canonical | See meaning below. | **`PROVIDER_OAI`** OpenAI or an Azure OpenAI-compatible endpoint. OpenAI (incl. Azure OpenAI-compatible endpoints) **`PROVIDER_ANTHROPIC`** Anthropic's model API. Anthropic Claude models **`PROVIDER_GOOGLE`** Google's Gemini model API. Google (Gemini) **`PROVIDER_COHERE`** Cohere's model API. Cohere Command models **`PROVIDER_MISTRAL`** Mistral's model API. Mistral
## In responses {#response} API JSON uses JSON field names (camelCase). JSON shape: `string` (`PROVIDER_OAI`, `PROVIDER_ANTHROPIC`, `PROVIDER_GOOGLE`, `PROVIDER_COHERE`, `PROVIDER_MISTRAL`) or `integer (int32)`. Target model provider
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_OAI` | 0 | Canonical | See meaning below. | | `PROVIDER_ANTHROPIC` | 1 | Canonical | See meaning below. | | `PROVIDER_GOOGLE` | 2 | Canonical | See meaning below. | | `PROVIDER_COHERE` | 3 | Canonical | See meaning below. | | `PROVIDER_MISTRAL` | 4 | Canonical | See meaning below. | **`PROVIDER_OAI`** OpenAI or an Azure OpenAI-compatible endpoint. OpenAI (incl. Azure OpenAI-compatible endpoints) **`PROVIDER_ANTHROPIC`** Anthropic's model API. Anthropic Claude models **`PROVIDER_GOOGLE`** Google's Gemini model API. Google (Gemini) **`PROVIDER_COHERE`** Cohere's model API. Cohere Command models **`PROVIDER_MISTRAL`** Mistral's model API. Mistral
## Where used {#where-used} | Reference | Relationship | |---|---| | Provider | API JSON uses JSON field names (camelCase). | Download the [public reference contract](/reference/api-contract.json). --- # ToolCategory {#overview} URL: https://docs.travila.ai/api/models/enum-q97i14qn23 Tool Category for organizing and filtering tools Type-reference view: `API Enum 6u1ita10u0`. Request and response views describe this type; they do not declare an endpoint. ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). JSON shape: `string` (`TOOL_CATEGORY_SEARCH`, `TOOL_CATEGORY_FILE_SYSTEM`, `TOOL_CATEGORY_VERSION_CONTROL`, `TOOL_CATEGORY_COMMUNICATION`, `TOOL_CATEGORY_DATA_ANALYSIS`, `TOOL_CATEGORY_WEB_BROWSING`, `TOOL_CATEGORY_SYSTEM`, `TOOL_CATEGORY_DEVELOPMENT`, `TOOL_CATEGORY_UNSAFE`) or `integer (int32)`. Tool Category for organizing and filtering tools
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CATEGORY_SEARCH` | 0 | Canonical | See meaning below. | | `TOOL_CATEGORY_FILE_SYSTEM` | 1 | Canonical | See meaning below. | | `TOOL_CATEGORY_VERSION_CONTROL` | 2 | Canonical | See meaning below. | | `TOOL_CATEGORY_COMMUNICATION` | 3 | Canonical | See meaning below. | | `TOOL_CATEGORY_DATA_ANALYSIS` | 4 | Canonical | See meaning below. | | `TOOL_CATEGORY_WEB_BROWSING` | 5 | Canonical | See meaning below. | | `TOOL_CATEGORY_SYSTEM` | 6 | Canonical | See meaning below. | | `TOOL_CATEGORY_DEVELOPMENT` | 7 | Canonical | See meaning below. | | `TOOL_CATEGORY_UNSAFE` | 8 | Canonical | See meaning below. | **`TOOL_CATEGORY_SEARCH`** Search or information retrieval. Search and information retrieval **`TOOL_CATEGORY_FILE_SYSTEM`** Read or modify files and directories. File operations **`TOOL_CATEGORY_VERSION_CONTROL`** Operate on a source-control repository or hosting service. Git, GitHub, etc. **`TOOL_CATEGORY_COMMUNICATION`** Send or retrieve email or other messages. Email, messaging, etc. **`TOOL_CATEGORY_DATA_ANALYSIS`** Process, query or analyze data. Data processing and analysis **`TOOL_CATEGORY_WEB_BROWSING`** Browse or extract information from web pages. Web scraping, browsing **`TOOL_CATEGORY_SYSTEM`** Operate on system resources or commands. System operations **`TOOL_CATEGORY_DEVELOPMENT`** Support software-development work. Development tools **`TOOL_CATEGORY_UNSAFE`** A category for potentially destructive operations requiring appropriate policy controls. Potentially destructive operations
## In responses {#response} API JSON uses JSON field names (camelCase). JSON shape: `string` (`TOOL_CATEGORY_SEARCH`, `TOOL_CATEGORY_FILE_SYSTEM`, `TOOL_CATEGORY_VERSION_CONTROL`, `TOOL_CATEGORY_COMMUNICATION`, `TOOL_CATEGORY_DATA_ANALYSIS`, `TOOL_CATEGORY_WEB_BROWSING`, `TOOL_CATEGORY_SYSTEM`, `TOOL_CATEGORY_DEVELOPMENT`, `TOOL_CATEGORY_UNSAFE`) or `integer (int32)`. Tool Category for organizing and filtering tools
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CATEGORY_SEARCH` | 0 | Canonical | See meaning below. | | `TOOL_CATEGORY_FILE_SYSTEM` | 1 | Canonical | See meaning below. | | `TOOL_CATEGORY_VERSION_CONTROL` | 2 | Canonical | See meaning below. | | `TOOL_CATEGORY_COMMUNICATION` | 3 | Canonical | See meaning below. | | `TOOL_CATEGORY_DATA_ANALYSIS` | 4 | Canonical | See meaning below. | | `TOOL_CATEGORY_WEB_BROWSING` | 5 | Canonical | See meaning below. | | `TOOL_CATEGORY_SYSTEM` | 6 | Canonical | See meaning below. | | `TOOL_CATEGORY_DEVELOPMENT` | 7 | Canonical | See meaning below. | | `TOOL_CATEGORY_UNSAFE` | 8 | Canonical | See meaning below. | **`TOOL_CATEGORY_SEARCH`** Search or information retrieval. Search and information retrieval **`TOOL_CATEGORY_FILE_SYSTEM`** Read or modify files and directories. File operations **`TOOL_CATEGORY_VERSION_CONTROL`** Operate on a source-control repository or hosting service. Git, GitHub, etc. **`TOOL_CATEGORY_COMMUNICATION`** Send or retrieve email or other messages. Email, messaging, etc. **`TOOL_CATEGORY_DATA_ANALYSIS`** Process, query or analyze data. Data processing and analysis **`TOOL_CATEGORY_WEB_BROWSING`** Browse or extract information from web pages. Web scraping, browsing **`TOOL_CATEGORY_SYSTEM`** Operate on system resources or commands. System operations **`TOOL_CATEGORY_DEVELOPMENT`** Support software-development work. Development tools **`TOOL_CATEGORY_UNSAFE`** A category for potentially destructive operations requiring appropriate policy controls. Potentially destructive operations
## Where used {#where-used} | Reference | Relationship | |---|---| | ToolCategory | API JSON uses JSON field names (camelCase). | Download the [public reference contract](/reference/api-contract.json). --- # VectorMetric {#overview} URL: https://docs.travila.ai/api/models/enum-q9e32qbsm3 Distance/similarity metric for vector indexes Type-reference view: `API Enum 6u3eomk7tb`. Request and response views describe this type; they do not declare an endpoint. ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). JSON shape: `string` (`VECTOR_METRIC_COSINE`, `VECTOR_METRIC_DOT_PRODUCT`, `VECTOR_METRIC_EUCLIDEAN`) or `integer (int32)`. Distance/similarity metric for vector indexes
| Value | No. | Form | Meaning | |---|---|---|---| | `VECTOR_METRIC_COSINE` | 0 | Canonical | Compare vectors using cosine similarity. | | `VECTOR_METRIC_DOT_PRODUCT` | 1 | Canonical | Compare vectors using their dot product. | | `VECTOR_METRIC_EUCLIDEAN` | 2 | Canonical | Compare vectors using Euclidean distance. |
## In responses {#response} API JSON uses JSON field names (camelCase). JSON shape: `string` (`VECTOR_METRIC_COSINE`, `VECTOR_METRIC_DOT_PRODUCT`, `VECTOR_METRIC_EUCLIDEAN`) or `integer (int32)`. Distance/similarity metric for vector indexes
| Value | No. | Form | Meaning | |---|---|---|---| | `VECTOR_METRIC_COSINE` | 0 | Canonical | Compare vectors using cosine similarity. | | `VECTOR_METRIC_DOT_PRODUCT` | 1 | Canonical | Compare vectors using their dot product. | | `VECTOR_METRIC_EUCLIDEAN` | 2 | Canonical | Compare vectors using Euclidean distance. |
## Where used {#where-used} | Reference | Relationship | |---|---| | VectorMetric | API JSON uses JSON field names (camelCase). | Download the [public reference contract](/reference/api-contract.json). --- # ErrorInfo {#overview} URL: https://docs.travila.ai/api/models/schema-1es9uii84j Machine-readable error identification (per AIP-193, every error must include this). ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `reason` | `string` | Optional | Stable machine-readable reason string (e.g., "MODEL\_NOT\_FOUND", "RATE\_LIMITED", "MODERATION\_FLAGGED"). Unique within the domain. Clients may switch on this field. | | `domain` | `string` | Optional | Machine-readable namespace identifying the origin of the error. | | `metadata` | Map from string to `string` | Optional | Arbitrary key-value metadata. If the message field mentions a specific value (model name, field path, etc.), it MUST also appear here. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `reason` | `string` | Optional | Stable machine-readable reason string (e.g., "MODEL\_NOT\_FOUND", "RATE\_LIMITED", "MODERATION\_FLAGGED"). Unique within the domain. Clients may switch on this field. | | `domain` | `string` | Optional | Machine-readable namespace identifying the origin of the error. | | `metadata` | Map from string to `string` | Optional | Arbitrary key-value metadata. If the message field mentions a specific value (model name, field path, etc.), it MUST also appear here. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Submit client-side tool execution results](/api/conversations/submit-client-tool-results) | `POST /api/v1/llm/submit-client-tool-results` |
Models containing this value | Model | Relationship | |---|---| | [ErrorDetails](/api/models/schema-1f7d7kh0s1#response) | Nested in model | | [ErrorDetails](/api/models/schema-1f7d7kh0s1#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # FieldViolation {#overview} URL: https://docs.travila.ai/api/models/schema-1eu5noj3g1 A single field-level validation violation. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `field` | `string` | Optional | Dot-separated path to the field (e.g., "generation\_config.model"). | | `description` | `string` | Optional | Human-readable description of the violation. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `field` | `string` | Optional | Dot-separated path to the field (e.g., "generation\_config.model"). | | `description` | `string` | Optional | Human-readable description of the violation. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Submit client-side tool execution results](/api/conversations/submit-client-tool-results) | `POST /api/v1/llm/submit-client-tool-results` |
Models containing this value | Model | Relationship | |---|---| | [ErrorDetails](/api/models/schema-1f7d7kh0s1#response) | Nested in model | | [ErrorDetails](/api/models/schema-1f7d7kh0s1#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # HelpLink {#overview} URL: https://docs.travila.ai/api/models/schema-1f0qdi91b8 A help link for error resolution. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `url` | `string` | Optional | URL to documentation or resolution guide. | | `description` | `string` | Optional | Description of what the link provides. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `url` | `string` | Optional | URL to documentation or resolution guide. | | `description` | `string` | Optional | Description of what the link provides. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Submit client-side tool execution results](/api/conversations/submit-client-tool-results) | `POST /api/v1/llm/submit-client-tool-results` |
Models containing this value | Model | Relationship | |---|---| | [ErrorDetails](/api/models/schema-1f7d7kh0s1#response) | Nested in model | | [ErrorDetails](/api/models/schema-1f7d7kh0s1#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # ModelError {#overview} URL: https://docs.travila.ai/api/models/schema-1f2939tg20 Model-specific error context. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `modelId` | `string` | Optional | The model ID that caused the error. | | `reason` | `string` | Optional | Why the model failed (e.g., "invalid", "unavailable", "moderation\_flagged"). | | `alternativesTried` | Array of `string` | Optional | Alternative models that were tried or could be tried. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `modelId` | `string` | Optional | The model ID that caused the error. | | `reason` | `string` | Optional | Why the model failed (e.g., "invalid", "unavailable", "moderation\_flagged"). | | `alternativesTried` | Array of `string` | Optional | Alternative models that were tried or could be tried. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Submit client-side tool execution results](/api/conversations/submit-client-tool-results) | `POST /api/v1/llm/submit-client-tool-results` |
Models containing this value | Model | Relationship | |---|---| | [ErrorDetails](/api/models/schema-1f7d7kh0s1#response) | Nested in model | | [ErrorDetails](/api/models/schema-1f7d7kh0s1#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # RetryInfo {#overview} URL: https://docs.travila.ai/api/models/schema-1f439vae2d Retry guidance for transient errors. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `retryDelayMs` | `string (int64)` | Optional | Suggested minimum delay before retrying, in milliseconds. Pattern: `^-?\d+$`. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `retryDelayMs` | `string (int64)` | Optional | Suggested minimum delay before retrying, in milliseconds. Pattern: `^-?\d+$`. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Submit client-side tool execution results](/api/conversations/submit-client-tool-results) | `POST /api/v1/llm/submit-client-tool-results` |
Models containing this value | Model | Relationship | |---|---| | [ErrorDetails](/api/models/schema-1f7d7kh0s1#response) | Nested in model | | [ErrorDetails](/api/models/schema-1f7d7kh0s1#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # UpstreamError {#overview} URL: https://docs.travila.ai/api/models/schema-1f66rlcp5a Context from an upstream provider error, including the provider name when reported. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `provider` | `string` | Optional | Name of the upstream provider that reported the error. | | `statusCode` | `string (int64)` | Optional | HTTP status code returned by the provider. Pattern: `^-?\d+$`. | | `rawBody` | `string` | Optional | Raw error body from the provider, truncated to 512 bytes. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `provider` | `string` | Optional | Name of the upstream provider that reported the error. | | `statusCode` | `string (int64)` | Optional | HTTP status code returned by the provider. Pattern: `^-?\d+$`. | | `rawBody` | `string` | Optional | Raw error body from the provider, truncated to 512 bytes. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Submit client-side tool execution results](/api/conversations/submit-client-tool-results) | `POST /api/v1/llm/submit-client-tool-results` |
Models containing this value | Model | Relationship | |---|---| | [ErrorDetails](/api/models/schema-1f7d7kh0s1#response) | Nested in model | | [ErrorDetails](/api/models/schema-1f7d7kh0s1#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # ErrorDetails {#overview} URL: https://docs.travila.ai/api/models/schema-1f7d7kh0s1 Typed error details container. Concrete fields instead of Any for type safety across languages. At most one of each detail type. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `errorInfo` | [ErrorInfo](/api/models/schema-1es9uii84j#request) | Optional | Identifies the error for machine consumption. Required on all errors by this error contract. | | `retryInfo` | [RetryInfo](/api/models/schema-1f439vae2d#request) | Optional | Retry guidance for transient errors. | | `fieldViolations` | Array of [FieldViolation](/api/models/schema-1eu5noj3g1#request) | Optional | Field-level validation failures. | | `upstreamError` | [UpstreamError](/api/models/schema-1f66rlcp5a#request) | Optional | Upstream provider error context. | | `modelError` | [ModelError](/api/models/schema-1f2939tg20#request) | Optional | Model-specific error context. | | `helpLinks` | Array of [HelpLink](/api/models/schema-1f0qdi91b8#request) | Optional | Help links for error resolution. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `errorInfo` | [ErrorInfo](/api/models/schema-1es9uii84j#response) | Optional | Identifies the error for machine consumption. Required on all errors by this error contract. | | `retryInfo` | [RetryInfo](/api/models/schema-1f439vae2d#response) | Optional | Retry guidance for transient errors. | | `fieldViolations` | Array of [FieldViolation](/api/models/schema-1eu5noj3g1#response) | Optional | Field-level validation failures. | | `upstreamError` | [UpstreamError](/api/models/schema-1f66rlcp5a#response) | Optional | Upstream provider error context. | | `modelError` | [ModelError](/api/models/schema-1f2939tg20#response) | Optional | Model-specific error context. | | `helpLinks` | Array of [HelpLink](/api/models/schema-1f0qdi91b8#response) | Optional | Help links for error resolution. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Submit client-side tool execution results](/api/conversations/submit-client-tool-results) | `POST /api/v1/llm/submit-client-tool-results` |
Models containing this value | Model | Relationship | |---|---| | [RpcError](/api/models/schema-1fajlacjs0#response) | Nested in model | | [RpcError](/api/models/schema-1fajlacjs0#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # RpcError {#overview} URL: https://docs.travila.ai/api/models/schema-1fajlacjs0 Error payload containing an API-defined error code, a message and structured details. Interpret `code` using the ErrorCode enumeration published with this API; numeric equivalence with `google.rpc.Status` is not implied. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `code` | `string` (`ERROR_CODE_CANCELLED`, `ERROR_CODE_UNKNOWN`, `ERROR_CODE_INVALID_ARGUMENT`, `ERROR_CODE_DEADLINE_EXCEEDED`, `ERROR_CODE_NOT_FOUND`, `ERROR_CODE_ALREADY_EXISTS`, `ERROR_CODE_PERMISSION_DENIED`, `ERROR_CODE_RESOURCE_EXHAUSTED`, `ERROR_CODE_FAILED_PRECONDITION`, `ERROR_CODE_ABORTED`, `ERROR_CODE_OUT_OF_RANGE`, `ERROR_CODE_UNIMPLEMENTED`, `ERROR_CODE_INTERNAL`, `ERROR_CODE_UNAVAILABLE`, `ERROR_CODE_DATA_LOSS`, `ERROR_CODE_UNAUTHENTICATED`, `ERROR_CODE_MODEL_INVALID`, `ERROR_CODE_MODEL_UNAVAILABLE`, `ERROR_CODE_MODERATION_FLAGGED`, `ERROR_CODE_GENERATION_FAILED`, `ERROR_CODE_TOOL_EXECUTION_FAILED`, `ERROR_CODE_UPSTREAM_PROVIDER`, `ERROR_CODE_VALIDATION_EXHAUSTED`, `ERROR_CODE_PAYMENT_REQUIRED`) or `integer (int32)` | Optional; explicit presence | Machine-readable error code. Clients switch on this field. | | `message` | `string` | Optional | Human-readable error description. Intended for developers, not end users. Must not be parsed programmatically — use code and details instead. | | `isTerminal` | `boolean` | Optional | Whether this error is classified as terminal (non-retryable). A terminal error should not trigger automatic retries of the failed operation. A nonterminal error may reflect a transient condition that can resolve on retry. | | `details` | [ErrorDetails](/api/models/schema-1f7d7kh0s1#request) | Optional | Structured error details. At most one of each detail type. | ### Values of `code` {#request-values-code} API-defined categories describing why a request or operation failed. Use the published symbolic name and accompanying error details. These numeric assignments are not interchangeable with `google.rpc.Code`.
| Value | No. | Form | Meaning | |---|---|---|---| | `ERROR_CODE_CANCELLED` | 0 | Canonical | See meaning below. | | `ERROR_CODE_UNKNOWN` | 1 | Canonical | See meaning below. | | `ERROR_CODE_INVALID_ARGUMENT` | 2 | Canonical | See meaning below. | | `ERROR_CODE_DEADLINE_EXCEEDED` | 3 | Canonical | See meaning below. | | `ERROR_CODE_NOT_FOUND` | 4 | Canonical | See meaning below. | | `ERROR_CODE_ALREADY_EXISTS` | 5 | Canonical | See meaning below. | | `ERROR_CODE_PERMISSION_DENIED` | 6 | Canonical | See meaning below. | | `ERROR_CODE_RESOURCE_EXHAUSTED` | 7 | Canonical | See meaning below. | | `ERROR_CODE_FAILED_PRECONDITION` | 8 | Canonical | See meaning below. | | `ERROR_CODE_ABORTED` | 9 | Canonical | See meaning below. | | `ERROR_CODE_OUT_OF_RANGE` | 10 | Canonical | See meaning below. | | `ERROR_CODE_UNIMPLEMENTED` | 11 | Canonical | See meaning below. | | `ERROR_CODE_INTERNAL` | 12 | Canonical | See meaning below. | | `ERROR_CODE_UNAVAILABLE` | 13 | Canonical | See meaning below. | | `ERROR_CODE_DATA_LOSS` | 14 | Canonical | See meaning below. | | `ERROR_CODE_UNAUTHENTICATED` | 15 | Canonical | See meaning below. | | `ERROR_CODE_MODEL_INVALID` | 16 | Canonical | See meaning below. | | `ERROR_CODE_MODEL_UNAVAILABLE` | 17 | Canonical | See meaning below. | | `ERROR_CODE_MODERATION_FLAGGED` | 18 | Canonical | See meaning below. | | `ERROR_CODE_GENERATION_FAILED` | 19 | Canonical | See meaning below. | | `ERROR_CODE_TOOL_EXECUTION_FAILED` | 20 | Canonical | See meaning below. | | `ERROR_CODE_UPSTREAM_PROVIDER` | 21 | Canonical | See meaning below. | | `ERROR_CODE_VALIDATION_EXHAUSTED` | 22 | Canonical | See meaning below. | | `ERROR_CODE_PAYMENT_REQUIRED` | 23 | Canonical | See meaning below. | **`ERROR_CODE_CANCELLED`** The caller cancelled the operation before it completed. Canonical error categories. 499 — Cancelled by caller **`ERROR_CODE_UNKNOWN`** The operation failed without a more specific error classification. 500 — Unknown error **`ERROR_CODE_INVALID_ARGUMENT`** The request contains an invalid argument or field value. 400 — Bad input, invalid field values **`ERROR_CODE_DEADLINE_EXCEEDED`** The operation did not complete before its deadline. 504 — Operation timed out **`ERROR_CODE_NOT_FOUND`** The requested resource does not exist or could not be found. 404 — Resource does not exist **`ERROR_CODE_ALREADY_EXISTS`** The requested creation conflicts with a resource that already exists. 409 — Resource already exists **`ERROR_CODE_PERMISSION_DENIED`** The authenticated caller is not permitted to perform the operation. 403 — Caller lacks permission **`ERROR_CODE_RESOURCE_EXHAUSTED`** A quota, rate limit or other capacity limit prevented the operation. 429 — Rate limited or quota exceeded **`ERROR_CODE_FAILED_PRECONDITION`** The operation requires a system or resource state that is not currently satisfied. 400 — System not in required state **`ERROR_CODE_ABORTED`** The operation was aborted, for example by a concurrent modification conflict. 409 — Concurrent conflict, retry may succeed **`ERROR_CODE_OUT_OF_RANGE`** An argument is outside the range supported by this operation. 400 — Value outside valid range **`ERROR_CODE_UNIMPLEMENTED`** The requested operation is not implemented. 501 — Not implemented **`ERROR_CODE_INTERNAL`** An internal failure prevented the operation from completing. 500 — Internal error **`ERROR_CODE_UNAVAILABLE`** The service or a required dependency is temporarily unavailable. 503 — Service temporarily unavailable **`ERROR_CODE_DATA_LOSS`** The operation encountered unrecoverable loss or corruption of data. 500 — Unrecoverable data loss **`ERROR_CODE_UNAUTHENTICATED`** Authentication credentials are missing or invalid. 401 — Missing or invalid credentials **`ERROR_CODE_MODEL_INVALID`** The requested model identifier is absent from the model catalog. Domain-specific error categories. 400 — Model ID not found in catalog **`ERROR_CODE_MODEL_UNAVAILABLE`** The model exists, but no provider is currently available to serve it. 503 — Model exists but all providers are down **`ERROR_CODE_MODERATION_FLAGGED`** Content moderation flagged the submitted content. 403 — Input flagged by content moderation **`ERROR_CODE_GENERATION_FAILED`** Model generation failed after its configured attempts. 500 — LLM generation failed after retries **`ERROR_CODE_TOOL_EXECUTION_FAILED`** Execution of a requested tool failed. 500 — MCP tool call failed **`ERROR_CODE_UPSTREAM_PROVIDER`** An upstream model provider returned an error. 503 — Upstream provider returned error **`ERROR_CODE_VALIDATION_EXHAUSTED`** Structured-output validation still failed after the configured attempts. 500 — Structured output validation failed after all retries **`ERROR_CODE_PAYMENT_REQUIRED`** The account lacks the credits required for the operation. 402 — Insufficient credits
## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `code` | `string` (`ERROR_CODE_CANCELLED`, `ERROR_CODE_UNKNOWN`, `ERROR_CODE_INVALID_ARGUMENT`, `ERROR_CODE_DEADLINE_EXCEEDED`, `ERROR_CODE_NOT_FOUND`, `ERROR_CODE_ALREADY_EXISTS`, `ERROR_CODE_PERMISSION_DENIED`, `ERROR_CODE_RESOURCE_EXHAUSTED`, `ERROR_CODE_FAILED_PRECONDITION`, `ERROR_CODE_ABORTED`, `ERROR_CODE_OUT_OF_RANGE`, `ERROR_CODE_UNIMPLEMENTED`, `ERROR_CODE_INTERNAL`, `ERROR_CODE_UNAVAILABLE`, `ERROR_CODE_DATA_LOSS`, `ERROR_CODE_UNAUTHENTICATED`, `ERROR_CODE_MODEL_INVALID`, `ERROR_CODE_MODEL_UNAVAILABLE`, `ERROR_CODE_MODERATION_FLAGGED`, `ERROR_CODE_GENERATION_FAILED`, `ERROR_CODE_TOOL_EXECUTION_FAILED`, `ERROR_CODE_UPSTREAM_PROVIDER`, `ERROR_CODE_VALIDATION_EXHAUSTED`, `ERROR_CODE_PAYMENT_REQUIRED`) or `integer (int32)` | Optional; explicit presence | Machine-readable error code. Clients switch on this field. | | `message` | `string` | Optional | Human-readable error description. Intended for developers, not end users. Must not be parsed programmatically — use code and details instead. | | `isTerminal` | `boolean` | Optional | Whether this error is classified as terminal (non-retryable). A terminal error should not trigger automatic retries of the failed operation. A nonterminal error may reflect a transient condition that can resolve on retry. | | `details` | [ErrorDetails](/api/models/schema-1f7d7kh0s1#response) | Optional | Structured error details. At most one of each detail type. | ### Values of `code` {#response-values-code} API-defined categories describing why a request or operation failed. Use the published symbolic name and accompanying error details. These numeric assignments are not interchangeable with `google.rpc.Code`.
| Value | No. | Form | Meaning | |---|---|---|---| | `ERROR_CODE_CANCELLED` | 0 | Canonical | See meaning below. | | `ERROR_CODE_UNKNOWN` | 1 | Canonical | See meaning below. | | `ERROR_CODE_INVALID_ARGUMENT` | 2 | Canonical | See meaning below. | | `ERROR_CODE_DEADLINE_EXCEEDED` | 3 | Canonical | See meaning below. | | `ERROR_CODE_NOT_FOUND` | 4 | Canonical | See meaning below. | | `ERROR_CODE_ALREADY_EXISTS` | 5 | Canonical | See meaning below. | | `ERROR_CODE_PERMISSION_DENIED` | 6 | Canonical | See meaning below. | | `ERROR_CODE_RESOURCE_EXHAUSTED` | 7 | Canonical | See meaning below. | | `ERROR_CODE_FAILED_PRECONDITION` | 8 | Canonical | See meaning below. | | `ERROR_CODE_ABORTED` | 9 | Canonical | See meaning below. | | `ERROR_CODE_OUT_OF_RANGE` | 10 | Canonical | See meaning below. | | `ERROR_CODE_UNIMPLEMENTED` | 11 | Canonical | See meaning below. | | `ERROR_CODE_INTERNAL` | 12 | Canonical | See meaning below. | | `ERROR_CODE_UNAVAILABLE` | 13 | Canonical | See meaning below. | | `ERROR_CODE_DATA_LOSS` | 14 | Canonical | See meaning below. | | `ERROR_CODE_UNAUTHENTICATED` | 15 | Canonical | See meaning below. | | `ERROR_CODE_MODEL_INVALID` | 16 | Canonical | See meaning below. | | `ERROR_CODE_MODEL_UNAVAILABLE` | 17 | Canonical | See meaning below. | | `ERROR_CODE_MODERATION_FLAGGED` | 18 | Canonical | See meaning below. | | `ERROR_CODE_GENERATION_FAILED` | 19 | Canonical | See meaning below. | | `ERROR_CODE_TOOL_EXECUTION_FAILED` | 20 | Canonical | See meaning below. | | `ERROR_CODE_UPSTREAM_PROVIDER` | 21 | Canonical | See meaning below. | | `ERROR_CODE_VALIDATION_EXHAUSTED` | 22 | Canonical | See meaning below. | | `ERROR_CODE_PAYMENT_REQUIRED` | 23 | Canonical | See meaning below. | **`ERROR_CODE_CANCELLED`** The caller cancelled the operation before it completed. Canonical error categories. 499 — Cancelled by caller **`ERROR_CODE_UNKNOWN`** The operation failed without a more specific error classification. 500 — Unknown error **`ERROR_CODE_INVALID_ARGUMENT`** The request contains an invalid argument or field value. 400 — Bad input, invalid field values **`ERROR_CODE_DEADLINE_EXCEEDED`** The operation did not complete before its deadline. 504 — Operation timed out **`ERROR_CODE_NOT_FOUND`** The requested resource does not exist or could not be found. 404 — Resource does not exist **`ERROR_CODE_ALREADY_EXISTS`** The requested creation conflicts with a resource that already exists. 409 — Resource already exists **`ERROR_CODE_PERMISSION_DENIED`** The authenticated caller is not permitted to perform the operation. 403 — Caller lacks permission **`ERROR_CODE_RESOURCE_EXHAUSTED`** A quota, rate limit or other capacity limit prevented the operation. 429 — Rate limited or quota exceeded **`ERROR_CODE_FAILED_PRECONDITION`** The operation requires a system or resource state that is not currently satisfied. 400 — System not in required state **`ERROR_CODE_ABORTED`** The operation was aborted, for example by a concurrent modification conflict. 409 — Concurrent conflict, retry may succeed **`ERROR_CODE_OUT_OF_RANGE`** An argument is outside the range supported by this operation. 400 — Value outside valid range **`ERROR_CODE_UNIMPLEMENTED`** The requested operation is not implemented. 501 — Not implemented **`ERROR_CODE_INTERNAL`** An internal failure prevented the operation from completing. 500 — Internal error **`ERROR_CODE_UNAVAILABLE`** The service or a required dependency is temporarily unavailable. 503 — Service temporarily unavailable **`ERROR_CODE_DATA_LOSS`** The operation encountered unrecoverable loss or corruption of data. 500 — Unrecoverable data loss **`ERROR_CODE_UNAUTHENTICATED`** Authentication credentials are missing or invalid. 401 — Missing or invalid credentials **`ERROR_CODE_MODEL_INVALID`** The requested model identifier is absent from the model catalog. Domain-specific error categories. 400 — Model ID not found in catalog **`ERROR_CODE_MODEL_UNAVAILABLE`** The model exists, but no provider is currently available to serve it. 503 — Model exists but all providers are down **`ERROR_CODE_MODERATION_FLAGGED`** Content moderation flagged the submitted content. 403 — Input flagged by content moderation **`ERROR_CODE_GENERATION_FAILED`** Model generation failed after its configured attempts. 500 — LLM generation failed after retries **`ERROR_CODE_TOOL_EXECUTION_FAILED`** Execution of a requested tool failed. 500 — MCP tool call failed **`ERROR_CODE_UPSTREAM_PROVIDER`** An upstream model provider returned an error. 503 — Upstream provider returned error **`ERROR_CODE_VALIDATION_EXHAUSTED`** Structured-output validation still failed after the configured attempts. 500 — Structured output validation failed after all retries **`ERROR_CODE_PAYMENT_REQUIRED`** The account lacks the credits required for the operation. 402 — Insufficient credits
## Where used {#where-used} | Reference | Relationship | |---|---| | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Submit client-side tool execution results](/api/conversations/submit-client-tool-results) | `POST /api/v1/llm/submit-client-tool-results` |
Models containing this value | Model | Relationship | |---|---| | [ClientToolResult](/api/models/schema-1i4kndhs46#request) | Nested in model | | [LLMGenerationCompletedEvent](/api/models/schema-pntuu08p80#response) | Nested in model | | [LLMGenerationCompletedEvent](/api/models/schema-pntuu08p80#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # StringValue {#overview} URL: https://docs.travila.ai/api/models/schema-1fc03re4nc Standard JSON representation of this value. Type-reference view: `API Schema 6282cia2fj`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} Wrapper message for `string`. The JSON representation for `StringValue` is JSON string. Not recommended for use in new APIs, but still useful for legacy APIs. Use the published contract view for this imported type’s scalar and null representation. A declaration containing a text field does not by itself imply ordinary object encoding. ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). JSON shape: `string`. ## In responses {#response} API JSON uses JSON field names (camelCase). JSON shape: `string`. ## Where used {#where-used} | Reference | Relationship | |---|---| | StringValue | API JSON uses JSON field names (camelCase). | Download the [public reference contract](/reference/api-contract.json). --- # Account {#overview} URL: https://docs.travila.ai/api/models/schema-1fd4ce3lnc Connected account (external user's OAuth connection to an app) ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | Optional | Unique account ID. | | `name` | `string` | Optional | Display name (e.g., user's email or handle). | | `externalUserId` | `string` | Optional | Your application's user ID. | | `healthy` | `boolean` | Optional | Whether the account credentials are valid. | | `app` | `string` | Optional | See meaning below. | | `oauthAppId` | `string` | Optional | OAuth app identifier (if applicable). | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | | `updatedAt` | `string (date-time)` | Optional | Time when this record was last updated. | | `credentialsLastRefreshedAt` | `string (date-time)` | Optional | Time when the connected account credentials were last refreshed. | | `credentialsExpiresAt` | `string (date-time)` | Optional | Expiration time reported for the connected account credentials. | | `error` | `string` | Optional | Error message if unhealthy. | | `lastRefreshedAt` | `string (date-time)` | Optional | ISO 8601 when credentials were last refreshed. | | `nextRefreshAt` | `string (date-time)` | Optional | ISO 8601 when credentials will next be refreshed. | **`app`** Pipedream application selected by the request or returned by the provider. App name\_slug ## Where used {#where-used} | Reference | Relationship | |---|---| | [List the caller's connected accounts](/api/connected-apps/pipedream-list-accounts-for-current-user) | `POST /api/v1/integrations/pipedream/list-accounts` | Download the [public reference contract](/reference/api-contract.json). - [connected-apps OpenAPI](/connected-apps.yaml) --- # Endpoint {#overview} URL: https://docs.travila.ai/api/models/schema-1ffl20kv2k Provider record describing a webhook delivery destination and its delivery settings. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | Optional | Identifier of the endpoint record. | | `name` | `string` | Optional | Display name of the webhook delivery destination. | | `url` | `string` | Optional | URL of the webhook delivery destination. | | `description` | `string` | Optional | Human-readable description of the resource. | | `status` | `string` (`ENDPOINT_STATUS_ACTIVE`, `ENDPOINT_STATUS_INACTIVE`, `ENDPOINT_STATUS_PAUSED`, `ENDPOINT_STATUS_PENDING`) or `integer (int32)` | Optional; explicit presence | Current state of the webhook endpoint. | | `secret` | `string` | Optional | Secret associated with the webhook endpoint. | | `httpTimeout` | `string (int64)` | Optional | Timeout for an individual webhook HTTP delivery, in seconds. Pattern: `^-?\d+$`. | | `rateLimit` | `string (int64)` | Optional | Maximum delivery rate configured for the webhook endpoint. Pattern: `^-?\d+$`. | | `rateLimitDuration` | `string` | Optional | Delivery-rate window returned as a seconds-suffixed duration string (for example, 60s). | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | | `updatedAt` | `string (date-time)` | Optional | Time when this record was last updated. | ### Values of `status` {#response-values-status} Enums Lifecycle condition reported for a webhook delivery endpoint.
| Value | No. | Form | Meaning | |---|---|---|---| | `ENDPOINT_STATUS_ACTIVE` | 0 | Canonical | The endpoint is marked active for webhook delivery. | | `ENDPOINT_STATUS_INACTIVE` | 1 | Canonical | The endpoint is marked inactive by the delivery backend. | | `ENDPOINT_STATUS_PAUSED` | 2 | Canonical | Delivery to the endpoint is paused. | | `ENDPOINT_STATUS_PENDING` | 3 | Canonical | The endpoint is pending activation in the delivery backend. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a webhook endpoint](/api/webhooks/create-webhook-endpoint) | `POST /api/v1/webhooks/create-endpoint` | | [List webhook endpoints](/api/webhooks/list-webhook-endpoints) | `POST /api/v1/webhooks/list-endpoints` | | [Update a webhook endpoint](/api/webhooks/update-webhook-endpoint) | `POST /api/v1/webhooks/update-endpoint` | Download the [public reference contract](/reference/api-contract.json). - [webhooks OpenAPI](/webhooks.yaml) --- # EventDelivery {#overview} URL: https://docs.travila.ai/api/models/schema-1fiv947q56 Delivery-attempt state and response information for a webhook event. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | Optional | Identifier of the event delivery record. | | `eventId` | `string` | Optional | Identifier of the webhook event being delivered. | | `endpointId` | `string` | Optional | Identifier of the webhook endpoint receiving deliveries. | | `status` | `string` (`DELIVERY_STATUS_SCHEDULED`, `DELIVERY_STATUS_PROCESSING`, `DELIVERY_STATUS_COMPLETED`, `DELIVERY_STATUS_RETRY`, `DELIVERY_STATUS_FAILED`, `DELIVERY_STATUS_DISCARDED`) or `integer (int32)` | Optional; explicit presence | Current delivery status reported for this webhook event attempt. | | `attempts` | `string (int64)` | Optional | Number of delivery attempts reported for the webhook event. Pattern: `^-?\d+$`. | | `eventType` | `string` | Optional | Type of the webhook event represented by this delivery. | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | | `updatedAt` | `string (date-time)` | Optional | Time when this record was last updated. | | `httpStatus` | `string (int64)` | Optional | HTTP response status reported for the delivery attempt. Pattern: `^-?\d+$`. | | `responseData` | `string` | Optional | Response body reported by the webhook delivery target. | | `error` | `string` | Optional | Error information reported for this operation or item. | ### Values of `status` {#response-values-status} Current delivery state of a webhook event sent to an endpoint.
| Value | No. | Form | Meaning | |---|---|---|---| | `DELIVERY_STATUS_SCHEDULED` | 0 | Canonical | The delivery is scheduled and waiting for processing. | | `DELIVERY_STATUS_PROCESSING` | 1 | Canonical | The delivery backend is processing a delivery attempt. | | `DELIVERY_STATUS_COMPLETED` | 2 | Canonical | See meaning below. | | `DELIVERY_STATUS_RETRY` | 3 | Canonical | The delivery is awaiting another attempt after a retryable failure. | | `DELIVERY_STATUS_FAILED` | 4 | Canonical | The delivery is reported as failed by the backend. | | `DELIVERY_STATUS_DISCARDED` | 5 | Canonical | The delivery backend discarded the event instead of completing delivery. | **`DELIVERY_STATUS_COMPLETED`** The webhook delivery completed successfully. Terminal.
## Where used {#where-used} | Reference | Relationship | |---|---| | [List webhook event deliveries](/api/webhooks/list-webhook-deliveries) | `POST /api/v1/webhooks/list-deliveries` | | [Retry a failed webhook delivery](/api/webhooks/retry-webhook-delivery) | `POST /api/v1/webhooks/retry-delivery` | Download the [public reference contract](/reference/api-contract.json). - [webhooks OpenAPI](/webhooks.yaml) --- # RetryConfig {#overview} URL: https://docs.travila.ai/api/models/schema-1fkul0p8vd Retry strategy, attempt limit, and interval for failed webhook deliveries. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `strategy` | `string` (`RETRY_STRATEGY_LINEAR`, `RETRY_STRATEGY_EXPONENTIAL`) or `integer (int32)` | Optional; explicit presence | Webhook retry strategy selected in the provider configuration. | | `retryCount` | `string (int64)` | Optional | Maximum retry count configured for webhook delivery. Pattern: `^-?\d+$`. | | `intervalSeconds` | `string (int64)` | Optional | Delay between webhook delivery retries, in seconds. Pattern: `^-?\d+$`. | ### Values of `strategy` {#response-values-strategy} Backoff strategy applied between webhook delivery attempts.
| Value | No. | Form | Meaning | |---|---|---|---| | `RETRY_STRATEGY_LINEAR` | 0 | Canonical | Retry using the configured linear interval strategy. | | `RETRY_STRATEGY_EXPONENTIAL` | 1 | Canonical | Increase the delay between retries using exponential backoff. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a webhook endpoint](/api/webhooks/create-webhook-endpoint) | `POST /api/v1/webhooks/create-endpoint` | | [Create a webhook subscription](/api/webhooks/create-webhook-subscription) | `POST /api/v1/webhooks/create-subscription` | | [List webhook subscriptions](/api/webhooks/list-webhook-subscriptions) | `POST /api/v1/webhooks/list-subscriptions` |
Models containing this value | Model | Relationship | |---|---| | [Subscription](/api/models/schema-1fn66l17fv#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [webhooks OpenAPI](/webhooks.yaml) --- # SubscriptionFilter {#overview} URL: https://docs.travila.ai/api/models/schema-1fl5depe11 Event-body and header conditions selecting webhook events for a subscription. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `body` | Map from string to `string` | Optional | Event-body matching rules used by the webhook subscription filter. | | `headers` | Map from string to `string` | Optional | Header-matching rules used to select events for the webhook subscription. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a webhook endpoint](/api/webhooks/create-webhook-endpoint) | `POST /api/v1/webhooks/create-endpoint` | | [Create a webhook subscription](/api/webhooks/create-webhook-subscription) | `POST /api/v1/webhooks/create-subscription` | | [List webhook subscriptions](/api/webhooks/list-webhook-subscriptions) | `POST /api/v1/webhooks/list-subscriptions` |
Models containing this value | Model | Relationship | |---|---| | [Subscription](/api/models/schema-1fn66l17fv#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [webhooks OpenAPI](/webhooks.yaml) --- # Subscription {#overview} URL: https://docs.travila.ai/api/models/schema-1fn66l17fv Webhook event selection and retry settings associated with an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | Optional | Identifier of the subscription record. | | `name` | `string` | Optional | Display name of the webhook event subscription. | | `endpointId` | `string` | Optional | Identifier of the webhook endpoint receiving deliveries. | | `eventTypes` | Array of `string` | Optional | Event type names selected for the webhook subscription. | | `filter` | [SubscriptionFilter](/api/models/schema-1fl5depe11#response) | Optional | Event-body and header conditions used to select webhook events for this subscription. | | `retryConfig` | [RetryConfig](/api/models/schema-1fkul0p8vd#response) | Optional | Retry policy applied to the webhook subscription. | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | | `externalId` | `string` | Optional | Client-supplied external subscription identifier. Empty when none was supplied. | | `updatedAt` | `string (date-time)` | Optional | Time when this record was last updated; equals created\_at until the first accepted update. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a webhook endpoint](/api/webhooks/create-webhook-endpoint) | `POST /api/v1/webhooks/create-endpoint` | | [Create a webhook subscription](/api/webhooks/create-webhook-subscription) | `POST /api/v1/webhooks/create-subscription` | | [List webhook subscriptions](/api/webhooks/list-webhook-subscriptions) | `POST /api/v1/webhooks/list-subscriptions` | Download the [public reference contract](/reference/api-contract.json). - [webhooks OpenAPI](/webhooks.yaml) --- # Compaction {#overview} URL: https://docs.travila.ai/api/models/schema-1fpqunnq41 Compaction metadata ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | Optional | Identifier of the compaction record. | | `startSequence` | `string (int64)` | Optional | Sequence number of the first conversation message represented by the compaction. Pattern: `^-?\d+$`. | | `endSequence` | `string (int64)` | Optional | Sequence number of the last conversation message represented by the compaction. Pattern: `^-?\d+$`. | | `summary` | `string` | Optional | Summary text produced by conversation compaction. | | `originalTokenCount` | `string (int64)` | Optional | Estimated token count of the context before compaction. Pattern: `^-?\d+$`. | | `summaryTokenCount` | `string (int64)` | Optional | Estimated token count of the generated summary. Pattern: `^-?\d+$`. | | `modelUsed` | `string` | Optional | Model identifier used for the context compaction. | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | | `status` | `string` (`COMPACTION_STATUS_PENDING`, `COMPACTION_STATUS_COMPLETED`, `COMPACTION_STATUS_FAILED`) or `integer (int32)` | Optional; explicit presence | Execution state of the conversation compaction. | | `triggerReason` | `string` (`COMPACTION_TRIGGER_REASON_THRESHOLD_EXCEEDED`, `COMPACTION_TRIGGER_REASON_MANUAL`) or `integer (int32)` | Optional; explicit presence | Reason for triggering this compaction (auto threshold vs manual) | ### Values of `status` {#response-values-status} Execution state of a conversation context-compaction attempt.
| Value | No. | Form | Meaning | |---|---|---|---| | `COMPACTION_STATUS_PENDING` | 0 | Canonical | Compaction was started and its result is still pending. | | `COMPACTION_STATUS_COMPLETED` | 1 | Canonical | Compaction completed and produced its result. | | `COMPACTION_STATUS_FAILED` | 2 | Canonical | Compaction failed; inspect the associated error. |
### Values of `triggerReason` {#response-values-triggerreason} Compaction Events Reason a conversation context-compaction attempt was started.
| Value | No. | Form | Meaning | |---|---|---|---| | `COMPACTION_TRIGGER_REASON_THRESHOLD_EXCEEDED` | 0 | Canonical | Context usage crossed the configured compaction threshold. | | `COMPACTION_TRIGGER_REASON_MANUAL` | 1 | Canonical | A caller explicitly requested compaction. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # ThresholdConfig {#overview} URL: https://docs.travila.ai/api/models/schema-1frig4k431 Threshold configuration for triggering compaction token\_count and percentage are mutually exclusive alternatives. Independent tracked fields do not enforce this relationship. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `tokenCount` | `string (int64)` | Optional; explicit presence | Absolute token limit. Pattern: `^-?\d+$`. | | `percentage` | `string (int64)` | Optional; explicit presence | % of model's context window. Pattern: `^-?\d+$`. | ## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | Message | `native.group.compaction_threshold` | Threshold configuration for triggering compaction | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `tokenCount` | `string (int64)` | Optional; explicit presence | Absolute token limit. Pattern: `^-?\d+$`. | | `percentage` | `string (int64)` | Optional; explicit presence | % of model's context window. Pattern: `^-?\d+$`. | ## Request validation {#response-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | Message | `native.group.compaction_threshold` | Threshold configuration for triggering compaction | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` |
Models containing this value | Model | Relationship | |---|---| | [CompactionConfig](/api/models/schema-1hbvkcgu5m#response) | Nested in model | | [CompactionConfig](/api/models/schema-1hbvkcgu5m#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # FileResolutionConfig {#overview} URL: https://docs.travila.ai/api/models/schema-1ftcunpmha Configuration for resolving CONTENT\_PART\_TYPE\_FILE\_ID parts to fresh signed URLs before requests are sent to LLM providers. Keeps stable file references in message history while generating ephemeral URLs only when needed. Omitting the file-resolution failure mode uses `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`, which silently drops an unresolvable part. A resolved URL can also expire before a later attempt; a fresh URL on every attempt is not guaranteed. With `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, an unresolvable required part fails the run before the provider call. This can happen after asynchronous send acceptance; inspect the correlated run outcome rather than expecting the initial HTTP response to report the later failure. Verify that the report was actually available before presenting its summary. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `failureMode` | `string` (`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`) or `integer (int32)` | Optional; explicit presence | Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. | ### Values of `failureMode` {#request-values-failuremode} How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `failureMode` | `string` (`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`, `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`) or `integer (int32)` | Optional; explicit presence | Action to take when a file cannot be resolved. If omitted, skip unresolved file content and use the remaining content. | ### Values of `failureMode` {#response-values-failuremode} How generation handles a content part whose file identifier cannot be resolved.
| Value | No. | Form | Meaning | |---|---|---|---| | `FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION` | 0 | Canonical | See meaning below. | | `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 1 | Canonical | See meaning below. | **`FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION`** Fail generation when a file content part cannot be resolved. Fail the entire generation if any file resolution fails. **`FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT`** Skip the unresolved content part and continue with the remaining content. Skip failed content parts and proceed with available content (graceful degradation).
## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [GenerationConfig](/api/models/schema-1h82h7ri5p#response) | Nested in model | | [GenerationConfig](/api/models/schema-1h82h7ri5p#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # PluginPDFConfig {#overview} URL: https://docs.travila.ai/api/models/schema-1fvi4j1t0d Plugins for pre/post-processing (generic representation) Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `engine` | `string` | Optional | See meaning below. | **`engine`** PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `engine` | `string` | Optional | See meaning below. | **`engine`** PDF parsing engine selected for the provider plugin. "pdf-text", "mistral-ocr", or "native" ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [PluginConfig](/api/models/schema-1g5jvg1icc#response) | Nested in model | | [PluginConfig](/api/models/schema-1g5jvg1icc#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # WebSearchOptions {#overview} URL: https://docs.travila.ai/api/models/schema-1g1r4lmi7m Amount of web-search context requested for generation. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `searchContextSize` | `string` | Optional | See meaning below. | **`searchContextSize`** Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `searchContextSize` | `string` | Optional | See meaning below. | **`searchContextSize`** Requested amount of web-search context: low, medium, or high. "low" | "medium" | "high" ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [PluginWebConfig](/api/models/schema-1g3q0m5uun#response) | Nested in model | | [PluginWebConfig](/api/models/schema-1g3q0m5uun#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # PluginWebConfig {#overview} URL: https://docs.travila.ai/api/models/schema-1g3q0m5uun Provider web-search configuration used to augment a generation request. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `engine` | `string` | Optional | See meaning below. | | `maxResults` | `string (int64)` | Optional | Maximum web-search result count requested by the plugin. Pattern: `^-?\d+$`. | | `searchPrompt` | `string` | Optional | Instructions supplied to the web-search plugin. | | `webSearchOptions` | [WebSearchOptions](/api/models/schema-1g1r4lmi7m#request) | Optional | Options controlling the amount of web-search context requested. | **`engine`** Search engine selected for the provider’s web-search plugin. e.g., native/exa ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `engine` | `string` | Optional | See meaning below. | | `maxResults` | `string (int64)` | Optional | Maximum web-search result count requested by the plugin. Pattern: `^-?\d+$`. | | `searchPrompt` | `string` | Optional | Instructions supplied to the web-search plugin. | | `webSearchOptions` | [WebSearchOptions](/api/models/schema-1g1r4lmi7m#response) | Optional | Options controlling the amount of web-search context requested. | **`engine`** Search engine selected for the provider’s web-search plugin. e.g., native/exa ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [PluginConfig](/api/models/schema-1g5jvg1icc#response) | Nested in model | | [PluginConfig](/api/models/schema-1g5jvg1icc#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # PluginConfig {#overview} URL: https://docs.travila.ai/api/models/schema-1g5jvg1icc Provider plugin identifier and its parser, search, or additional configuration. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | Optional | See meaning below. | | `pdf` | [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#request) | Optional | PDF annotation or parser configuration selected by the enclosing message. | | `web` | [PluginWebConfig](/api/models/schema-1g3q0m5uun#request) | Optional | Web-search configuration for the selected generation plugin. | | `params` | Map from string to `string` | Optional | Additional provider-specific plugin parameters. | **`id`** Provider plugin identifier, such as file-parser. e.g., "file-parser" ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | Optional | See meaning below. | | `pdf` | [PluginPDFConfig](/api/models/schema-1fvi4j1t0d#response) | Optional | PDF annotation or parser configuration selected by the enclosing message. | | `web` | [PluginWebConfig](/api/models/schema-1g3q0m5uun#response) | Optional | Web-search configuration for the selected generation plugin. | | `params` | Map from string to `string` | Optional | Additional provider-specific plugin parameters. | **`id`** Provider plugin identifier, such as file-parser. e.g., "file-parser" ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [GenerationConfig](/api/models/schema-1h82h7ri5p#response) | Nested in model | | [GenerationConfig](/api/models/schema-1h82h7ri5p#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # ResponseFormat {#overview} URL: https://docs.travila.ai/api/models/schema-1g69v4vltg Structured response control When a schema is set, current server validation defaults to enabled unless explicitly disabled. An explicit retry count of zero disables validation retries; omission defaults to one. A retry can incur another model attempt and cost. A schema name is a label, not an immutable schema version. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `jsonObject` | `boolean` | Optional | See meaning below. | | `jsonSchema` | Map from string to JSON value | Optional | See meaning below. | | `schemaName` | `string` | Optional | Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. | | `validate` | `boolean` | Optional; explicit presence | Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). | | `maxValidationRetries` | `string (int64)` | Optional; explicit presence | Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: `^-?\d+$`. | | `responseHealing` | `boolean` | Optional; explicit presence | Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. | **`jsonObject`** Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **`jsonSchema`** JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) ## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `maxValidationRetries` | At most | `3` | | `maxValidationRetries` | At least | `0` | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `jsonObject` | `boolean` | Optional | See meaning below. | | `jsonSchema` | Map from string to JSON value | Optional | See meaning below. | | `schemaName` | `string` | Optional | Human-readable name of the structured-output schema, included in structured-message metadata and in the provider request’s json\_schema.name. | | `validate` | `boolean` | Optional; explicit presence | Enable server-side validation of the response against json\_schema. Default: true when json\_schema is set (applied in Go when not explicitly set). | | `maxValidationRetries` | `string (int64)` | Optional; explicit presence | Maximum retries when server-side validation fails. Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output). Pattern: `^-?\d+$`. | | `responseHealing` | `boolean` | Optional; explicit presence | Enable response healing for structured JSON output. Defaults to enabled for non-streaming requests with json\_schema unless explicitly disabled. | **`jsonObject`** Whether the model provider is requested to return a valid JSON object. enforce valid JSON object **`jsonSchema`** JSON Schema describing the requested structured model output. optional JSON Schema (draft-07+) ## Request validation {#response-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `maxValidationRetries` | At most | `3` | | `maxValidationRetries` | At least | `0` | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [GenerationConfig](/api/models/schema-1h82h7ri5p#response) | Nested in model | | [GenerationConfig](/api/models/schema-1h82h7ri5p#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # MemoryConfig {#overview} URL: https://docs.travila.ai/api/models/schema-1g8iadjcu1 Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig. Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes. Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool. When memory is enabled, search\_top\_k selects 1–50 results; search\_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results. custom\_extraction\_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent\_id\_override changes the conversation-based memory scope so memories can be shared across conversations. include\_assistant\_messages controls assistant/agent-scoped memories and defaults to false. inject\_memory\_timestamps defaults to true and includes remembered and, when available, updated dates. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `enabled` | `boolean` | Optional | Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. | | `searchTopK` | `string (int64)` | Optional | See meaning below. Pattern: `^-?\d+$`. | | `searchThreshold` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) | | `injectAsSystemContext` | `boolean` | Optional | When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. | | `searchQueryOverride` | `string` | Optional | Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. | | `enableRerank` | `boolean` | Optional | Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. | | `addMemoriesAsync` | `boolean` | Optional | This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. | | `customExtractionPrompt` | `string` | Optional | Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. | | `enableGraph` | `boolean` | Optional | Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. | | `agentIdOverride` | `string` | Optional | Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. | | `exposeAsMcpTool` | `boolean` | Optional | This flag is currently ignored. It does not expose memory search as a model tool. Default: false. | | `includeAssistantMessages` | `boolean` | Optional | Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false | | `injectMemoryTimestamps` | `boolean` | Optional | Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \`enabled` | `boolean` | Optional | Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. | | `searchTopK` | `string (int64)` | Optional | See meaning below. Pattern: `^-?\d+$`. | | `searchThreshold` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) | | `injectAsSystemContext` | `boolean` | Optional | When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "\[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. | | `searchQueryOverride` | `string` | Optional | Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. | | `enableRerank` | `boolean` | Optional | Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. | | `addMemoriesAsync` | `boolean` | Optional | This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. | | `customExtractionPrompt` | `string` | Optional | Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. | | `enableGraph` | `boolean` | Optional | Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. | | `agentIdOverride` | `string` | Optional | Override the agent\_id used for memory scoping. By default, the conversation\_id is used as the agent\_id. Use this to share memories across multiple conversations. | | `exposeAsMcpTool` | `boolean` | Optional | This flag is currently ignored. It does not expose memory search as a model tool. Default: false. | | `includeAssistantMessages` | `boolean` | Optional | Include assistant/agent-scoped memories in operations. When false, skips agent\_id for both add and search operations, keeping only user-scoped memories. Default: false | | `injectMemoryTimestamps` | `boolean` | Optional | Include created\_at/updated\_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: \ ## Request validation {#response-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | Message | `native.gate.enabled` | search_top_k and search_threshold must be valid when enabled is true | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [GenerationConfig](/api/models/schema-1h82h7ri5p#response) | Nested in model | | [GenerationConfig](/api/models/schema-1h82h7ri5p#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # ModelRoutingFilter {#overview} URL: https://docs.travila.ai/api/models/schema-1ga4tjqqg1 ModelRoutingFilter defines metadata-based criteria for filtering model candidates. All filters are ANDed — a model must pass every specified filter. Unset or zero fields do not filter that dimension. Unknown maximum-output metadata currently passes a minimum-output filter, while an empty modality list fails a required-modality check. A passing metadata check is not proof the provider will honor the eventual request. [`maxPromptCost`](/api/models/schema-1ga4tjqqg1#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/schema-1ga4tjqqg1#request-field-maxcompletioncost) compare per-token catalog prices; unknown/unparseable prices currently pass. They do not cap total tokens, tool costs, retries or aggregate provider spend. Before sending paid traffic, confirm which spending limits are actually enforced for your account. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `minContextLength` | `string (int64)` | Optional | Minimum context window (tokens). Models below this are excluded. Pattern: `^-?\d+$`. | | `minMaxCompletionTokens` | `string (int64)` | Optional | Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: `^-?\d+$`. | | `requiredInputModalities` | Array of `string` | Optional | Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). | | `requiredOutputModalities` | Array of `string` | Optional | Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). | | `maxPromptCost` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). | | `maxCompletionCost` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). | | `excludeModerated` | `boolean` | Optional | Exclude models with content moderation enabled. | | `requiredParameters` | Array of `string` | Optional | Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `minContextLength` | `string (int64)` | Optional | Minimum context window (tokens). Models below this are excluded. Pattern: `^-?\d+$`. | | `minMaxCompletionTokens` | `string (int64)` | Optional | Minimum max completion tokens. Models below this are excluded. Models reporting 0 (unknown) pass through (permissive). Pattern: `^-?\d+$`. | | `requiredInputModalities` | Array of `string` | Optional | Required input modalities (e.g., \["image", "audio"]). Model must support ALL listed. Models with empty input\_modalities are filtered out (strict). | | `requiredOutputModalities` | Array of `string` | Optional | Required output modalities (e.g., \["image"]). Model must support ALL listed. Models with empty output\_modalities are filtered out (strict). | | `maxPromptCost` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Maximum cost per prompt token (e.g., 0.000003). 0 = no limit. Unparseable pricing strings pass through (permissive). | | `maxCompletionCost` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Maximum cost per completion token. 0 = no limit. Unparseable pricing strings pass through (permissive). | | `excludeModerated` | `boolean` | Optional | Exclude models with content moderation enabled. | | `requiredParameters` | Array of `string` | Optional | Required supported parameters (e.g., \["tools", "response\_format"]). Model must support ALL listed. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [GenerationConfig](/api/models/schema-1h82h7ri5p#response) | Nested in model | | [GenerationConfig](/api/models/schema-1h82h7ri5p#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # PercentileThreshold {#overview} URL: https://docs.travila.ai/api/models/schema-1gcuue0out Percentile thresholds for provider performance metrics Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `p50` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Threshold applied to the provider metric’s 50th percentile. | | `p90` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Threshold applied to the provider metric’s 90th percentile. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `p50` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Threshold applied to the provider metric’s 50th percentile. | | `p90` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Threshold applied to the provider metric’s 90th percentile. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [ProviderPreferences](/api/models/schema-1gg690bhqh#response) | Nested in model | | [ProviderPreferences](/api/models/schema-1gg690bhqh#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # ProviderMaxPrice {#overview} URL: https://docs.travila.ai/api/models/schema-1geaq4stvt Routing / provider preferences (generic superset) Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `prompt` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | $/1M prompt tokens. | | `completion` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | $/1M completion tokens. | | `request` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | See meaning below. | | `image` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | See meaning below. | | `audio` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | $/1M audio tokens. | **`request`** Maximum provider cost allowed per request, in US dollars. $/request **`image`** Maximum provider cost allowed per image, in US dollars. $/image ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `prompt` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | $/1M prompt tokens. | | `completion` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | $/1M completion tokens. | | `request` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | See meaning below. | | `image` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | See meaning below. | | `audio` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | $/1M audio tokens. | **`request`** Maximum provider cost allowed per request, in US dollars. $/request **`image`** Maximum provider cost allowed per image, in US dollars. $/image ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [ProviderPreferences](/api/models/schema-1gg690bhqh#response) | Nested in model | | [ProviderPreferences](/api/models/schema-1gg690bhqh#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # ProviderPreferences {#overview} URL: https://docs.travila.ai/api/models/schema-1gg690bhqh Routing preferences restricting and ordering the model providers eligible for a request. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `order` | Array of `string` | Optional | Preferred ordering of model providers for routing. | | `allowFallbacks` | `boolean` | Optional | The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. | | `requireParameters` | `boolean` | Optional | Whether routing requires providers to support the requested parameters. | | `dataCollection` | `string` (`DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY`) or `integer (int32)` | Optional; explicit presence | Provider data-collection preference used when routing the request. | | `zdr` | `boolean` | Optional | Whether routing requests providers offering zero data retention. | | `only` | Array of `string` | Optional | Provider identifiers allowed by the routing preference. | | `ignore` | Array of `string` | Optional | Provider identifiers excluded by the routing preference. | | `quantizations` | Array of `string` | Optional | See meaning below. | | `sort` | `string` (`PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY`) or `integer (int32)` | Optional; explicit presence | Metric used to order eligible model providers. | | `maxPrice` | [ProviderMaxPrice](/api/models/schema-1geaq4stvt#request) | Optional | Upper price bounds used when selecting a model provider. | | `enforceDistillableText` | `boolean` | Optional | Embeddings: enforce distillable text. | | `preferredMinThroughput` | [PercentileThreshold](/api/models/schema-1gcuue0out#request) | Optional | Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. | | `preferredMaxLatency` | [PercentileThreshold](/api/models/schema-1gcuue0out#request) | Optional | Deprioritize providers above this latency (ms). | **`quantizations`** Model quantization formats allowed by the routing preference. generic string for portability ### Values of `dataCollection` {#request-values-datacollection} Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
### Values of `sort` {#request-values-sort} Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `order` | Array of `string` | Optional | Preferred ordering of model providers for routing. | | `allowFallbacks` | `boolean` | Optional | The current chat routing path enables provider fallbacks even when this value is false or omitted. This field cannot disable fallback in that path. Use `only` to restrict eligible providers; confirm the selected providers support the requested model. | | `requireParameters` | `boolean` | Optional | Whether routing requires providers to support the requested parameters. | | `dataCollection` | `string` (`DATA_COLLECTION_MODE_ALLOW`, `DATA_COLLECTION_MODE_DENY`) or `integer (int32)` | Optional; explicit presence | Provider data-collection preference used when routing the request. | | `zdr` | `boolean` | Optional | Whether routing requests providers offering zero data retention. | | `only` | Array of `string` | Optional | Provider identifiers allowed by the routing preference. | | `ignore` | Array of `string` | Optional | Provider identifiers excluded by the routing preference. | | `quantizations` | Array of `string` | Optional | See meaning below. | | `sort` | `string` (`PROVIDER_SORT_PRICE`, `PROVIDER_SORT_THROUGHPUT`, `PROVIDER_SORT_LATENCY`) or `integer (int32)` | Optional; explicit presence | Metric used to order eligible model providers. | | `maxPrice` | [ProviderMaxPrice](/api/models/schema-1geaq4stvt#response) | Optional | Upper price bounds used when selecting a model provider. | | `enforceDistillableText` | `boolean` | Optional | Embeddings: enforce distillable text. | | `preferredMinThroughput` | [PercentileThreshold](/api/models/schema-1gcuue0out#response) | Optional | Deprioritize providers below this throughput (tokens/sec). Does not exclude — just pushes to end of preference list. | | `preferredMaxLatency` | [PercentileThreshold](/api/models/schema-1gcuue0out#response) | Optional | Deprioritize providers above this latency (ms). | **`quantizations`** Model quantization formats allowed by the routing preference. generic string for portability ### Values of `dataCollection` {#response-values-datacollection} Provider-routing preference for whether providers may collect submitted data.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATA_COLLECTION_MODE_ALLOW` | 0 | Canonical | Allow routing to providers that may collect submitted data under their policies. | | `DATA_COLLECTION_MODE_DENY` | 1 | Canonical | Request routing only to providers that do not collect submitted data under the routing policy. |
### Values of `sort` {#response-values-sort} Metric used to order eligible model providers.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_SORT_PRICE` | 0 | Canonical | Prefer providers with lower price. | | `PROVIDER_SORT_THROUGHPUT` | 1 | Canonical | Prefer providers with higher throughput. | | `PROVIDER_SORT_LATENCY` | 2 | Canonical | Prefer providers with lower latency. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [GenerationConfig](/api/models/schema-1h82h7ri5p#response) | Nested in model | | [GenerationConfig](/api/models/schema-1h82h7ri5p#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # ReasoningOptions {#overview} URL: https://docs.travila.ai/api/models/schema-1gi26i7r89 Reasoning options Supported effort settings depend on the selected model; a setting can be rejected or ignored when unsupported. To ask for the answer without returned reasoning text, set [`exclude`](/api/models/schema-1gi26i7r89#request-field-exclude) to `true`. That controls the output you receive, not whether the model uses or bills reasoning tokens. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `effort` | `string` (`EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE`) or `integer (int32)` | Optional; explicit presence | Requested model reasoning effort. | | `maxTokens` | `string (int64)` | Optional | Maximum reasoning-token count requested from the model provider. Pattern: `^-?\d+$`. | | `exclude` | `boolean` | Optional | Whether the provider should omit reasoning content from its response. | | `includeReasoningHistory` | `boolean` | Optional | When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. | ### Values of `effort` {#request-values-effort} Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `effort` | `string` (`EFFORT_HIGH`, `EFFORT_MEDIUM`, `EFFORT_LOW`, `EFFORT_XHIGH`, `EFFORT_MINIMAL`, `EFFORT_NONE`) or `integer (int32)` | Optional; explicit presence | Requested model reasoning effort. | | `maxTokens` | `string (int64)` | Optional | Maximum reasoning-token count requested from the model provider. Pattern: `^-?\d+$`. | | `exclude` | `boolean` | Optional | Whether the provider should omit reasoning content from its response. | | `includeReasoningHistory` | `boolean` | Optional | When true (default), reasoning content from previous turns is included in multi-turn requests to enable provider continuity. | ### Values of `effort` {#response-values-effort} Requested reasoning effort sent to the model provider; supported levels and their effect depend on the chosen model.
| Value | No. | Form | Meaning | |---|---|---|---| | `EFFORT_HIGH` | 0 | Canonical | Request the provider's high reasoning-effort level. | | `EFFORT_MEDIUM` | 1 | Canonical | Request the provider's medium reasoning-effort level. | | `EFFORT_LOW` | 2 | Canonical | Request the provider's low reasoning-effort level. | | `EFFORT_XHIGH` | 3 | Canonical | Request the provider's extra-high reasoning-effort level where supported. | | `EFFORT_MINIMAL` | 4 | Canonical | Request the provider's minimal reasoning-effort level where supported. | | `EFFORT_NONE` | 5 | Canonical | Request no reasoning effort where the provider supports disabling it. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [GenerationConfig](/api/models/schema-1h82h7ri5p#response) | Nested in model | | [GenerationConfig](/api/models/schema-1h82h7ri5p#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # TimeAwareConfig {#overview} URL: https://docs.travila.ai/api/models/schema-1gkqaobt3t Configuration for time-aware LLM generation. Controls injection of temporal context (current time, message timestamps, file timestamps) into the LLM context during generation. include\_message\_timestamps and include\_file\_timestamps default to false. The timezone is an IANA timezone name and defaults to UTC. timestamp\_format accepts empty text, friendly, iso8601 or date\_only. The default friendly format includes a human-readable date, time and zone; iso8601 uses an ISO timestamp, and date\_only includes only the date. An unrecognized value uses friendly formatting. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `includeCurrentTime` | `boolean` | Optional | When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. | | `includeMessageTimestamps` | `boolean` | Optional | Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. | | `includeFileTimestamps` | `boolean` | Optional | Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \`timezone` | `string` | Optional | Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" Maximum length: 50. | | `timestampFormat` | `string` (``, `friendly`, `iso8601`, `date_only`) | Optional | Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" Maximum length: 50. | ## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `timezone` | Maximum length | `50` | | `timestampFormat` | Maximum length | `50` | | `timestampFormat` | Allowed values | ``, `friendly`, `iso8601`, `date_only` | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `includeCurrentTime` | `boolean` | Optional | When enabled, include the current date and time in the per-turn volatile context attached to the current user message, using the configured timezone and timestamp format. | | `includeMessageTimestamps` | `boolean` | Optional | Include timestamps on messages in the model context to provide chronological context. Requires the message timestamp to be populated. Default: false. | | `includeFileTimestamps` | `boolean` | Optional | Include upload/modification timestamps when resolving FILE\_ID content. When true, resolved file references include "\[Uploaded: \`timezone` | `string` | Optional | Timezone for formatting (IANA format, e.g., "America/Los\_Angeles"). Default: "UTC" | | `timestampFormat` | `string` | Optional | Format pattern for timestamps. "friendly" (default): "Jan 2, 2026 at 3:04 PM MST" "iso8601": "2026-01-02T15:04:00-08:00" "date\_only": "2026-01-02" | ## Request validation {#response-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `timezone` | Maximum length | `50` | | `timestampFormat` | Maximum length | `50` | | `timestampFormat` | Allowed values | ``, `friendly`, `iso8601`, `date_only` | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [GenerationConfig](/api/models/schema-1h82h7ri5p#response) | Nested in model | | [GenerationConfig](/api/models/schema-1h82h7ri5p#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # ToolChoice {#overview} URL: https://docs.travila.ai/api/models/schema-1gmq0e4ilg Policy selecting automatic tool choice, no tool use, or a named tool. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `kind` | `string` (`TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC`) or `integer (int32)` | Optional; explicit presence | Discriminator selecting the representation or policy used by this message. | | `specificToolName` | `string` | Optional | Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. | ### Values of `kind` {#request-values-kind} How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `kind` | `string` (`TOOL_CHOICE_KIND_AUTO`, `TOOL_CHOICE_KIND_NONE`, `TOOL_CHOICE_KIND_SPECIFIC`) or `integer (int32)` | Optional; explicit presence | Discriminator selecting the representation or policy used by this message. | | `specificToolName` | `string` | Optional | Only used when kind = TOOL\_CHOICE\_KIND\_SPECIFIC. | ### Values of `kind` {#response-values-kind} How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_CHOICE_KIND_AUTO` | 0 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_NONE` | 1 | Canonical | See meaning below. | | `TOOL_CHOICE_KIND_SPECIFIC` | 2 | Canonical | See meaning below. | **`TOOL_CHOICE_KIND_AUTO`** Let the provider decide whether to call an available tool. provider decides (default) **`TOOL_CHOICE_KIND_NONE`** Disable tool selection for this generation. disable tools **`TOOL_CHOICE_KIND_SPECIFIC`** Require the named tool specified by the enclosing tool-choice configuration. force a specific tool by name
## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [GenerationConfig](/api/models/schema-1h82h7ri5p#response) | Nested in model | | [GenerationConfig](/api/models/schema-1h82h7ri5p#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # ToolDefinition {#overview} URL: https://docs.travila.ai/api/models/schema-1gomaj79cc A tool or function the model can request during generation. **[`serverId`](/api/models/schema-1gomaj79cc#request-field-serverid) is required** on every tool definition. Use `"client"` as the conventional value for tools you execute — client tools are matched by **name**, not by server. **[`parametersJsonSchema`](/api/models/schema-1gomaj79cc#request-field-parametersjsonschema)** is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `name` | `string` | **Required in requests** | Name used to select and invoke the tool. Minimum length: 1. | | `description` | `string` | **Required in requests** | Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1. | | `parametersJsonSchema` | Map from string to JSON value | Optional | JSON Schema object. | | `metadata` | Map from string to `string` | Optional | Additional tool metadata (version, category, etc.). | | `serverId` | `string` | **Required in requests** | Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1. | | `tags` | Array of `string` | Optional | Tool categorization tags. | | `documentationUrl` | `string` | Optional | Link to detailed documentation. | | `outputJsonSchema` | Map from string to JSON value | Optional | Optional output schema (JSON Schema serialized as string) describing structured results | ## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `name` | Minimum length | `1` | | `description` | Minimum length | `1` | | `serverId` | Minimum length | `1` | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `name` | `string` | **Required in requests** | Name used to select and invoke the tool. | | `description` | `string` | **Required in requests** | Explanation of the tool’s purpose supplied to the model and callers. | | `parametersJsonSchema` | Map from string to JSON value | Optional | JSON Schema object. | | `metadata` | Map from string to `string` | Optional | Additional tool metadata (version, category, etc.). | | `serverId` | `string` | **Required in requests** | Required server identifier. Use `client` as the conventional value for client-side tools; those tools are matched by name, not by server. | | `tags` | Array of `string` | Optional | Tool categorization tags. | | `documentationUrl` | `string` | Optional | Link to detailed documentation. | | `outputJsonSchema` | Map from string to JSON value | Optional | Optional output schema (JSON Schema serialized as string) describing structured results | ## Request validation {#response-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `name` | Minimum length | `1` | | `description` | Minimum length | `1` | | `serverId` | Minimum length | `1` | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Get detailed MCP server info](/api/conversations/mcp-get-server-info) | `POST /api/v1/llm/mcp-get-server-info` | | [List available MCP tools](/api/conversations/mcp-list-tools) | `POST /api/v1/llm/mcp-list-tools` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [GenerationConfig](/api/models/schema-1h82h7ri5p#response) | Nested in model | | [GenerationConfig](/api/models/schema-1h82h7ri5p#request) | Nested in model | | [MCPServerInfo](/api/models/schema-1ipatl4liq#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # Backoff {#overview} URL: https://docs.travila.ai/api/models/schema-1gqlghlp0v Requested initial delay, growth factor and upper bound for tool-call retries. The current generation workflow stores this configuration but does not schedule retries from it. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `initialMs` | `string (int64)` | Optional | See meaning below. Pattern: `^-?\d+$`. | | `multiplier` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | See meaning below. | | `maxMs` | `string (int64)` | Optional | See meaning below. Pattern: `^-?\d+$`. | **`initialMs`** Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 **`multiplier`** Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 **`maxMs`** Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `initialMs` | `string (int64)` | Optional | See meaning below. Pattern: `^-?\d+$`. | | `multiplier` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | See meaning below. | | `maxMs` | `string (int64)` | Optional | See meaning below. Pattern: `^-?\d+$`. | **`initialMs`** Requested initial retry delay in milliseconds; not applied by the current generation workflow. e.g., 200 **`multiplier`** Requested retry-delay multiplier; not applied by the current generation workflow. e.g., 2.0 **`maxMs`** Requested maximum retry delay in milliseconds; not applied by the current generation workflow. e.g., 2000 ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Update prompt variables](/api/conversations/update-prompt-variables) | `POST /api/v1/llm/update-prompt-variables` | | [Update conversation settings](/api/conversations/update-settings) | `POST /api/v1/llm/update-settings` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response) | Nested in model | | [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # StopOnFailureRule {#overview} URL: https://docs.travila.ai/api/models/schema-1gstrgb39r Requested tool-selection rule for handling an execution failure. The current generation workflow stores these rules but does not evaluate them or stop a loop or run because of them. The conditions in [`stopOnFailureRules`](/api/models/schema-1h2ji21uc4#request-field-stoponfailurerules), including [`priority`](/api/models/schema-1gstrgb39r#request-field-priority), timeout inclusion and error matching, are not enforced. Do not rely on these fields as a stop control. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `toolNamePatterns` | Array of `string` | Optional | Requested tool-name selection; not evaluated by the current generation workflow. | | `serverIds` | Array of `string` | Optional | Requested MCP server selection; not evaluated by the current generation workflow. | | `onFailure` | `string` (`FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN`) or `integer (int32)` | Optional; explicit presence | See meaning below. | | `includeTimeouts` | `boolean` | Optional | See meaning below. | | `errorSubstrings` | Array of `string` | Optional | See meaning below. | | `priority` | `string (int64)` | Optional | See meaning below. Pattern: `^-?\d+$`. | **`onFailure`** Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN **`includeTimeouts`** Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **`errorSubstrings`** Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches **`priority`** Requested rule priority; not evaluated by the current generation workflow. lower evaluated first ### Values of `onFailure` {#request-values-onfailure} Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `toolNamePatterns` | Array of `string` | Optional | Requested tool-name selection; not evaluated by the current generation workflow. | | `serverIds` | Array of `string` | Optional | Requested MCP server selection; not evaluated by the current generation workflow. | | `onFailure` | `string` (`FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN`) or `integer (int32)` | Optional; explicit presence | See meaning below. | | `includeTimeouts` | `boolean` | Optional | See meaning below. | | `errorSubstrings` | Array of `string` | Optional | See meaning below. | | `priority` | `string (int64)` | Optional | See meaning below. Pattern: `^-?\d+$`. | **`onFailure`** Requested failure action; not evaluated by the current generation workflow. STOP\_LOOP or STOP\_RUN **`includeTimeouts`** Requested inclusion of timeouts as failures; not evaluated by the current generation workflow. treat timeouts as failure for this rule **`errorSubstrings`** Requested error-text selection; not evaluated by the current generation workflow. only stop if error matches **`priority`** Requested rule priority; not evaluated by the current generation workflow. lower evaluated first ### Values of `onFailure` {#response-values-onfailure} Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Update prompt variables](/api/conversations/update-prompt-variables) | `POST /api/v1/llm/update-prompt-variables` | | [Update conversation settings](/api/conversations/update-settings) | `POST /api/v1/llm/update-settings` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response) | Nested in model | | [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # TimeoutPolicy {#overview} URL: https://docs.travila.ai/api/models/schema-1gu5od417l Bounds the run as a whole. This message has no per-tool or per-loop execution timeout. Approval and client-result answer windows are configured separately on ToolExecutionPolicy; those waits do not cancel an already dispatched remote action. Set a finite [`timeouts.overallMs`](/api/models/schema-1gu5od417l#request-field-overallms) when the task needs a duration limit. It is measured from run start; zero or omission leaves the run-level duration unbounded. When Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and pending calls can be closed with `endReason: "run_timed_out"`. A call still awaiting approval has not been dispatched. The timeout does not guarantee a remote action stops at that instant, establish whether it took effect, or roll it back. Use [`endReason`](/api/models/schema-1it6mqsqoo#response-field-endreason) to distinguish a run deadline from a call's own answer window: an unanswered approval reads `approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the actual tool status too; approval and client-tool expiry can produce `FAILED` or `TIMED_OUT`. Run and individual tool outcomes are different fields. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `overallMs` | `string (int64)` | Optional | Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: `^-?\d+$`. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `overallMs` | `string (int64)` | Optional | Overall run budget in milliseconds, measured from run start. Zero or omission leaves this run-level bound unset. The workflow checks the deadline and can end with AGENT\_STATUS\_TIMED\_OUT; it cannot cancel or undo a remote action already dispatched. Approval and client-result waits retain their separate finite limits. Pattern: `^-?\d+$`. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Update prompt variables](/api/conversations/update-prompt-variables) | `POST /api/v1/llm/update-prompt-variables` | | [Update conversation settings](/api/conversations/update-settings) | `POST /api/v1/llm/update-settings` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response) | Nested in model | | [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # ToolExecutionOrderRule {#overview} URL: https://docs.travila.ai/api/models/schema-1h0coqd8e8 Per-run requested ordering rule for tool execution. The current generation workflow stores these rules but does not apply their patterns, server filters or weights. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `toolNamePatterns` | Array of `string` | Optional | Requested tool-name patterns; not evaluated by the current generation workflow. | | `serverIds` | Array of `string` | Optional | Optional requested MCP server filter; not evaluated by the current generation workflow. | | `weight` | `string (int64)` | Optional | See meaning below. Pattern: `^-?\d+$`. | **`weight`** Requested ordering weight; not applied by the current generation workflow. lower executes first ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `toolNamePatterns` | Array of `string` | Optional | Requested tool-name patterns; not evaluated by the current generation workflow. | | `serverIds` | Array of `string` | Optional | Optional requested MCP server filter; not evaluated by the current generation workflow. | | `weight` | `string (int64)` | Optional | See meaning below. Pattern: `^-?\d+$`. | **`weight`** Requested ordering weight; not applied by the current generation workflow. lower executes first ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Update prompt variables](/api/conversations/update-prompt-variables) | `POST /api/v1/llm/update-prompt-variables` | | [Update conversation settings](/api/conversations/update-settings) | `POST /api/v1/llm/update-settings` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response) | Nested in model | | [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # ToolExecutionPolicy {#overview} URL: https://docs.travila.ai/api/models/schema-1h2ji21uc4 Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow. If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action. An omitted or zero [`approvalTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-approvaltimeoutms) waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatterns) yields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes every expiry `FAILED`. The retry controls [`retriableToolNamePatterns`](/api/models/schema-1h2ji21uc4#request-field-retriabletoolnamepatterns), [`retryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-retryableerrorsubstrings), [`nonRetryableErrorSubstrings`](/api/models/schema-1h2ji21uc4#request-field-nonretryableerrorsubstrings), [`maxRetries`](/api/models/schema-1h2ji21uc4#request-field-maxretries) and [`retryBackoff`](/api/models/schema-1h2ji21uc4#request-field-retrybackoff) are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls. [`maxTotalToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxtotaltoolcalls) limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive `FAILED` tool results naming the limit, which the model can use when continuing the run. [`maxParallelToolCalls`](/api/models/schema-1h2ji21uc4#request-field-maxparalleltoolcalls) limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency. Choose [`clientToolTimeoutMs`](/api/models/schema-1h2ji21uc4#request-field-clienttooltimeoutms) for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat). See [Tool execution policies](/api/tool-execution/policies) for policy selection and caller reconciliation. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `requireApprovalToolNamePatterns` | Array of `string` | Optional | Tool-name patterns selecting calls that require an approval decision. | | `requireApprovalServerIds` | Array of `string` | Optional | MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. | | `autoApproveToolNamePatterns` | Array of `string` | Optional | Tool-name patterns whose matching calls may be approved automatically. | | `autoApproveServerIds` | Array of `string` | Optional | MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. | | `approvalMode` | `string` (`APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`) or `integer (int32)` | Optional; explicit presence | See meaning below. | | `clientToolMode` | `string` (`CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`) or `integer (int32)` | Optional; explicit presence | See meaning below. | | `approvalTimeoutMs` | `string (int64)` | Optional | Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: `^-?\d+$`. | | `failOnApprovalTimeoutToolNamePatterns` | Array of `string` | Optional | Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. | | `orderRules` | Array of [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#request) | Optional | Stored requested ordering rules; not applied by the current generation workflow. | | `stableSortByCallIndexOnTie` | `boolean` | Optional | Stored requested ordering tie-breaker; not applied by the current generation workflow. | | `maxParallelToolCalls` | `string (int64)` | Optional | Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: `^-?\d+$`. | | `maxToolCallsPerLoop` | `string (int64)` | Optional | See meaning below. Pattern: `^-?\d+$`. | | `maxTotalToolCalls` | `string (int64)` | Optional | Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: `^-?\d+$`. | | `retriableToolNamePatterns` | Array of `string` | Optional | Stored requested retry selection; does not enable retries in the current workflow. | | `maxRetries` | `string (int64)` | Optional | See meaning below. Pattern: `^-?\d+$`. | | `retryBackoff` | [Backoff](/api/models/schema-1gqlghlp0v#request) | Optional | Stored requested retry delays; not applied by the current generation workflow. | | `retryableErrorSubstrings` | Array of `string` | Optional | Stored requested retryable-error selection; not evaluated by the current workflow. | | `nonRetryableErrorSubstrings` | Array of `string` | Optional | Stored requested retry exclusions; not evaluated by the current generation workflow. | | `timeouts` | [TimeoutPolicy](/api/models/schema-1gu5od417l#request) | Optional | Overall execution time budget for the generation run. | | `clientToolTimeoutMs` | `string (int64)` | Optional | Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: `^-?\d+$`. | | `failureMode` | `string` (`FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN`) or `integer (int32)` | Optional; explicit presence | See meaning below. | | `stopOnFailureRules` | Array of [StopOnFailureRule](/api/models/schema-1gstrgb39r#request) | Optional | Stored requested stop rules; not evaluated by the current generation workflow. | **`approvalMode`** How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED **`clientToolMode`** Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED **`maxToolCallsPerLoop`** Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap **`maxRetries`** Stored requested retry count; does not enable retries in the current workflow. per tool-call **`failureMode`** Stored requested failure action; not enforced by the current generation workflow. default if no rule matches ### Values of `approvalMode` {#request-values-approvalmode} How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
### Values of `clientToolMode` {#request-values-clienttoolmode} How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
### Values of `failureMode` {#request-values-failuremode} Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `requireApprovalToolNamePatterns` | Array of `string` | Optional | Tool-name patterns selecting calls that require an approval decision. | | `requireApprovalServerIds` | Array of `string` | Optional | MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. | | `autoApproveToolNamePatterns` | Array of `string` | Optional | Tool-name patterns whose matching calls may be approved automatically. | | `autoApproveServerIds` | Array of `string` | Optional | MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. | | `approvalMode` | `string` (`APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`) or `integer (int32)` | Optional; explicit presence | See meaning below. | | `clientToolMode` | `string` (`CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`) or `integer (int32)` | Optional; explicit presence | See meaning below. | | `approvalTimeoutMs` | `string (int64)` | Optional | Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail\_on\_approval\_timeout\_tool\_name\_patterns produces FAILED; other calls become TIMED\_OUT. An empty pattern list makes every expiry FAILED. Pattern: `^-?\d+$`. | | `failOnApprovalTimeoutToolNamePatterns` | Array of `string` | Optional | Selects approval timeouts reported as FAILED; nonmatching calls become TIMED\_OUT. An empty list makes every approval expiry FAILED. Global failure\_mode is not enforced. | | `orderRules` | Array of [ToolExecutionOrderRule](/api/models/schema-1h0coqd8e8#response) | Optional | Stored requested ordering rules; not applied by the current generation workflow. | | `stableSortByCallIndexOnTie` | `boolean` | Optional | Stored requested ordering tie-breaker; not applied by the current generation workflow. | | `maxParallelToolCalls` | `string (int64)` | Optional | Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: `^-?\d+$`. | | `maxToolCallsPerLoop` | `string (int64)` | Optional | See meaning below. Pattern: `^-?\d+$`. | | `maxTotalToolCalls` | `string (int64)` | Optional | Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: `^-?\d+$`. | | `retriableToolNamePatterns` | Array of `string` | Optional | Stored requested retry selection; does not enable retries in the current workflow. | | `maxRetries` | `string (int64)` | Optional | See meaning below. Pattern: `^-?\d+$`. | | `retryBackoff` | [Backoff](/api/models/schema-1gqlghlp0v#response) | Optional | Stored requested retry delays; not applied by the current generation workflow. | | `retryableErrorSubstrings` | Array of `string` | Optional | Stored requested retryable-error selection; not evaluated by the current workflow. | | `nonRetryableErrorSubstrings` | Array of `string` | Optional | Stored requested retry exclusions; not evaluated by the current generation workflow. | | `timeouts` | [TimeoutPolicy](/api/models/schema-1gu5od417l#response) | Optional | Overall execution time budget for the generation run. | | `clientToolTimeoutMs` | `string (int64)` | Optional | Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail\_on\_approval\_timeout\_tool\_name\_patterns list yields FAILED; other calls become TIMED\_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: `^-?\d+$`. | | `failureMode` | `string` (`FAILURE_MODE_CONTINUE`, `FAILURE_MODE_STOP_LOOP`, `FAILURE_MODE_STOP_RUN`) or `integer (int32)` | Optional; explicit presence | See meaning below. | | `stopOnFailureRules` | Array of [StopOnFailureRule](/api/models/schema-1gstrgb39r#response) | Optional | Stored requested stop rules; not evaluated by the current generation workflow. | **`approvalMode`** How to schedule execution when approvals are required for some tools default: APPROVAL\_MODE\_MIXED **`clientToolMode`** Stored requested client-tool scheduling mode; not enforced by the current workflow. default: CLIENT\_TOOL\_MODE\_MIXED **`maxToolCallsPerLoop`** Stored requested per-loop tool-call cap; not enforced by the current generation workflow. 0 = no cap **`maxRetries`** Stored requested retry count; does not enable retries in the current workflow. per tool-call **`failureMode`** Stored requested failure action; not enforced by the current generation workflow. default if no rule matches ### Values of `approvalMode` {#response-values-approvalmode} How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `APPROVAL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `APPROVAL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`APPROVAL_MODE_MIXED`** Run automatically approved calls immediately and hold only calls that require approval. Run auto-approved tool calls immediately; hold only those requiring approval. **`APPROVAL_MODE_BLOCK_ALL`** Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
### Values of `clientToolMode` {#response-values-clienttoolmode} How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning | |---|---|---|---| | `CLIENT_TOOL_MODE_MIXED` | 0 | Canonical | See meaning below. | | `CLIENT_TOOL_MODE_BLOCK_ALL` | 1 | Canonical | See meaning below. | **`CLIENT_TOOL_MODE_MIXED`** Record pending client tools and continue with server-executed MCP tools and the loop. Do not wait on client tools; record pending and continue executing MCP tools and loop **`CLIENT_TOOL_MODE_BLOCK_ALL`** Hold loop advancement until the caller submits results for all pending client tools. Block loop advancement until all client-side tool calls are resolved by the client
### Values of `failureMode` {#response-values-failuremode} Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning | |---|---|---|---| | `FAILURE_MODE_CONTINUE` | 0 | Canonical | Request continued processing after the failed tool call. | | `FAILURE_MODE_STOP_LOOP` | 1 | Canonical | Request stopping the current tool-execution loop after the failure. | | `FAILURE_MODE_STOP_RUN` | 2 | Canonical | Request stopping the generation run after the failure. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Update prompt variables](/api/conversations/update-prompt-variables) | `POST /api/v1/llm/update-prompt-variables` | | [Update conversation settings](/api/conversations/update-settings) | `POST /api/v1/llm/update-settings` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [ConversationSettings](/api/models/schema-ph6avse89k#response) | Nested in model | | [ConversationSettings](/api/models/schema-ph6avse89k#request) | Nested in model | | [GenerationConfig](/api/models/schema-1h82h7ri5p#response) | Nested in model | | [GenerationConfig](/api/models/schema-1h82h7ri5p#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # TurnContextConfig {#overview} URL: https://docs.travila.ai/api/models/schema-1h5dj58uph Configuration for turn-aware LLM generation Turn context tells the model the current generation number and remaining allowance, with tool guidance based on that allowance. This annotation is enabled by default and is not persisted in message history. Its presentation options belong in the [generation configuration reference](/api/conversations/update-default-generation-config); the annotation itself does not change the run limit. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `enabled` | `boolean` | Optional | Enable turn context injection into system prompt Default: true | | `includeToolGuidance` | `boolean` | Optional | Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) | | `format` | `string` (`minimal`, `standard`, `verbose`) | **Required in requests** | Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" | ## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `format` | Allowed values | `minimal`, `standard`, `verbose` | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `enabled` | `boolean` | Optional | Enable turn context injection into system prompt Default: true | | `includeToolGuidance` | `boolean` | Optional | Include tool usage guidance based on remaining turns Default: false (can enable for agentic workflows) | | `format` | `string` | **Required in requests** | Format for turn context "minimal": "\[Turn 2/5]" "standard": "\[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]" "verbose": Includes detailed behavioral guidance Default: "standard" | ## Request validation {#response-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `format` | Allowed values | `minimal`, `standard`, `verbose` | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [GenerationConfig](/api/models/schema-1h82h7ri5p#response) | Nested in model | | [GenerationConfig](/api/models/schema-1h82h7ri5p#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # UsageOptions {#overview} URL: https://docs.travila.ai/api/models/schema-1h615aquj0 Usage accounting preferences Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `include` | `boolean` | Optional | Whether usage accounting should be included in the provider response. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `include` | `boolean` | Optional | Whether usage accounting should be included in the provider response. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [GenerationConfig](/api/models/schema-1h82h7ri5p#response) | Nested in model | | [GenerationConfig](/api/models/schema-1h82h7ri5p#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # GenerationConfig {#overview} URL: https://docs.travila.ai/api/models/schema-1h82h7ri5p Canonical generation configuration Set the language preference to a BCP-47 tag (for example, `"fr"` or `"pt-BR"`). The platform injects a `"Respond only in [language]"` instruction into **every** LLM call for this conversation. The instruction is not persisted to history. See [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `model` | `string` | Optional | Primary model identifier requested for generation. | | `models` | Array of `string` | Optional | Candidate models for routing. | | `systemPrompt` | `string` | Optional; explicit presence | Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. | | `modelRoutingFilter` | [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#request) | Optional | Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. | | `provider` | [ProviderPreferences](/api/models/schema-1gg690bhqh#request) | Optional | Provider/multi-provider routing preferences | | `reasoning` | [ReasoningOptions](/api/models/schema-1gi26i7r89#request) | Optional | Reasoning effort and output options passed to the model provider. | | `usage` | [UsageOptions](/api/models/schema-1h615aquj0#request) | Optional | Token and cost accounting associated with the operation. | | `transforms` | Array of `string` | Optional | Provider transformations requested for the generation input. | | `tools` | Array of [ToolDefinition](/api/models/schema-1gomaj79cc#request) | Optional | Tool definitions exposed to the model for server-side execution. | | `toolChoice` | [ToolChoice](/api/models/schema-1gmq0e4ilg#request) | Optional | Policy controlling whether and which tool the model may call. | | `clientTools` | Array of [ToolDefinition](/api/models/schema-1gomaj79cc#request) | Optional | Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) | | `toolPolicy` | [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request) | Optional | Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) | | `temperature` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional; explicit presence | Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. | | `topP` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional; explicit presence | Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. | | `maxOutputTokens` | `string (int64)` | Optional; explicit presence | Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: `^-?\d+$`. | | `frequencyPenalty` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional; explicit presence | Sampling penalty applied to tokens according to their prior frequency. | | `presencePenalty` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional; explicit presence | Sampling penalty applied to tokens already present in generated content. | | `stopSequences` | Array of `string` | Optional | Token sequences at which the model should stop generation. | | `seed` | `string (int64)` | Optional; explicit presence | Deterministic control where supported. Pattern: `^-?\d+$`. | | `responseFormat` | [ResponseFormat](/api/models/schema-1g69v4vltg#request) | Optional | Structured-output format and schema requested for the model response. | | `allowParallelToolCalls` | `boolean` | Optional; explicit presence | Allow the model to issue multiple tool calls in parallel where supported | | `topK` | `string (int64)` | Optional; explicit presence | Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: `^-?\d+$`. | | `repetitionPenalty` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional; explicit presence | Provider sampling penalty used to discourage repeated output. | | `logitBias` | Map from string to `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Per-token adjustments applied to the provider token-selection logits. | | `topLogprobs` | `string (int64)` | Optional; explicit presence | Number of top token log probabilities requested from the provider. Pattern: `^-?\d+$`. | | `minP` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional; explicit presence | Minimum relative token probability used by supported sampling providers. | | `topA` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional; explicit presence | Adaptive probability cutoff used by supported sampling providers. | | `user` | `string` | Optional; explicit presence | User identifier forwarded for provider-side request attribution. | | `modalities` | Array of `string` (`MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO`) or `integer (int32)` | Optional | Output modalities (e.g., \[TEXT, IMAGE]) | | `plugins` | Array of [PluginConfig](/api/models/schema-1g5jvg1icc#request) | Optional | Provider plugins requested for pre-processing or post-processing. | | `languagePreference` | `string` | Optional; explicit presence | Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) Minimum length: 2. Pattern: `^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$`. | | `timeAware` | [TimeAwareConfig](/api/models/schema-1gkqaobt3t#request) | Optional | Time-aware generation options (current time, message timestamps, file timestamps) | | `turnContext` | [TurnContextConfig](/api/models/schema-1h5dj58uph#request) | Optional | Turn context configuration for turn-aware generation | | `mem0` | [MemoryConfig](/api/models/schema-1g8iadjcu1#request) | Optional | Configuration for semantic memory search, context injection and extraction during generation. | | `requestTimeoutSeconds` | `string (int64)` | Optional | Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: `^-?\d+$`. | | `fileResolution` | [FileResolutionConfig](/api/models/schema-1ftcunpmha#request) | Optional | Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. | | `clearTools` | `boolean` | Optional | Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. | | `clearClientTools` | `boolean` | Optional | Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. | ### Values of `modalities` {#request-values-modalities} Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `languagePreference` | Minimum length | `2` | | `languagePreference` | Pattern | `^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$` | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `model` | `string` | Optional | Primary model identifier requested for generation. | | `models` | Array of `string` | Optional | Candidate models for routing. | | `systemPrompt` | `string` | Optional; explicit presence | Optional system prompt prepended as a system message. An explicitly empty value in a per-call override clears the base prompt. | | `modelRoutingFilter` | [ModelRoutingFilter](/api/models/schema-1ga4tjqqg1#response) | Optional | Optional metadata-based model routing filter. When set, candidate models are filtered by these criteria before routing. | | `provider` | [ProviderPreferences](/api/models/schema-1gg690bhqh#response) | Optional | Provider/multi-provider routing preferences | | `reasoning` | [ReasoningOptions](/api/models/schema-1gi26i7r89#response) | Optional | Reasoning effort and output options passed to the model provider. | | `usage` | [UsageOptions](/api/models/schema-1h615aquj0#response) | Optional | Token and cost accounting associated with the operation. | | `transforms` | Array of `string` | Optional | Provider transformations requested for the generation input. | | `tools` | Array of [ToolDefinition](/api/models/schema-1gomaj79cc#response) | Optional | Tool definitions exposed to the model for server-side execution. | | `toolChoice` | [ToolChoice](/api/models/schema-1gmq0e4ilg#response) | Optional | Policy controlling whether and which tool the model may call. | | `clientTools` | Array of [ToolDefinition](/api/models/schema-1gomaj79cc#response) | Optional | Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP) | | `toolPolicy` | [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response) | Optional | Per-run tool execution policy (approvals, ordering, limits, retries, timeouts) | | `temperature` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional; explicit presence | Sampling temperature, from 0.0 to 2.0. Omission inherits the base configuration or provider default; an explicitly supplied zero remains an override. | | `topP` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional; explicit presence | Cumulative token-probability cutoff used for nucleus sampling, from 0.0 through 1.0. | | `maxOutputTokens` | `string (int64)` | Optional; explicit presence | Maximum output-token count requested from the model provider; corresponds to max\_tokens in provider requests. Pattern: `^-?\d+$`. | | `frequencyPenalty` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional; explicit presence | Sampling penalty applied to tokens according to their prior frequency. | | `presencePenalty` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional; explicit presence | Sampling penalty applied to tokens already present in generated content. | | `stopSequences` | Array of `string` | Optional | Token sequences at which the model should stop generation. | | `seed` | `string (int64)` | Optional; explicit presence | Deterministic control where supported. Pattern: `^-?\d+$`. | | `responseFormat` | [ResponseFormat](/api/models/schema-1g69v4vltg#response) | Optional | Structured-output format and schema requested for the model response. | | `allowParallelToolCalls` | `boolean` | Optional; explicit presence | Allow the model to issue multiple tool calls in parallel where supported | | `topK` | `string (int64)` | Optional; explicit presence | Maximum number of candidate next tokens considered by providers that support top-k sampling. Pattern: `^-?\d+$`. | | `repetitionPenalty` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional; explicit presence | Provider sampling penalty used to discourage repeated output. | | `logitBias` | Map from string to `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Per-token adjustments applied to the provider token-selection logits. | | `topLogprobs` | `string (int64)` | Optional; explicit presence | Number of top token log probabilities requested from the provider. Pattern: `^-?\d+$`. | | `minP` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional; explicit presence | Minimum relative token probability used by supported sampling providers. | | `topA` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional; explicit presence | Adaptive probability cutoff used by supported sampling providers. | | `user` | `string` | Optional; explicit presence | User identifier forwarded for provider-side request attribution. | | `modalities` | Array of `string` (`MODALITY_TEXT`, `MODALITY_IMAGE`, `MODALITY_AUDIO`) or `integer (int32)` | Optional | Output modalities (e.g., \[TEXT, IMAGE]) | | `plugins` | Array of [PluginConfig](/api/models/schema-1g5jvg1icc#response) | Optional | Provider plugins requested for pre-processing or post-processing. | | `languagePreference` | `string` | Optional; explicit presence | Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware) | | `timeAware` | [TimeAwareConfig](/api/models/schema-1gkqaobt3t#response) | Optional | Time-aware generation options (current time, message timestamps, file timestamps) | | `turnContext` | [TurnContextConfig](/api/models/schema-1h5dj58uph#response) | Optional | Turn context configuration for turn-aware generation | | `mem0` | [MemoryConfig](/api/models/schema-1g8iadjcu1#response) | Optional | Configuration for semantic memory search, context injection and extraction during generation. | | `requestTimeoutSeconds` | `string (int64)` | Optional | Timeout for an individual model-provider request, in seconds. Zero selects the 30-second default; other values are clamped to the range 1–600. Pattern: `^-?\d+$`. | | `fileResolution` | [FileResolutionConfig](/api/models/schema-1ftcunpmha#response) | Optional | Configuration for resolving FILE\_ID content parts to fresh signed URLs before calling a model provider. When unset, unresolved content is skipped. | | `clearTools` | `boolean` | Optional | Set to true with an empty tools list in an override to clear inherited tools. An empty list alone inherits the base tools. This directive applies only when merging an override. | | `clearClientTools` | `boolean` | Optional | Set to true with an empty client tools list in an override to clear inherited client tools for that turn. An empty list alone inherits the base client tools, and a nonempty list replaces them regardless of this directive. It applies only when merging an override and leaves server tool selection unchanged. | ### Values of `modalities` {#response-values-modalities} Output media requested from a model that supports that modality.
| Value | No. | Form | Meaning | |---|---|---|---| | `MODALITY_TEXT` | 0 | Canonical | Request generated text output. | | `MODALITY_IMAGE` | 1 | Canonical | Request generated image output where the model supports it. | | `MODALITY_AUDIO` | 2 | Canonical | Request generated audio output where the model supports it. |
## Request validation {#response-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `languagePreference` | Minimum length | `2` | | `languagePreference` | Pattern | `^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$` | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Update default generation config](/api/conversations/update-default-generation-config) | `POST /api/v1/llm/update-default-generation-config` | | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Update the caller's default generation config](/api/end-users/update-default-generation-config) | `POST /api/v1/enduser/update-generation-config` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [CompactionConfig](/api/models/schema-1hbvkcgu5m#response) | Nested in model | | [CompactionConfig](/api/models/schema-1hbvkcgu5m#request) | Nested in model | | [AgentProfile](/api/models/schema-1hmbcecg1j#response) | Nested in model | | [AgentProfile](/api/models/schema-1hmbcecg1j#request) | Nested in model | | [GenerationContext](/api/models/schema-1im79fphmq#response) | Nested in model | | [GenerationContext](/api/models/schema-1im79fphmq#request) | Nested in model | | [LLMGenerationStartedEvent](/api/models/schema-pnv14jb39g#response) | Nested in model | | [LLMGenerationStartedEvent](/api/models/schema-pnv14jb39g#request) | Nested in model | | [SourcePromptTemplate](/api/models/schema-pjk9r8rn5b#request) | Nested in model | | [EndUserState](/api/models/schema-1l1et4gp2i#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) - [end-users OpenAPI](/end-users.yaml) --- # CompactionConfig {#overview} URL: https://docs.travila.ai/api/models/schema-1hbvkcgu5m Configuration for compaction strategy ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `mode` | `string` (`COMPACTION_MODE_SYNC`, `COMPACTION_MODE_ASYNC`) or `integer (int32)` | Optional; explicit presence | See meaning below. | | `threshold` | [ThresholdConfig](/api/models/schema-1frig4k431#request) | Optional | Token-count or context-window-percentage threshold that triggers compaction. | | `generationConfig` | [GenerationConfig](/api/models/schema-1h82h7ri5p#request) | Optional | Separate config for compaction LLM calls. | | `preserveRecent` | `string (int64)` | Optional | Messages to keep uncompacted. Pattern: `^-?\d+$`. | **`mode`** Context compaction mode selected by the operation. SYNC, ASYNC ### Values of `mode` {#request-values-mode} Whether context compaction blocks the triggering operation or proceeds asynchronously.
| Value | No. | Form | Meaning | |---|---|---|---| | `COMPACTION_MODE_SYNC` | 0 | Canonical | Wait for compaction to finish before continuing the dependent operation. | | `COMPACTION_MODE_ASYNC` | 1 | Canonical | Start compaction asynchronously and apply its result when it becomes available. |
## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `mode` | `string` (`COMPACTION_MODE_SYNC`, `COMPACTION_MODE_ASYNC`) or `integer (int32)` | Optional; explicit presence | See meaning below. | | `threshold` | [ThresholdConfig](/api/models/schema-1frig4k431#response) | Optional | Token-count or context-window-percentage threshold that triggers compaction. | | `generationConfig` | [GenerationConfig](/api/models/schema-1h82h7ri5p#response) | Optional | Separate config for compaction LLM calls. | | `preserveRecent` | `string (int64)` | Optional | Messages to keep uncompacted. Pattern: `^-?\d+$`. | **`mode`** Context compaction mode selected by the operation. SYNC, ASYNC ### Values of `mode` {#response-values-mode} Whether context compaction blocks the triggering operation or proceeds asynchronously.
| Value | No. | Form | Meaning | |---|---|---|---| | `COMPACTION_MODE_SYNC` | 0 | Canonical | Wait for compaction to finish before continuing the dependent operation. | | `COMPACTION_MODE_ASYNC` | 1 | Canonical | Start compaction asynchronously and apply its result when it becomes available. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` |
Models containing this value | Model | Relationship | |---|---| | [ContextManagementSettings](/api/models/schema-1hgrvsu34j#response) | Nested in model | | [ContextManagementSettings](/api/models/schema-1hgrvsu34j#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # SelectiveExclusionConfig {#overview} URL: https://docs.travila.ai/api/models/schema-1hc73qpaio Configuration for selective exclusion ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `excludeToolResults` | `boolean` | Optional | Whether tool-result content is excluded from model context. | | `excludeImages` | `boolean` | Optional | Whether image content is excluded from model context. | | `excludeFiles` | `boolean` | Optional | Whether file content is excluded from model context. | | `excludeReasoning` | `boolean` | Optional | When true, reasoning/thinking content parts are excluded from context | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `excludeToolResults` | `boolean` | Optional | Whether tool-result content is excluded from model context. | | `excludeImages` | `boolean` | Optional | Whether image content is excluded from model context. | | `excludeFiles` | `boolean` | Optional | Whether file content is excluded from model context. | | `excludeReasoning` | `boolean` | Optional | When true, reasoning/thinking content parts are excluded from context | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` |
Models containing this value | Model | Relationship | |---|---| | [ContextManagementSettings](/api/models/schema-1hgrvsu34j#response) | Nested in model | | [ContextManagementSettings](/api/models/schema-1hgrvsu34j#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # WindowingConfig {#overview} URL: https://docs.travila.ai/api/models/schema-1he7ulevif Configuration for windowing strategy ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `maxMessages` | `string (int64)` | Optional | See meaning below. Pattern: `^-?\d+$`. | **`maxMessages`** Maximum number of conversation messages to retain in the context window. Default: 100 ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `maxMessages` | `string (int64)` | Optional | See meaning below. Pattern: `^-?\d+$`. | **`maxMessages`** Maximum number of conversation messages to retain in the context window. Default: 100 ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` |
Models containing this value | Model | Relationship | |---|---| | [ContextManagementSettings](/api/models/schema-1hgrvsu34j#response) | Nested in model | | [ContextManagementSettings](/api/models/schema-1hgrvsu34j#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # ContextManagementSettings {#overview} URL: https://docs.travila.ai/api/models/schema-1hgrvsu34j Configuration for context management ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `strategy` | `string` (`CONTEXT_STRATEGY_COMPACTION`, `CONTEXT_STRATEGY_WINDOWING`, `CONTEXT_STRATEGY_NONE`) or `integer (int32)` | Optional; explicit presence | Context management strategy selected for the conversation. | | `compactionConfig` | [CompactionConfig](/api/models/schema-1hbvkcgu5m#request) | Optional | Configuration applied when summarizing the conversation context. | | `windowingConfig` | [WindowingConfig](/api/models/schema-1he7ulevif#request) | Optional | Rules selecting the message window retained in model context. | | `selectiveExclusionConfig` | [SelectiveExclusionConfig](/api/models/schema-1hc73qpaio#request) | Optional | Rules selecting content to omit from the model context. | ### Values of `strategy` {#request-values-strategy} How stored conversation history is selected or summarized for model context.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTEXT_STRATEGY_COMPACTION` | 0 | Canonical | Use completed compaction summaries and remaining history; fall back to windowing when no completed summary is available. | | `CONTEXT_STRATEGY_WINDOWING` | 1 | Canonical | Keep a bounded window of recent conversation messages according to the windowing configuration. | | `CONTEXT_STRATEGY_NONE` | 2 | Canonical | Pass the conversation history without applying compaction or windowing. |
## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `strategy` | `string` (`CONTEXT_STRATEGY_COMPACTION`, `CONTEXT_STRATEGY_WINDOWING`, `CONTEXT_STRATEGY_NONE`) or `integer (int32)` | Optional; explicit presence | Context management strategy selected for the conversation. | | `compactionConfig` | [CompactionConfig](/api/models/schema-1hbvkcgu5m#response) | Optional | Configuration applied when summarizing the conversation context. | | `windowingConfig` | [WindowingConfig](/api/models/schema-1he7ulevif#response) | Optional | Rules selecting the message window retained in model context. | | `selectiveExclusionConfig` | [SelectiveExclusionConfig](/api/models/schema-1hc73qpaio#response) | Optional | Rules selecting content to omit from the model context. | ### Values of `strategy` {#response-values-strategy} How stored conversation history is selected or summarized for model context.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTEXT_STRATEGY_COMPACTION` | 0 | Canonical | Use completed compaction summaries and remaining history; fall back to windowing when no completed summary is available. | | `CONTEXT_STRATEGY_WINDOWING` | 1 | Canonical | Keep a bounded window of recent conversation messages according to the windowing configuration. | | `CONTEXT_STRATEGY_NONE` | 2 | Canonical | Pass the conversation history without applying compaction or windowing. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Update context management settings](/api/conversations/update-context-management-settings) | `POST /api/v1/llm/update-context-management-settings` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # MCPServerReference {#overview} URL: https://docs.travila.ai/api/models/schema-1hik90rmo1 MCP Server Reference Lightweight reference to pre-configured MCP servers used by workflows Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `serverId` | `string` | **Required in requests** | ID of pre-configured MCP server (e.g., "github", "filesystem"). Minimum length: 1. | | `enabled` | `boolean` | Optional; explicit presence | Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. | | `priority` | `string (int64)` | Optional | Priority override for tool selection (higher = preferred). Pattern: `^-?\d+$`. | | `allowlistToolPatterns` | Array of `string` | Optional | Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). | | `blocklistToolPatterns` | Array of `string` | Optional | Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). | | `serverOverrides` | Map from string to `string` | Optional | Override server settings for this usage. | | `deferTools` | `boolean` | Optional | Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. | ## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `serverId` | Minimum length | `1` | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `serverId` | `string` | **Required in requests** | ID of pre-configured MCP server (e.g., "github", "filesystem"). | | `enabled` | `boolean` | Optional; explicit presence | Whether to use this MCP server. Omission means enabled; only an explicitly false value excludes it from discovery. | | `priority` | `string (int64)` | Optional | Priority override for tool selection (higher = preferred). Pattern: `^-?\d+$`. | | `allowlistToolPatterns` | Array of `string` | Optional | Only include tools matching these patterns (e.g., "github\_get\_*", "search\_*"). | | `blocklistToolPatterns` | Array of `string` | Optional | Exclude tools matching these patterns (e.g., "*\_delete", "*\_destroy"). | | `serverOverrides` | Map from string to `string` | Optional | Override server settings for this usage. | | `deferTools` | `boolean` | Optional | Whether this server's tools are deferred. A deferred tool is left out of the model's tool list until the run's tool search loads it. Omission or false declares every tool up front. | ## Request validation {#response-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `serverId` | Minimum length | `1` | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Update prompt variables](/api/conversations/update-prompt-variables) | `POST /api/v1/llm/update-prompt-variables` | | [Update conversation settings](/api/conversations/update-settings) | `POST /api/v1/llm/update-settings` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | | [List available MCP tools](/api/conversations/mcp-list-tools) | `POST /api/v1/llm/mcp-list-tools` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [AgentProfile](/api/models/schema-1hmbcecg1j#response) | Nested in model | | [AgentProfile](/api/models/schema-1hmbcecg1j#request) | Nested in model | | [ConversationSettings](/api/models/schema-ph6avse89k#response) | Nested in model | | [ConversationSettings](/api/models/schema-ph6avse89k#request) | Nested in model | | [GenerationContext](/api/models/schema-1im79fphmq#response) | Nested in model | | [GenerationContext](/api/models/schema-1im79fphmq#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) --- # PromptVariableSpec {#overview} URL: https://docs.travila.ai/api/models/schema-1hkadmq6cl Declares a variable used by a profile’s system-prompt template. Values are supplied through the conversation’s prompt\_variables. When creating a conversation with an explicitly selected profile, a variable\_specs entry with required set to true and no nonempty default\_value causes MISSING\_REQUIRED\_PROMPT\_VARIABLES if the variable is missing. Supply its value at creation; this validation is not repeated for each send or queued turn. Set intended values explicitly even when the specification declares a default. A nonempty default\_value suppresses the creation-time missing-required error but is not automatically inserted into the rendered prompt. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `name` | `string` | Optional | See meaning below. | | `description` | `string` | Optional | Console hint + caller documentation. | | `required` | `boolean` | Optional | Whether a value is required for a profile explicitly selected at conversation creation. This validation does not run for every send or queued turn. | | `defaultValue` | `string` | Optional | A nonempty default value suppresses the creation-time missing-required error. It is not automatically inserted into the rendered prompt; supply intended values explicitly. | | `type` | `string` (`VAR_TYPE_STRING`, `VAR_TYPE_NUMBER`, `VAR_TYPE_BOOL`, `VAR_TYPE_LIST`) or `integer (int32)` | Optional; explicit presence | Optional runtime type for this variable in the template engine. | **`name`** Variable name referenced by the profile’s system-prompt template. e.g. "user\_name" → substituted for \{\{.user\_name}} ### Values of `type` {#request-values-type} Type used to coerce a prompt variable before placing it in the template context. It determines creation-time validation, the authoring control, and how comparisons and joining values behave.
| Value | No. | Form | Meaning | |---|---|---|---| | `VAR_TYPE_STRING` | 0 | Canonical | Treat the variable as text in the template context. | | `VAR_TYPE_NUMBER` | 1 | Canonical | See meaning below. | | `VAR_TYPE_BOOL` | 2 | Canonical | See meaning below. | | `VAR_TYPE_LIST` | 3 | Canonical | See meaning below. | **`VAR_TYPE_NUMBER`** Coerce the variable to a numeric value for arithmetic or numeric comparisons. float64 in the template context (gt/lt/ge…) **`VAR_TYPE_BOOL`** Coerce the variable to a boolean for template conditions. truthiness in \{\{if …}} **`VAR_TYPE_LIST`** Provide a list that templates can iterate or join. \[]interface\{} — joinable, rangeable
## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `name` | `string` | Optional | See meaning below. | | `description` | `string` | Optional | Console hint + caller documentation. | | `required` | `boolean` | Optional | Whether a value is required for a profile explicitly selected at conversation creation. This validation does not run for every send or queued turn. | | `defaultValue` | `string` | Optional | A nonempty default value suppresses the creation-time missing-required error. It is not automatically inserted into the rendered prompt; supply intended values explicitly. | | `type` | `string` (`VAR_TYPE_STRING`, `VAR_TYPE_NUMBER`, `VAR_TYPE_BOOL`, `VAR_TYPE_LIST`) or `integer (int32)` | Optional; explicit presence | Optional runtime type for this variable in the template engine. | **`name`** Variable name referenced by the profile’s system-prompt template. e.g. "user\_name" → substituted for \{\{.user\_name}} ### Values of `type` {#response-values-type} Type used to coerce a prompt variable before placing it in the template context. It determines creation-time validation, the authoring control, and how comparisons and joining values behave.
| Value | No. | Form | Meaning | |---|---|---|---| | `VAR_TYPE_STRING` | 0 | Canonical | Treat the variable as text in the template context. | | `VAR_TYPE_NUMBER` | 1 | Canonical | See meaning below. | | `VAR_TYPE_BOOL` | 2 | Canonical | See meaning below. | | `VAR_TYPE_LIST` | 3 | Canonical | See meaning below. | **`VAR_TYPE_NUMBER`** Coerce the variable to a numeric value for arithmetic or numeric comparisons. float64 in the template context (gt/lt/ge…) **`VAR_TYPE_BOOL`** Coerce the variable to a boolean for template conditions. truthiness in \{\{if …}} **`VAR_TYPE_LIST`** Provide a list that templates can iterate or join. \[]interface\{} — joinable, rangeable
## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` |
Models containing this value | Model | Relationship | |---|---| | [AgentProfile](/api/models/schema-1hmbcecg1j#response) | Nested in model | | [AgentProfile](/api/models/schema-1hmbcecg1j#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) --- # AgentProfile {#overview} URL: https://docs.travila.ai/api/models/schema-1hmbcecg1j A reusable persona with model configuration, tools and metadata describing when it should be selected. See the profile-selection and versioning guide for profile resolution and fragment versions. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `profileId` | `string` | Optional | Stable id, unique within the project library. | | `name` | `string` | Optional | See meaning below. | | `description` | `string` | Optional | Human-facing summary. | | `whenToUse` | `string` | Optional | Routing hint, Skill-style "use when…" | | `keywords` | Array of `string` | Optional | Keywords associated with discovery or selection of the agent profile. | | `enabled` | `boolean` | Optional; explicit presence | Whether the profile is enabled for selection. Omission during creation defaults to true; an explicitly false value creates a disabled profile. Disabled profiles are not selectable. | | `generationConfig` | [GenerationConfig](/api/models/schema-1h82h7ri5p#request) | Optional | Model, sampling, and tool configuration used for generation. | | `mcpServers` | Array of [MCPServerReference](/api/models/schema-1hik90rmo1#request) | Optional | MCP servers used for tool discovery when this profile is active. This list replaces the conversation-wide MCP server list for those turns. | | `variableSpecs` | Array of [PromptVariableSpec](/api/models/schema-1hkadmq6cl#request) | Optional | Variables consumed by the profile’s system-prompt template, rendered from the conversation’s prompt\_variables. | | `version` | `string (int64)` | Optional | Output-only immutable revision of the profile. Versions start at one and increase on successful mutations; values supplied on writes are ignored. Pattern: `^-?\d+$`. | **`name`** Display name used when selecting an agent profile. e.g. "Nutrition Coach" ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `profileId` | `string` | Optional | Stable id, unique within the project library. | | `name` | `string` | Optional | See meaning below. | | `description` | `string` | Optional | Human-facing summary. | | `whenToUse` | `string` | Optional | Routing hint, Skill-style "use when…" | | `keywords` | Array of `string` | Optional | Keywords associated with discovery or selection of the agent profile. | | `enabled` | `boolean` | Optional; explicit presence | Whether the profile is enabled for selection. Omission during creation defaults to true; an explicitly false value creates a disabled profile. Disabled profiles are not selectable. | | `generationConfig` | [GenerationConfig](/api/models/schema-1h82h7ri5p#response) | Optional | Model, sampling, and tool configuration used for generation. | | `mcpServers` | Array of [MCPServerReference](/api/models/schema-1hik90rmo1#response) | Optional | MCP servers used for tool discovery when this profile is active. This list replaces the conversation-wide MCP server list for those turns. | | `variableSpecs` | Array of [PromptVariableSpec](/api/models/schema-1hkadmq6cl#response) | Optional | Variables consumed by the profile’s system-prompt template, rendered from the conversation’s prompt\_variables. | | `version` | `string (int64)` | Optional | Output-only immutable revision of the profile. Versions start at one and increase on successful mutations; values supplied on writes are ignored. Pattern: `^-?\d+$`. | **`name`** Display name used when selecting an agent profile. e.g. "Nutrition Coach" ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create an agent profile](/api/agent-profiles/create-agent-profile) | `POST /api/v1/agent-profiles/create` | | [Get an agent profile](/api/agent-profiles/get-agent-profile) | `POST /api/v1/agent-profiles/get` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List agent profiles](/api/agent-profiles/list-agent-profiles) | `POST /api/v1/agent-profiles/list` | | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) --- # StructuredMessage {#overview} URL: https://docs.travila.ai/api/models/schema-1ho1lk4ndj A structured message whose JSON payload has been validated against a declared schema. Consumers can trust that json\_payload conforms to the schema identified by schema\_name. Inspect the run outcome before treating any message as complete. Current structured metadata is attached to a text content part through [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/schema-1hqi9r2bhh#response-field-structuredmessage) can be absent. Use an object at the schema root and validate the exact final response your application consumes; server validation covers only the first model choice. For integers that your JSON client cannot represent exactly, define string-valued fields in your schema instead of converting them through floating point. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `jsonPayload` | Map from string to JSON value | Optional | The validated JSON payload as a Struct (preserves types) | | `schemaName` | `string` | Optional | Schema identifier (from ResponseFormat.schema\_name) | | `healed` | `boolean` | Optional | Whether response healing is reported for this structured message. Currently returned as false. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `jsonPayload` | Map from string to JSON value | Optional | The validated JSON payload as a Struct (preserves types) | | `schemaName` | `string` | Optional | Schema identifier (from ResponseFormat.schema\_name) | | `healed` | `boolean` | Optional | Whether response healing is reported for this structured message. Currently returned as false. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [List MCP resources](/api/conversations/mcp-list-resources) | `POST /api/v1/llm/mcp-list-resources` | | [Read an MCP resource](/api/conversations/mcp-read-resource) | `POST /api/v1/llm/mcp-read-resource` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [ContentPart](/api/models/schema-1hqi9r2bhh#response) | Nested in model | | [ContentPart](/api/models/schema-1hqi9r2bhh#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # ContentPart {#overview} URL: https://docs.travila.ai/api/models/schema-1hqi9r2bhh Content parts composing a message, using a flattened structure for JSON compatibility. The `type` identifies how the content is represented; only defined content types are accepted. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `type` | `string` (`CONTENT_PART_TYPE_TEXT`, `CONTENT_PART_TYPE_IMAGE_URL`, `CONTENT_PART_TYPE_IMAGE_BASE64`, `CONTENT_PART_TYPE_FILE_ID`, `CONTENT_PART_TYPE_FILE_PATH`, `CONTENT_PART_TYPE_FILE_URL`, `CONTENT_PART_TYPE_FILE_DATA_URL`, `CONTENT_PART_TYPE_AUDIO_BASE64`, `CONTENT_PART_TYPE_REASONING`) or `integer (int32)` (`0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`) | Optional; explicit presence | Kind of content carried by this message part. | | `content` | `string` | Optional | Text content, image URL, file ID, or base64-encoded data. | | `metadata` | Map from string to `string` | Optional | Additional type-specific metadata (dimensions, mime\_type, etc.). | | `cachePreferred` | `boolean` | Optional | Hint that this part is eligible for provider prompt caching. | | `structuredMessage` | [StructuredMessage](/api/models/schema-1ho1lk4ndj#request) | Optional | Populated on TEXT parts for structured output responses. | ### Values of `type` {#request-values-type} Discriminator identifying which content representation a message part carries.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTENT_PART_TYPE_TEXT` | 0 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_URL` | 1 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_BASE64` | 2 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_ID` | 3 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_PATH` | 4 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_URL` | 5 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_DATA_URL` | 6 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_AUDIO_BASE64` | 7 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_REASONING` | 8 | Canonical | See meaning below. | **`CONTENT_PART_TYPE_TEXT`** Plain text carried by the content part. Plain text content **`CONTENT_PART_TYPE_IMAGE_URL`** An image supplied through a remote URL. Remote image URL **`CONTENT_PART_TYPE_IMAGE_BASE64`** An image supplied as base64-encoded bytes. Base64-encoded image data **`CONTENT_PART_TYPE_FILE_ID`** A provider file identifier or internal storage identifier resolved before generation. File ID — a provider file ID (e.g., OpenAI) OR an internal storage file ID; resolved to a signed FILE\_URL just-in-time before the model-provider request **`CONTENT_PART_TYPE_FILE_PATH`** A reference to a local file path. Local file path reference **`CONTENT_PART_TYPE_FILE_URL`** A file supplied through a public or signed URL. Public or signed file URL (e.g., PDF URL or data: URL) **`CONTENT_PART_TYPE_FILE_DATA_URL`** A file embedded in a data URL, including its media type and encoded data. data\:application/pdf;base64,... or similar **`CONTENT_PART_TYPE_AUDIO_BASE64`** Base64-encoded audio; the part metadata identifies its audio format. Base64-encoded audio (metadata.format required, e.g., wav/mp3) **`CONTENT_PART_TYPE_REASONING`** A reasoning segment returned by a model provider, when available. Reasoning/thinking content from chain-of-thought models
## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `type` | Defined enum value | `true` | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `type` | `string` (`CONTENT_PART_TYPE_TEXT`, `CONTENT_PART_TYPE_IMAGE_URL`, `CONTENT_PART_TYPE_IMAGE_BASE64`, `CONTENT_PART_TYPE_FILE_ID`, `CONTENT_PART_TYPE_FILE_PATH`, `CONTENT_PART_TYPE_FILE_URL`, `CONTENT_PART_TYPE_FILE_DATA_URL`, `CONTENT_PART_TYPE_AUDIO_BASE64`, `CONTENT_PART_TYPE_REASONING`) or `integer (int32)` | Optional; explicit presence | Kind of content carried by this message part. | | `content` | `string` | Optional | Text content, image URL, file ID, or base64-encoded data. | | `metadata` | Map from string to `string` | Optional | Additional type-specific metadata (dimensions, mime\_type, etc.). | | `cachePreferred` | `boolean` | Optional | Hint that this part is eligible for provider prompt caching. | | `structuredMessage` | [StructuredMessage](/api/models/schema-1ho1lk4ndj#response) | Optional | Populated on TEXT parts for structured output responses. | ### Values of `type` {#response-values-type} Discriminator identifying which content representation a message part carries.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONTENT_PART_TYPE_TEXT` | 0 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_URL` | 1 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_IMAGE_BASE64` | 2 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_ID` | 3 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_PATH` | 4 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_URL` | 5 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_FILE_DATA_URL` | 6 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_AUDIO_BASE64` | 7 | Canonical | See meaning below. | | `CONTENT_PART_TYPE_REASONING` | 8 | Canonical | See meaning below. | **`CONTENT_PART_TYPE_TEXT`** Plain text carried by the content part. Plain text content **`CONTENT_PART_TYPE_IMAGE_URL`** An image supplied through a remote URL. Remote image URL **`CONTENT_PART_TYPE_IMAGE_BASE64`** An image supplied as base64-encoded bytes. Base64-encoded image data **`CONTENT_PART_TYPE_FILE_ID`** A provider file identifier or internal storage identifier resolved before generation. File ID — a provider file ID (e.g., OpenAI) OR an internal storage file ID; resolved to a signed FILE\_URL just-in-time before the model-provider request **`CONTENT_PART_TYPE_FILE_PATH`** A reference to a local file path. Local file path reference **`CONTENT_PART_TYPE_FILE_URL`** A file supplied through a public or signed URL. Public or signed file URL (e.g., PDF URL or data: URL) **`CONTENT_PART_TYPE_FILE_DATA_URL`** A file embedded in a data URL, including its media type and encoded data. data\:application/pdf;base64,... or similar **`CONTENT_PART_TYPE_AUDIO_BASE64`** Base64-encoded audio; the part metadata identifies its audio format. Base64-encoded audio (metadata.format required, e.g., wav/mp3) **`CONTENT_PART_TYPE_REASONING`** A reasoning segment returned by a model provider, when available. Reasoning/thinking content from chain-of-thought models
## Request validation {#response-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `type` | Defined enum value | `true` | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [List MCP resources](/api/conversations/mcp-list-resources) | `POST /api/v1/llm/mcp-list-resources` | | [Read an MCP resource](/api/conversations/mcp-read-resource) | `POST /api/v1/llm/mcp-read-resource` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [Message](/api/models/schema-1j3dcf7kvu#response) | Nested in model | | [Message](/api/models/schema-1j3dcf7kvu#request) | Nested in model | | [PdfAnnotation](/api/models/schema-1hsi58i6pb#response) | Nested in model | | [PdfAnnotation](/api/models/schema-1hsi58i6pb#request) | Nested in model | | [Resource](/api/models/schema-pbf83hf239#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # PdfAnnotation {#overview} URL: https://docs.travila.ai/api/models/schema-1hsi58i6pb Provider annotation identifying a parsed PDF and reusable parsing output. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `filename` | `string` | Optional | Optional identifying information about the original file | | `engine` | `string` | Optional | PDF parsing engine used by provider (e.g., "pdf-text", "mistral-ocr", "native") | | `token` | `string` | Optional | Opaque provider token or handle allowing reuse without re-parsing | | `sourceUrl` | `string` | Optional | Optional: original source reference (public URL or data: URL) | | `hash` | `string` | Optional | Provider-supplied hash identifying the parsed file. | | `content` | Array of [ContentPart](/api/models/schema-1hqi9r2bhh#request) | Optional | Optional structured content returned by provider annotations (text, image URLs, etc.) Note: This can be large; include only if you need to round-trip provider annotations. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `filename` | `string` | Optional | Optional identifying information about the original file | | `engine` | `string` | Optional | PDF parsing engine used by provider (e.g., "pdf-text", "mistral-ocr", "native") | | `token` | `string` | Optional | Opaque provider token or handle allowing reuse without re-parsing | | `sourceUrl` | `string` | Optional | Optional: original source reference (public URL or data: URL) | | `hash` | `string` | Optional | Provider-supplied hash identifying the parsed file. | | `content` | Array of [ContentPart](/api/models/schema-1hqi9r2bhh#response) | Optional | Optional structured content returned by provider annotations (text, image URLs, etc.) Note: This can be large; include only if you need to round-trip provider annotations. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [Annotation](/api/models/schema-1i0hjer0pd#response) | Nested in model | | [Annotation](/api/models/schema-1i0hjer0pd#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # UrlCitation {#overview} URL: https://docs.travila.ai/api/models/schema-1hujls61ng Web source and character range cited in generated message content. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `url` | `string` | Optional | URL of the cited web page. | | `title` | `string` | Optional | Title of the web page cited by this annotation. | | `content` | `string` | Optional | Optional excerpt or snippet of the cited web page. | | `startIndex` | `string (int64)` | Optional | Character index in message content. Pattern: `^-?\d+$`. | | `endIndex` | `string (int64)` | Optional | Character index in message content. Pattern: `^-?\d+$`. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `url` | `string` | Optional | URL of the cited web page. | | `title` | `string` | Optional | Title of the web page cited by this annotation. | | `content` | `string` | Optional | Optional excerpt or snippet of the cited web page. | | `startIndex` | `string (int64)` | Optional | Character index in message content. Pattern: `^-?\d+$`. | | `endIndex` | `string (int64)` | Optional | Character index in message content. Pattern: `^-?\d+$`. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [Annotation](/api/models/schema-1i0hjer0pd#response) | Nested in model | | [Annotation](/api/models/schema-1i0hjer0pd#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # Annotation {#overview} URL: https://docs.travila.ai/api/models/schema-1i0hjer0pd Tagged provider annotation attached to generated content, such as a citation or PDF reference. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `kind` | `string` (`ANNOTATION_KIND_URL_CITATION`, `ANNOTATION_KIND_PDF`) or `integer (int32)` | Optional; explicit presence | Selected kind; determines which submessage is populated | | `urlCitation` | [UrlCitation](/api/models/schema-1hujls61ng#request) | Optional | Submessage fields (optional); populate the one matching kind | | `pdf` | [PdfAnnotation](/api/models/schema-1hsi58i6pb#request) | Optional | PDF annotation identifying the parsed file and available parsing output. | | `metadata` | Map from string to `string` | Optional | Provider-specific extras. | ### Values of `kind` {#request-values-kind} Kind of source annotation associated with generated content.
| Value | No. | Form | Meaning | |---|---|---|---| | `ANNOTATION_KIND_URL_CITATION` | 0 | Canonical | A citation to a source identified by its URL. | | `ANNOTATION_KIND_PDF` | 1 | Canonical | An annotation identifying source content in a PDF document. |
## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `kind` | `string` (`ANNOTATION_KIND_URL_CITATION`, `ANNOTATION_KIND_PDF`) or `integer (int32)` | Optional; explicit presence | Selected kind; determines which submessage is populated | | `urlCitation` | [UrlCitation](/api/models/schema-1hujls61ng#response) | Optional | Submessage fields (optional); populate the one matching kind | | `pdf` | [PdfAnnotation](/api/models/schema-1hsi58i6pb#response) | Optional | PDF annotation identifying the parsed file and available parsing output. | | `metadata` | Map from string to `string` | Optional | Provider-specific extras. | ### Values of `kind` {#response-values-kind} Kind of source annotation associated with generated content.
| Value | No. | Form | Meaning | |---|---|---|---| | `ANNOTATION_KIND_URL_CITATION` | 0 | Canonical | A citation to a source identified by its URL. | | `ANNOTATION_KIND_PDF` | 1 | Canonical | An annotation identifying source content in a PDF document. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [Message](/api/models/schema-1j3dcf7kvu#response) | Nested in model | | [Message](/api/models/schema-1j3dcf7kvu#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # ClientContext {#overview} URL: https://docs.travila.ai/api/models/schema-1i2sndrl93 Opaque caller-supplied attributes attached to a conversation message. Values are strings, including values such as `"false"`. The schema allows at most 32 pairs, keys of at most 64 characters, and values of at most 1,024 characters. Keep the entire map well below 8 KiB: Travila also applies an encoded-size limit that includes field overhead and drops context that exceeds it. Short page identifiers and a few relevant values are preferable to a page dump; an oversized map is not automatically shortened. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `values` | Map from string to `string` | Optional | Arbitrary client-supplied context for this message (e.g. page, referrer, device, in-app flow). Keys/values are opaque strings. Maximum properties: 32. | ## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `values` | Max Pairs | `32` | | `values` | Keys · Maximum length | `64` | | `values` | Values · Maximum length | `1024` | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `values` | Map from string to `string` | Optional | Arbitrary client-supplied context for this message (e.g. page, referrer, device, in-app flow). Keys/values are opaque strings. | ## Request validation {#response-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `values` | Max Pairs | `32` | | `values` | Keys · Maximum length | `64` | | `values` | Values · Maximum length | `1024` | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [Message](/api/models/schema-1j3dcf7kvu#response) | Nested in model | | [Message](/api/models/schema-1j3dcf7kvu#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # ClientToolResult {#overview} URL: https://docs.travila.ai/api/models/schema-1i4kndhs46 Result submitted by the caller for a client-side tool call. Both tool\_call\_id and tool\_name must identify the same pending call. When submission reaches workflow validation, either missing value causes a 400 response. Copy the call's id and name into these result fields, rather than submitting the pending ToolCall unchanged. Fields marked optional in the wire shape may still be required for a valid workflow submission. Both `tool_call_id` and `tool_name` must identify the same pending call; workflow validation rejects either missing value. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `toolCallId` | `string` | Optional | Required call identifier, copied from the pending ToolCall.id. | | `toolName` | `string` | Optional | Required tool name, copied from the pending ToolCall.name. | | `resultJson` | Map from string to JSON value | Optional | Structured output for a matched pending call. A nonempty object records COMPLETED; an empty or omitted object records FAILED, including when the client could not complete the action. | | `error` | [RpcError](/api/models/schema-1fajlacjs0#request) | Optional | Supplied error detail. The current result handler does not consume this field; the presence of a nonempty result\_json alone determines whether the tool is recorded as completed. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Submit client-side tool execution results](/api/conversations/submit-client-tool-results) | `POST /api/v1/llm/submit-client-tool-results` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # CompletionTokensDetails {#overview} URL: https://docs.travila.ai/api/models/schema-1i6q4qpg72 Breakdown of completion-token usage. Categories are measured by different upstream tokenizers and need not sum to completion\_tokens; reasoning\_tokens can exceed completion\_tokens. One category must not be derived by subtracting the others. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `reasoningTokens` | `string (int64)` | Optional | Tokens used for reasoning/thinking. Pattern: `^-?\d+$`. | | `imageTokens` | `string (int64)` | Optional | Completion tokens emitted as image output. Pattern: `^-?\d+$`. | | `audioTokens` | `string (int64)` | Optional | Completion tokens emitted as audio output. Pattern: `^-?\d+$`. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `reasoningTokens` | `string (int64)` | Optional | Tokens used for reasoning/thinking. Pattern: `^-?\d+$`. | | `imageTokens` | `string (int64)` | Optional | Completion tokens emitted as image output. Pattern: `^-?\d+$`. | | `audioTokens` | `string (int64)` | Optional | Completion tokens emitted as audio output. Pattern: `^-?\d+$`. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [Usage](/api/models/schema-1j1vov2uoh#response) | Nested in model | | [Usage](/api/models/schema-1j1vov2uoh#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # ConversationThread {#overview} URL: https://docs.travila.ai/api/models/schema-1i84dsgmg6 Lightweight conversation-thread registry record used for managing multiple threads. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `threadId` | `string` | Optional | See meaning below. | | `title` | `string` | Optional | Display title of the conversation thread. | | `tags` | Array of `string` | Optional | Labels associated with the resource for organization or filtering. | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | | `updatedAt` | `string (date-time)` | Optional | Time when this record was last updated. | | `externalId` | `string` | Optional | Caller-supplied identifier associated with the conversation thread. | **`threadId`** Identifier of the conversation thread. key used for ConversationActorService ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # CostDetails {#overview} URL: https://docs.travila.ai/api/models/schema-1ia0h761lm Breakdown of model-provider cost. When the customer supplies the provider key, usage.cost is zero and upstream\_inference\_cost reports the provider spend, split into prompt and completion components. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `upstreamInferenceCost` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Total upstream provider cost (USD) on BYOK routes. | | `upstreamInferencePromptCost` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Upstream cost attributed to prompt tokens (USD). | | `upstreamInferenceCompletionCost` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Upstream cost attributed to completion tokens (USD). | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `upstreamInferenceCost` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Total upstream provider cost (USD) on BYOK routes. | | `upstreamInferencePromptCost` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Upstream cost attributed to prompt tokens (USD). | | `upstreamInferenceCompletionCost` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Upstream cost attributed to completion tokens (USD). | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [Usage](/api/models/schema-1j1vov2uoh#response) | Nested in model | | [Usage](/api/models/schema-1j1vov2uoh#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # ExperimentContext {#overview} URL: https://docs.travila.ai/api/models/schema-1icbr3lltu Dataset-run attribution attached when a scripted evaluation turn is sent. Supported on SendMessageRequest and SendMessageSyncRequest; ordinary conversation traffic leaves it unset. The attribution must accompany the turn so its observations can be associated with the dataset run; a separate post-run link does not supply this attribution. The dataset is required when experiment context is supplied. This attribution is separate from client\_context, which is included in model prompt context. Do not place evaluation attribution in prompt context. dataset\_item\_id is optional: a run can be scored from its traces without assigning each turn to a dataset item. profile\_revision\_hash supplies a profile revision fingerprint for comparison and attribution. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `datasetId` | `string` | **Required in requests** | Identifier of the dataset to which this run belongs. Required whenever experiment context is supplied. Minimum length: 1. | | `runName` | `string` | **Required in requests** | Names the run. Repeating a run\_name for the same dataset appends to that run rather than starting a new one, because the derived experiment id is deterministic — the same property that lets a retried turn land in the run it belongs to. Minimum length: 1. | | `datasetItemId` | `string` | Optional | Which dataset item this turn exercises. Optional: a run can be scored on its traces alone, and a harness that does not model items per-turn can leave it empty. | | `description` | `string` | Optional | Free-text description displayed with the dataset run. | | `metadataJson` | `string` | Optional | Additional run metadata serialized as a JSON object string and carried through unchanged. | | `profileRevisionHash` | `string` | Optional | Profile revision fingerprint attached to the dataset run for comparison and attribution. | ## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `datasetId` | Minimum length | `1` | | `runName` | Minimum length | `1` | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # MemoryReference {#overview} URL: https://docs.travila.ai/api/models/schema-1ie9a4bgk5 A memory record retrieved and included in generation context. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `memoryId` | `string` | Optional | Identifier of the retrieved memory record. | | `score` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Relevance score reported by the memory provider for this match. | | `memoryText` | `string` | Optional | Text of the retrieved memory record. | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | | `updatedAt` | `string (date-time)` | Optional | Time when this record was last updated. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `memoryId` | `string` | Optional | Identifier of the retrieved memory record. | | `score` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Relevance score reported by the memory provider for this match. | | `memoryText` | `string` | Optional | Text of the retrieved memory record. | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | | `updatedAt` | `string (date-time)` | Optional | Time when this record was last updated. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [GenerationContext](/api/models/schema-1im79fphmq#response) | Nested in model | | [GenerationContext](/api/models/schema-1im79fphmq#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # MemorySearchParams {#overview} URL: https://docs.travila.ai/api/models/schema-1igd5iut01 Parameters used to retrieve relevant memories during generation. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `query` | `string` | Optional | Text submitted to memory retrieval for this generation. | | `topK` | `string (int64)` | Optional | Maximum memory matches requested during generation-context retrieval. Pattern: `^-?\d+$`. | | `threshold` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Minimum relevance threshold requested for the memory query. | | `rerank` | `boolean` | Optional | Whether reranking was requested for the memory search. | | `resultsReturned` | `string (int64)` | Optional | Number of memory records returned by the search. Pattern: `^-?\d+$`. | | `relationsReturned` | `string (int64)` | Optional | Number of graph relationships returned by the search. Pattern: `^-?\d+$`. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `query` | `string` | Optional | Text submitted to memory retrieval for this generation. | | `topK` | `string (int64)` | Optional | Maximum memory matches requested during generation-context retrieval. Pattern: `^-?\d+$`. | | `threshold` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Minimum relevance threshold requested for the memory query. | | `rerank` | `boolean` | Optional | Whether reranking was requested for the memory search. | | `resultsReturned` | `string (int64)` | Optional | Number of memory records returned by the search. Pattern: `^-?\d+$`. | | `relationsReturned` | `string (int64)` | Optional | Number of graph relationships returned by the search. Pattern: `^-?\d+$`. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [GenerationContext](/api/models/schema-1im79fphmq#response) | Nested in model | | [GenerationContext](/api/models/schema-1im79fphmq#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # RelationReference {#overview} URL: https://docs.travila.ai/api/models/schema-1ijit8ceuv A graph relationship retrieved and included in generation context. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `source` | `string` | Optional | Source entity of the memory graph relationship. | | `relationship` | `string` | Optional | Relationship label connecting the source and destination entities. | | `destination` | `string` | Optional | Destination entity of the memory graph relationship. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `source` | `string` | Optional | Source entity of the memory graph relationship. | | `relationship` | `string` | Optional | Relationship label connecting the source and destination entities. | | `destination` | `string` | Optional | Destination entity of the memory graph relationship. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [GenerationContext](/api/models/schema-1im79fphmq#response) | Nested in model | | [GenerationContext](/api/models/schema-1im79fphmq#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # TurnInfo {#overview} URL: https://docs.travila.ai/api/models/schema-1ilcikuhu8 Turn position within an agentic generation run Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `currentTurn` | `string (int64)` | Optional | Current turn position within the generation run. Pattern: `^-?\d+$`. | | `maxTurns` | `string (int64)` | Optional | Maximum turns configured for the generation run. Pattern: `^-?\d+$`. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `currentTurn` | `string (int64)` | Optional | Current turn position within the generation run. Pattern: `^-?\d+$`. | | `maxTurns` | `string (int64)` | Optional | Maximum turns configured for the generation run. Pattern: `^-?\d+$`. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [GenerationContext](/api/models/schema-1im79fphmq#response) | Nested in model | | [GenerationContext](/api/models/schema-1im79fphmq#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # GenerationContext {#overview} URL: https://docs.travila.ai/api/models/schema-1im79fphmq Snapshot of retrieval inputs, prompt provenance, and turn position that shaped a generated message. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `memories` | Array of [MemoryReference](/api/models/schema-1ie9a4bgk5#request) | Optional | Memory records captured in the generation context. | | `relations` | Array of [RelationReference](/api/models/schema-1ijit8ceuv#request) | Optional | Graph relationships captured in the generation context. | | `memorySearch` | [MemorySearchParams](/api/models/schema-1igd5iut01#request) | Optional | Memory-query parameters and counts recorded for this generation. | | `turn` | [TurnInfo](/api/models/schema-1ilcikuhu8#request) | Optional | Turn position and limit within the generation run. | | `languagePreference` | `string` | Optional | Language preference associated with the generation context. | | `resolvedSystemPrompt` | `string` | Optional | System prompt selected for this generation after prompt precedence is resolved. This field is retained in the schema but is not populated; use resolved\_prompt\_hash for recorded prompt identity. | | `profileId` | `string` | Optional | Agent profile that produced this message ("" if none active). | | `model` | `string` | Optional | Model actually used for this generation. | | `promptSource` | `string` (`PROMPT_SOURCE_CLIENT_OVERRIDE`, `PROMPT_SOURCE_PROFILE_TEMPLATE`, `PROMPT_SOURCE_DEFAULT_CONFIG`) or `integer (int32)` | Optional; explicit presence | Which precedence tier supplied the prompt. | | `baseConfig` | [GenerationConfig](/api/models/schema-1h82h7ri5p#request) | Optional | See meaning below. | | `overrideConfig` | [GenerationConfig](/api/models/schema-1h82h7ri5p#request) | Optional | Per-call generation configuration supplied before the override merge. | | `profileVersion` | `string (int64)` | Optional | Immutable version of the active agent profile used to render this turn’s prompt. Absent on older turns and turns without a profile template. Pattern: `^-?\d+$`. | | `fragmentsVersion` | `string (int64)` | Optional | Version of the prompt-fragment set used to render the profile prompt. Pattern: `^-?\d+$`. | | `promptVariables` | Map from string to JSON value | Optional | Values bound to the prompt template for this generation. | | `profileRenderFailed` | `boolean` | Optional | Whether rendering the profile prompt failed for this generation. | | `resolvedPromptHash` | `string` | Optional | SHA-256 hash, as 64 hexadecimal characters, of the resolved system prompt before the current-time instruction is appended. Identifies prompt content only, excluding model and sampling parameters. Absent on older turns without prompt capture. | | `resolvedUserContext` | `string` | Optional | See meaning below. | | `resolvedMcpServers` | Array of [MCPServerReference](/api/models/schema-1hik90rmo1#request) | Optional | See meaning below. | **`baseConfig`** Generation configuration resolved at send time before per-call overrides and timeout adjustments, with system\_prompt omitted. The active profile supplies the base when selected; otherwise the conversation default does. Use prompt\_source and profile\_id for prompt attribution. The base configuration can be absent when neither source supplies one or no snapshot was captured. For a supplied per-call override, the populated top-level fields of override\_config overlay base\_config to form the effective configuration. override\_config can be absent when no override was supplied. **`resolvedUserContext`** The literal user-context text supplied to the model for this turn, including the available name, locale and location conditions. It is a captured prompt input, not a reconstruction from the user’s current profile. The value is computed once per turn and reused across its model calls. It can be empty when location context is unavailable, enrichment fails or the turn predates capture. **`resolvedMcpServers`** The MCP server list used for this turn after resolving conversation settings, the active profile, and any per-turn `override_mcp_servers`. It determines both tool discovery and the allow/block rules applied by `CallTool`. A per-turn override does not change the conversation's stored MCP settings. Compare this snapshot with `settings.mcp_servers` to inspect how the turn's tool set differed. Empty on turns predating capture and on threads with no MCP servers. ### Values of `promptSource` {#request-values-promptsource} Source that supplied the effective system prompt for a generation turn. Distinguishes a client override, a profile template and the conversation default configuration for prompt attribution.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROMPT_SOURCE_CLIENT_OVERRIDE` | 0 | Canonical | See meaning below. | | `PROMPT_SOURCE_PROFILE_TEMPLATE` | 1 | Canonical | See meaning below. | | `PROMPT_SOURCE_DEFAULT_CONFIG` | 2 | Canonical | See meaning below. | **`PROMPT_SOURCE_CLIENT_OVERRIDE`** The caller supplied the prompt through the send request's generation-configuration override. SendRequest.override\_generation\_config **`PROMPT_SOURCE_PROFILE_TEMPLATE`** The prompt was rendered from the active agent profile template. active agent profile's rendered template **`PROMPT_SOURCE_DEFAULT_CONFIG`** The prompt came from the conversation or project default generation configuration. conversation/project default\_generation\_config
## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `memories` | Array of [MemoryReference](/api/models/schema-1ie9a4bgk5#response) | Optional | Memory records captured in the generation context. | | `relations` | Array of [RelationReference](/api/models/schema-1ijit8ceuv#response) | Optional | Graph relationships captured in the generation context. | | `memorySearch` | [MemorySearchParams](/api/models/schema-1igd5iut01#response) | Optional | Memory-query parameters and counts recorded for this generation. | | `turn` | [TurnInfo](/api/models/schema-1ilcikuhu8#response) | Optional | Turn position and limit within the generation run. | | `languagePreference` | `string` | Optional | Language preference associated with the generation context. | | `resolvedSystemPrompt` | `string` | Optional | System prompt selected for this generation after prompt precedence is resolved. This field is retained in the schema but is not populated; use resolved\_prompt\_hash for recorded prompt identity. | | `profileId` | `string` | Optional | Agent profile that produced this message ("" if none active). | | `model` | `string` | Optional | Model actually used for this generation. | | `promptSource` | `string` (`PROMPT_SOURCE_CLIENT_OVERRIDE`, `PROMPT_SOURCE_PROFILE_TEMPLATE`, `PROMPT_SOURCE_DEFAULT_CONFIG`) or `integer (int32)` | Optional; explicit presence | Which precedence tier supplied the prompt. | | `baseConfig` | [GenerationConfig](/api/models/schema-1h82h7ri5p#response) | Optional | See meaning below. | | `overrideConfig` | [GenerationConfig](/api/models/schema-1h82h7ri5p#response) | Optional | Per-call generation configuration supplied before the override merge. | | `profileVersion` | `string (int64)` | Optional | Immutable version of the active agent profile used to render this turn’s prompt. Absent on older turns and turns without a profile template. Pattern: `^-?\d+$`. | | `fragmentsVersion` | `string (int64)` | Optional | Version of the prompt-fragment set used to render the profile prompt. Pattern: `^-?\d+$`. | | `promptVariables` | Map from string to JSON value | Optional | Values bound to the prompt template for this generation. | | `profileRenderFailed` | `boolean` | Optional | Whether rendering the profile prompt failed for this generation. | | `resolvedPromptHash` | `string` | Optional | SHA-256 hash, as 64 hexadecimal characters, of the resolved system prompt before the current-time instruction is appended. Identifies prompt content only, excluding model and sampling parameters. Absent on older turns without prompt capture. | | `resolvedUserContext` | `string` | Optional | See meaning below. | | `resolvedMcpServers` | Array of [MCPServerReference](/api/models/schema-1hik90rmo1#response) | Optional | See meaning below. | **`baseConfig`** Generation configuration resolved at send time before per-call overrides and timeout adjustments, with system\_prompt omitted. The active profile supplies the base when selected; otherwise the conversation default does. Use prompt\_source and profile\_id for prompt attribution. The base configuration can be absent when neither source supplies one or no snapshot was captured. For a supplied per-call override, the populated top-level fields of override\_config overlay base\_config to form the effective configuration. override\_config can be absent when no override was supplied. **`resolvedUserContext`** The literal user-context text supplied to the model for this turn, including the available name, locale and location conditions. It is a captured prompt input, not a reconstruction from the user’s current profile. The value is computed once per turn and reused across its model calls. It can be empty when location context is unavailable, enrichment fails or the turn predates capture. **`resolvedMcpServers`** The MCP server list used for this turn after resolving conversation settings, the active profile, and any per-turn `override_mcp_servers`. It determines both tool discovery and the allow/block rules applied by `CallTool`. A per-turn override does not change the conversation's stored MCP settings. Compare this snapshot with `settings.mcp_servers` to inspect how the turn's tool set differed. Empty on turns predating capture and on threads with no MCP servers. ### Values of `promptSource` {#response-values-promptsource} Source that supplied the effective system prompt for a generation turn. Distinguishes a client override, a profile template and the conversation default configuration for prompt attribution.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROMPT_SOURCE_CLIENT_OVERRIDE` | 0 | Canonical | See meaning below. | | `PROMPT_SOURCE_PROFILE_TEMPLATE` | 1 | Canonical | See meaning below. | | `PROMPT_SOURCE_DEFAULT_CONFIG` | 2 | Canonical | See meaning below. | **`PROMPT_SOURCE_CLIENT_OVERRIDE`** The caller supplied the prompt through the send request's generation-configuration override. SendRequest.override\_generation\_config **`PROMPT_SOURCE_PROFILE_TEMPLATE`** The prompt was rendered from the active agent profile template. active agent profile's rendered template **`PROMPT_SOURCE_DEFAULT_CONFIG`** The prompt came from the conversation or project default generation configuration. conversation/project default\_generation\_config
## Where used {#where-used} | Reference | Relationship | |---|---| | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [Message](/api/models/schema-1j3dcf7kvu#response) | Nested in model | | [Message](/api/models/schema-1j3dcf7kvu#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # MCPServerInfo {#overview} URL: https://docs.travila.ai/api/models/schema-1ipatl4liq Detailed server information ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `serverId` | `string` | Optional | Identifier of the MCP server associated with the operation or tool. | | `name` | `string` | Optional | Display name of the MCP server. | | `version` | `string` | Optional | Version of the resource represented by this message. | | `capabilities` | Array of `string` | Optional | Capabilities reported by the MCP server. | | `metadata` | Map from string to `string` | Optional | Additional attributes associated with the resource. | | `status` | `string` (`MCP_SERVER_CONNECTION_STATUS_CONNECTED`, `MCP_SERVER_CONNECTION_STATUS_DISCONNECTED`, `MCP_SERVER_CONNECTION_STATUS_ERROR`, `MCP_SERVER_CONNECTION_STATUS_DISCOVERING`) or `integer (int32)` | Optional; explicit presence | Current connection status reported for the MCP server. | | `availableTools` | Array of [ToolDefinition](/api/models/schema-1gomaj79cc#response) | Optional | Tool definitions currently reported by the MCP server. | | `kind` | `string` (`MCP_SERVER_KIND_INTERNAL`, `MCP_SERVER_KIND_BUILT_IN`, `MCP_SERVER_KIND_CUSTOM`, `MCP_SERVER_KIND_EXTERNAL`, `MCP_SERVER_KIND_INTEGRATION`) or `integer (int32)` | Optional; explicit presence | Ownership category of the MCP server definition. | ### Values of `status` {#response-values-status} Current connection or discovery condition reported for an MCP server.
| Value | No. | Form | Meaning | |---|---|---|---| | `MCP_SERVER_CONNECTION_STATUS_CONNECTED` | 0 | Canonical | A connection to the MCP server is established. | | `MCP_SERVER_CONNECTION_STATUS_DISCONNECTED` | 1 | Canonical | There is no active connection to the MCP server. | | `MCP_SERVER_CONNECTION_STATUS_ERROR` | 2 | Canonical | A connection or discovery attempt encountered an error. | | `MCP_SERVER_CONNECTION_STATUS_DISCOVERING` | 3 | Canonical | The platform is discovering the server's available capabilities. |
### Values of `kind` {#response-values-kind} Ownership and connection category of an MCP server available to the platform. INTERNAL servers use fully qualified server IDs; BUILT\_IN IDs start with `built-in:`, CUSTOM with `custom:`, and INTEGRATION with `pipedream:`. EXTERNAL identifies existing externally configured servers with unprefixed IDs. Use this category when displaying or filtering the server catalog.
| Value | No. | Form | Meaning | |---|---|---|---| | `MCP_SERVER_KIND_INTERNAL` | 0 | Canonical | See meaning below. | | `MCP_SERVER_KIND_BUILT_IN` | 1 | Canonical | See meaning below. | | `MCP_SERVER_KIND_CUSTOM` | 2 | Canonical | See meaning below. | | `MCP_SERVER_KIND_EXTERNAL` | 3 | Canonical | An existing externally configured server. New entries are not supported in this category; it does not designate a new tenant registration. | | `MCP_SERVER_KIND_INTEGRATION` | 4 | Canonical | See meaning below. | **`MCP_SERVER_KIND_INTERNAL`** A server compiled into the deployment and dispatched in-process. Compiled into the deployment and dispatched in-process. No vendor cost. **`MCP_SERVER_KIND_BUILT_IN`** A platform-owned catalog server invoked with platform-held vendor credentials. Platform-owned catalog entry, called with a platform-held vendor key and no end-user identity. Metered per call. **`MCP_SERVER_KIND_CUSTOM`** A tenant-registered server invoked with the tenant's credentials. Registered by a tenant, called with the tenant's own credential. **`MCP_SERVER_KIND_INTEGRATION`** An account-connected integration reached through Pipedream Connect. Account-bound integration reached through Pipedream Connect.
## Where used {#where-used} | Reference | Relationship | |---|---| | [Get detailed MCP server info](/api/conversations/mcp-get-server-info) | `POST /api/v1/llm/mcp-get-server-info` | Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # MessageFeedback {#overview} URL: https://docs.travila.ai/api/models/schema-1iroqctqt1 One user's feedback on an assistant-generated message. kind must select a listed feedback representation. Requiredness and allowed values are declared separately. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `kind` | `string` (`FEEDBACK_KIND_THUMB`, `FEEDBACK_KIND_SCALE`) or `integer (int32)` (`0`, `1`) | **Required in requests** | Rating representation used to interpret the feedback value. | | `thumbUp` | `boolean` | Optional | Positive when true and negative when false; used for THUMB feedback. | | `rating` | `string (int64)` | Optional | Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent. Pattern: `^-?\d+$`. | | `reason` | `string` | Optional | Optional explanation for the rating. Maximum length: 1000. | | `ratedAt` | `string (date-time)` | Optional | Timestamp when feedback was submitted (server-set) | | `ratedBy` | `string` | Optional | Identifier of the user who submitted this feedback. Set by the server from the authenticated user identity; never client-supplied. Each user has one feedback entry per message. | ### Values of `kind` {#request-values-kind} Value scale used to interpret recorded feedback.
| Value | No. | Form | Meaning | |---|---|---|---| | `FEEDBACK_KIND_THUMB` | 0 | Canonical | See meaning below. | | `FEEDBACK_KIND_SCALE` | 1 | Canonical | See meaning below. | **`FEEDBACK_KIND_THUMB`** Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. binary thumbs up / down **`FEEDBACK_KIND_SCALE`** Feedback expressed as an integer rating from 1 through 10. 1-10 integer scale
## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `kind` | Required value | `true` | | `kind` | Defined enum value | `true` | | `rating` | At most | `10` | | `rating` | At least | `0` | | `reason` | Maximum length | `1000` | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `kind` | `string` (`FEEDBACK_KIND_THUMB`, `FEEDBACK_KIND_SCALE`) or `integer (int32)` | **Required in requests** | Rating representation used to interpret the feedback value. | | `thumbUp` | `boolean` | Optional | Positive when true and negative when false; used for THUMB feedback. | | `rating` | `string (int64)` | Optional | Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent. Pattern: `^-?\d+$`. | | `reason` | `string` | Optional | Optional explanation for the rating. | | `ratedAt` | `string (date-time)` | Optional | Timestamp when feedback was submitted (server-set) | | `ratedBy` | `string` | Optional | Identifier of the user who submitted this feedback. Set by the server from the authenticated user identity; never client-supplied. Each user has one feedback entry per message. | ### Values of `kind` {#response-values-kind} Value scale used to interpret recorded feedback.
| Value | No. | Form | Meaning | |---|---|---|---| | `FEEDBACK_KIND_THUMB` | 0 | Canonical | See meaning below. | | `FEEDBACK_KIND_SCALE` | 1 | Canonical | See meaning below. | **`FEEDBACK_KIND_THUMB`** Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. binary thumbs up / down **`FEEDBACK_KIND_SCALE`** Feedback expressed as an integer rating from 1 through 10. 1-10 integer scale
## Request validation {#response-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `kind` | Required value | `true` | | `kind` | Defined enum value | `true` | | `rating` | At most | `10` | | `rating` | At least | `0` | | `reason` | Maximum length | `1000` | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [Message](/api/models/schema-1j3dcf7kvu#response) | Nested in model | | [Message](/api/models/schema-1j3dcf7kvu#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # ToolCall {#overview} URL: https://docs.travila.ai/api/models/schema-1it6mqsqoo A single structured tool call emitted by the model [`clientToolDeadlineAt`](/api/models/schema-1it6mqsqoo#response-field-clienttooldeadlineat) is the client answer window. Expiry ends that wait and rejects late results; the timeout policy determines the outcome. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | Optional | Provider-supplied call id. | | `name` | `string` | Optional | Name of the tool or function being invoked. | | `argumentsJson` | Map from string to JSON value | Optional | JSON object payload. | | `status` | `string` (`TOOL_EXECUTION_STATUS_PENDING`, `TOOL_EXECUTION_STATUS_EXECUTING`, `TOOL_EXECUTION_STATUS_COMPLETED`, `TOOL_EXECUTION_STATUS_FAILED`, `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, `TOOL_EXECUTION_STATUS_CANCELLED`, `TOOL_EXECUTION_STATUS_TIMED_OUT`) or `integer (int32)` | Optional; explicit presence | Execution status recorded for the tool call. | | `resultJson` | Map from string to JSON value | Optional | Tool execution result (object). | | `executedAt` | `string (date-time)` | Optional | Time when the tool execution was recorded. | | `serverId` | `string` | Optional | Which server provides this tool (for MCP tools). | | `isClientTool` | `boolean` | Optional | True if this is a client-side tool handled by client. | | `description` | `string` | Optional | Tool description captured from the resolved tool definition when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. | | `parametersJsonSchema` | Map from string to JSON value | Optional | JSON Schema describing the tool’s input arguments. | | `requiresApprovalAt` | `string (date-time)` | Optional | Deadline for an approval decision, calculated from the effective approval timeout. This is not the time the call began waiting. An approval received after the deadline is rejected. | | `approvedAt` | `string (date-time)` | Optional | Timestamp when approval decision was recorded (if approved/rejected) | | `approvedBy` | `string` | Optional | Identifier of the approver (user id, email, or actor key) | | `executionDuration` | `string` | Optional | End-to-end execution duration once terminal (includes tool server latency or client-side time) Pattern: `^-?(?:0\|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$`. | | `endReason` | `string` | Optional | See meaning below. | | `clientToolDeadlineAt` | `string (date-time)` | Optional | Deadline by which the client must submit a result for this call, stamped when the call is dispatched to a caller. | **`endReason`** Why this call ended, in one short phrase — "approval rejected", "approval timeout", or the underlying error. Set only once `status` is terminal, and empty on a clean COMPLETED. Use this reason to distinguish a rejection from a failure without parsing the tool result. ### Values of `status` {#request-values-status} Execution state of a tool call, including approval waiting and terminal outcomes. The terminal outcomes are COMPLETED, FAILED, CANCELLED and TIMED\_OUT; inspect ToolCall.end\_reason for why a call ended rather than treating the reason as another status. Use a listed execution status. The end reason explains the outcome separately from the status.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_EXECUTION_STATUS_PENDING` | 0 | Canonical | The tool call is waiting to begin execution. | | `TOOL_EXECUTION_STATUS_EXECUTING` | 1 | Canonical | The tool call is currently executing. | | `TOOL_EXECUTION_STATUS_COMPLETED` | 2 | Canonical | The tool call completed successfully. This is a terminal outcome. | | `TOOL_EXECUTION_STATUS_FAILED` | 3 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. | | `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 4 | Canonical | The tool call is waiting for approval before it can execute. | | `TOOL_EXECUTION_STATUS_CANCELLED` | 5 | Canonical | The tool call was cancelled before normal completion. | | `TOOL_EXECUTION_STATUS_TIMED_OUT` | 6 | Canonical | Tool execution ended because its time limit elapsed. |
## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | Optional | Provider-supplied call id. | | `name` | `string` | Optional | Name of the tool or function being invoked. | | `argumentsJson` | Map from string to JSON value | Optional | JSON object payload. | | `status` | `string` (`TOOL_EXECUTION_STATUS_PENDING`, `TOOL_EXECUTION_STATUS_EXECUTING`, `TOOL_EXECUTION_STATUS_COMPLETED`, `TOOL_EXECUTION_STATUS_FAILED`, `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, `TOOL_EXECUTION_STATUS_CANCELLED`, `TOOL_EXECUTION_STATUS_TIMED_OUT`) or `integer (int32)` | Optional; explicit presence | Execution status recorded for the tool call. | | `resultJson` | Map from string to JSON value | Optional | Tool execution result (object). | | `executedAt` | `string (date-time)` | Optional | Time when the tool execution was recorded. | | `serverId` | `string` | Optional | Which server provides this tool (for MCP tools). | | `isClientTool` | `boolean` | Optional | True if this is a client-side tool handled by client. | | `description` | `string` | Optional | Tool description captured from the resolved tool definition when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. | | `parametersJsonSchema` | Map from string to JSON value | Optional | JSON Schema describing the tool’s input arguments. | | `requiresApprovalAt` | `string (date-time)` | Optional | Deadline for an approval decision, calculated from the effective approval timeout. This is not the time the call began waiting. An approval received after the deadline is rejected. | | `approvedAt` | `string (date-time)` | Optional | Timestamp when approval decision was recorded (if approved/rejected) | | `approvedBy` | `string` | Optional | Identifier of the approver (user id, email, or actor key) | | `executionDuration` | `string` | Optional | End-to-end execution duration once terminal (includes tool server latency or client-side time) Pattern: `^-?(?:0\|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$`. | | `endReason` | `string` | Optional | See meaning below. | | `clientToolDeadlineAt` | `string (date-time)` | Optional | Deadline by which the client must submit a result for this call, stamped when the call is dispatched to a caller. | **`endReason`** Why this call ended, in one short phrase — "approval rejected", "approval timeout", or the underlying error. Set only once `status` is terminal, and empty on a clean COMPLETED. Use this reason to distinguish a rejection from a failure without parsing the tool result. ### Values of `status` {#response-values-status} Execution state of a tool call, including approval waiting and terminal outcomes. The terminal outcomes are COMPLETED, FAILED, CANCELLED and TIMED\_OUT; inspect ToolCall.end\_reason for why a call ended rather than treating the reason as another status. Use a listed execution status. The end reason explains the outcome separately from the status.
| Value | No. | Form | Meaning | |---|---|---|---| | `TOOL_EXECUTION_STATUS_PENDING` | 0 | Canonical | The tool call is waiting to begin execution. | | `TOOL_EXECUTION_STATUS_EXECUTING` | 1 | Canonical | The tool call is currently executing. | | `TOOL_EXECUTION_STATUS_COMPLETED` | 2 | Canonical | The tool call completed successfully. This is a terminal outcome. | | `TOOL_EXECUTION_STATUS_FAILED` | 3 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. | | `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 4 | Canonical | The tool call is waiting for approval before it can execute. | | `TOOL_EXECUTION_STATUS_CANCELLED` | 5 | Canonical | The tool call was cancelled before normal completion. | | `TOOL_EXECUTION_STATUS_TIMED_OUT` | 6 | Canonical | Tool execution ended because its time limit elapsed. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Get a single tool call by ID](/api/conversations/get-tool-call) | `POST /api/v1/llm/get-tool-call` | | [List pending tool approvals](/api/conversations/list-pending-approvals) | `POST /api/v1/llm/list-pending-approvals` | | [List client-side tool calls awaiting a result](/api/conversations/list-pending-client-tools) | `POST /api/v1/llm/list-pending-client-tools` | | [Execute an MCP tool](/api/conversations/mcp-call-tool) | `POST /api/v1/llm/mcp-call-tool` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [Message](/api/models/schema-1j3dcf7kvu#response) | Nested in model | | [Message](/api/models/schema-1j3dcf7kvu#request) | Nested in model | | [ToolCallCompletedEvent](/api/models/schema-po3pkfshjg#response) | Nested in model | | [ToolCallCompletedEvent](/api/models/schema-po3pkfshjg#request) | Nested in model | | [ToolCallStartedEvent](/api/models/schema-po5rioe4il#response) | Nested in model | | [ToolCallStartedEvent](/api/models/schema-po5rioe4il#request) | Nested in model | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e#response) | Nested in model | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # PromptTokensDetails {#overview} URL: https://docs.travila.ai/api/models/schema-1ivj82m55o Breakdown of prompt token usage by category (input-side cache accounting) Subset semantics: cached\_tokens and cache\_write\_tokens are a breakdown *of* prompt\_tokens, so cached\_tokens + cache\_write\_tokens \<= Usage.prompt\_tokens. Ordinary (full-rate) prompt tokens = prompt\_tokens - cached\_tokens - cache\_write\_tokens. audio\_tokens / video\_tokens are modality breakdowns of prompt\_tokens (also a subset). Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `cachedTokens` | `string (int64)` | Optional | Prompt tokens served from cache (cache READ). Pattern: `^-?\d+$`. | | `cacheWriteTokens` | `string (int64)` | Optional | Prompt tokens written to cache this call (cache WRITE). Pattern: `^-?\d+$`. | | `audioTokens` | `string (int64)` | Optional | Prompt tokens from audio input (multimodal). Pattern: `^-?\d+$`. | | `videoTokens` | `string (int64)` | Optional | Prompt tokens from video input (multimodal). Pattern: `^-?\d+$`. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `cachedTokens` | `string (int64)` | Optional | Prompt tokens served from cache (cache READ). Pattern: `^-?\d+$`. | | `cacheWriteTokens` | `string (int64)` | Optional | Prompt tokens written to cache this call (cache WRITE). Pattern: `^-?\d+$`. | | `audioTokens` | `string (int64)` | Optional | Prompt tokens from audio input (multimodal). Pattern: `^-?\d+$`. | | `videoTokens` | `string (int64)` | Optional | Prompt tokens from video input (multimodal). Pattern: `^-?\d+$`. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [Usage](/api/models/schema-1j1vov2uoh#response) | Nested in model | | [Usage](/api/models/schema-1j1vov2uoh#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # Usage {#overview} URL: https://docs.travila.ai/api/models/schema-1j1vov2uoh Usage accounting Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `promptTokens` | `string (int64)` | Optional | Prompt-token usage reported by the model provider. Pattern: `^-?\d+$`. | | `completionTokens` | `string (int64)` | Optional | Completion-token usage reported by the model provider. Pattern: `^-?\d+$`. | | `totalTokens` | `string (int64)` | Optional | Total token usage reported by the model provider. Pattern: `^-?\d+$`. | | `costEstimate` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Estimated cost in USD. | | `completionTokensDetails` | [CompletionTokensDetails](/api/models/schema-1i6q4qpg72#request) | Optional | Breakdown of completion tokens. | | `promptTokensDetails` | [PromptTokensDetails](/api/models/schema-1ivj82m55o#request) | Optional | Breakdown of prompt tokens (cache). | | `costDetails` | [CostDetails](/api/models/schema-1ia0h761lm#request) | Optional | Breakdown of upstream provider cost (BYOK routes). | | `isByok` | `boolean` | Optional | Whether this generation used the customer's own model-provider key. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `promptTokens` | `string (int64)` | Optional | Prompt-token usage reported by the model provider. Pattern: `^-?\d+$`. | | `completionTokens` | `string (int64)` | Optional | Completion-token usage reported by the model provider. Pattern: `^-?\d+$`. | | `totalTokens` | `string (int64)` | Optional | Total token usage reported by the model provider. Pattern: `^-?\d+$`. | | `costEstimate` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Estimated cost in USD. | | `completionTokensDetails` | [CompletionTokensDetails](/api/models/schema-1i6q4qpg72#response) | Optional | Breakdown of completion tokens. | | `promptTokensDetails` | [PromptTokensDetails](/api/models/schema-1ivj82m55o#response) | Optional | Breakdown of prompt tokens (cache). | | `costDetails` | [CostDetails](/api/models/schema-1ia0h761lm#response) | Optional | Breakdown of upstream provider cost (BYOK routes). | | `isByok` | `boolean` | Optional | Whether this generation used the customer's own model-provider key. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [LLMGenerationCompletedEvent](/api/models/schema-pntuu08p80#response) | Nested in model | | [LLMGenerationCompletedEvent](/api/models/schema-pntuu08p80#request) | Nested in model | | [Message](/api/models/schema-1j3dcf7kvu#response) | Nested in model | | [Message](/api/models/schema-1j3dcf7kvu#request) | Nested in model | | [UsageByModel](/api/models/schema-po7orad6ac#response) | Nested in model | | [UsageByModel](/api/models/schema-po7orad6ac#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # Message {#overview} URL: https://docs.travila.ai/api/models/schema-1j3dcf7kvu Chat message At least one of content or tool\_calls must contain an entry; both lists may be nonempty. role must select a listed message role. Requiredness and allowed values are declared separately. Type-reference view: `API Schema 9frhv4euve`, `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `role` | `string` (`ROLE_SYSTEM`, `ROLE_USER`, `ROLE_ASSISTANT`, `ROLE_TOOL`) or `integer (int32)` (`0`, `1`, `2`, `3`) | **Required in requests** | Role of the participant that produced the chat message. | | `content` | Array of [ContentPart](/api/models/schema-1hqi9r2bhh#request) | Optional | Content parts composing the chat message. | | `toolCalls` | Array of [ToolCall](/api/models/schema-1it6mqsqoo#request) | Optional | Assistant-to-tool invocations. | | `name` | `string` | Optional | See meaning below. | | `timestamp` | `string (date-time)` | Optional | Timestamp associated with the conversation message or event. | | `messageId` | `string` | Optional | Unique message identifier. | | `annotations` | Array of [Annotation](/api/models/schema-1i0hjer0pd#request) | Optional | Structured annotations (e.g., standardized web search URL citations, PDF reuse tokens) | | `sequence` | `string (int64)` | Optional | Monotonic, per-conversation sequence number for stable ordering (1-based) Pattern: `^-?\d+$`. | | `generatedBy` | `string` | Optional | Workflow run id or generator key that produced this message (e.g., workflow run key) | | `usage` | [Usage](/api/models/schema-1j1vov2uoh#request) | Optional | Token usage for this generation (populated for assistant messages) | | `model` | `string` | Optional | Model that generated this message (e.g., "anthropic/claude-sonnet-4") | | `generationContext` | [GenerationContext](/api/models/schema-1im79fphmq#request) | Optional | Dynamic context that shaped this generation (memories, search params, turn info) | | `clientContext` | [ClientContext](/api/models/schema-1i2sndrl93#request) | Optional | Arbitrary client-supplied context attached by the client for this message | | `feedback` | Array of [MessageFeedback](/api/models/schema-1iroqctqt1#request) | Optional | Feedback on an assistant message, with one entry per rater identified by rated\_by. A later rating by the same rater replaces their earlier entry. | | `sourceUserMessageId` | `string` | Optional | See meaning below. | | `finishReason` | `string` | Optional | Why the model stopped, verbatim from the provider: "stop", "tool\_calls", "length", "error". Empty for historical messages. | **`name`** Name identifying the sender of the chat message. optional sender name **`sourceUserMessageId`** Identifier of the user message that opened this conversation turn. Generated messages in the same turn share this value; a user message carries its own message\_id. Empty on historical messages that predate turn attribution. Use this field for turn attribution rather than inferring it from message adjacency or a client-supplied message\_id. The generated\_by identifier groups messages by generation run but does not identify the user message that opened the turn. ### Values of `role` {#request-values-role} Participant role attached to a conversation message and forwarded in model context.
| Value | No. | Form | Meaning | |---|---|---|---| | `ROLE_SYSTEM` | 0 | Canonical | Instructions or context provided as a system message. | | `ROLE_USER` | 1 | Canonical | Input supplied by the user or customer application. | | `ROLE_ASSISTANT` | 2 | Canonical | Content produced by the assistant, including its tool-call requests. | | `ROLE_TOOL` | 3 | Canonical | A tool result supplied back to the assistant. |
## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | Message | `native.group.message_content` | content or tool_calls required | | `role` | Required value | `true` | | `role` | Defined enum value | `true` | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `role` | `string` (`ROLE_SYSTEM`, `ROLE_USER`, `ROLE_ASSISTANT`, `ROLE_TOOL`) or `integer (int32)` | **Required in requests** | Role of the participant that produced the chat message. | | `content` | Array of [ContentPart](/api/models/schema-1hqi9r2bhh#response) | Optional | Content parts composing the chat message. | | `toolCalls` | Array of [ToolCall](/api/models/schema-1it6mqsqoo#response) | Optional | Assistant-to-tool invocations. | | `name` | `string` | Optional | See meaning below. | | `timestamp` | `string (date-time)` | Optional | Timestamp associated with the conversation message or event. | | `messageId` | `string` | Optional | Unique message identifier. | | `annotations` | Array of [Annotation](/api/models/schema-1i0hjer0pd#response) | Optional | Structured annotations (e.g., standardized web search URL citations, PDF reuse tokens) | | `sequence` | `string (int64)` | Optional | Monotonic, per-conversation sequence number for stable ordering (1-based) Pattern: `^-?\d+$`. | | `generatedBy` | `string` | Optional | Workflow run id or generator key that produced this message (e.g., workflow run key) | | `usage` | [Usage](/api/models/schema-1j1vov2uoh#response) | Optional | Token usage for this generation (populated for assistant messages) | | `model` | `string` | Optional | Model that generated this message (e.g., "anthropic/claude-sonnet-4") | | `generationContext` | [GenerationContext](/api/models/schema-1im79fphmq#response) | Optional | Dynamic context that shaped this generation (memories, search params, turn info) | | `clientContext` | [ClientContext](/api/models/schema-1i2sndrl93#response) | Optional | Arbitrary client-supplied context attached by the client for this message | | `feedback` | Array of [MessageFeedback](/api/models/schema-1iroqctqt1#response) | Optional | Feedback on an assistant message, with one entry per rater identified by rated\_by. A later rating by the same rater replaces their earlier entry. | | `sourceUserMessageId` | `string` | Optional | See meaning below. | | `finishReason` | `string` | Optional | Why the model stopped, verbatim from the provider: "stop", "tool\_calls", "length", "error". Empty for historical messages. | **`name`** Name identifying the sender of the chat message. optional sender name **`sourceUserMessageId`** Identifier of the user message that opened this conversation turn. Generated messages in the same turn share this value; a user message carries its own message\_id. Empty on historical messages that predate turn attribution. Use this field for turn attribution rather than inferring it from message adjacency or a client-supplied message\_id. The generated\_by identifier groups messages by generation run but does not identify the user message that opened the turn. ### Values of `role` {#response-values-role} Participant role attached to a conversation message and forwarded in model context.
| Value | No. | Form | Meaning | |---|---|---|---| | `ROLE_SYSTEM` | 0 | Canonical | Instructions or context provided as a system message. | | `ROLE_USER` | 1 | Canonical | Input supplied by the user or customer application. | | `ROLE_ASSISTANT` | 2 | Canonical | Content produced by the assistant, including its tool-call requests. | | `ROLE_TOOL` | 3 | Canonical | A tool result supplied back to the assistant. |
## Request validation {#response-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | Message | `native.group.message_content` | content or tool_calls required | | `role` | Required value | `true` | | `role` | Defined enum value | `true` | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Withdraw your rating on a message](/api/conversations/delete-message-rating) | `POST /api/v1/llm/delete-message-rating` | | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Rate an assistant message](/api/conversations/rate-message) | `POST /api/v1/llm/rate-message` | | [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` | | [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync) | `POST /api/v1/llm/submit-client-tool-results-sync` | | [Append a message without generating](/api/conversations/append-message) | `POST /api/v1/llm/append-message` | | [Send a message to a conversation](/api/conversations/send-message) | `POST /api/v1/llm/send-message` | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94) | API JSON uses JSON field names (camelCase). | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [ReceiveMessageRequest](/api/models/schema-q69v86pv94#response) | Nested in model | | [ReceiveMessageRequest](/api/models/schema-q69v86pv94#request) | Nested in model | | [LLMMessagePublishedEvent](/api/models/schema-po1qsocerv#response) | Nested in model | | [LLMMessagePublishedEvent](/api/models/schema-po1qsocerv#request) | Nested in model | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e#response) | Nested in model | | [ClientToolDispatch](/api/models/schema-qj0o2cvv4e#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # PromptFragment {#overview} URL: https://docs.travila.ai/api/models/schema-1j5dvgfmr9 Project-scoped reusable prompt-template text. Profiles and other fragments include it with `{{template "fragment_id" .}}`; variables come from the conversation’s prompt\_variables. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `fragmentId` | `string` | Optional | Stable template name, unique within the project library and used by include actions. | | `name` | `string` | Optional | Display name used as a console hint for the reusable prompt fragment. | | `content` | `string` | Optional | Raw template text, supporting `{{.variable}}` placeholders and nested `{{template "id" .}}` includes. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `fragmentId` | `string` | Optional | Stable template name, unique within the project library and used by include actions. | | `name` | `string` | Optional | Display name used as a console hint for the reusable prompt fragment. | | `content` | `string` | Optional | Raw template text, supporting `{{.variable}}` placeholders and nested `{{template "id" .}}` includes. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a prompt fragment](/api/agent-profiles/create-prompt-fragment) | `POST /api/v1/prompt-fragments/create` | | [Get a prompt fragment](/api/agent-profiles/get-prompt-fragment) | `POST /api/v1/prompt-fragments/get` | | [Get a fragment set by version](/api/agent-profiles/get-prompt-fragment-set) | `POST /api/v1/prompt-fragments/get-set` | | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | | [List prompt fragments](/api/agent-profiles/list-prompt-fragments) | `POST /api/v1/prompt-fragments/list` | | [Update a prompt fragment](/api/agent-profiles/update-prompt-fragment) | `POST /api/v1/prompt-fragments/update` | Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) --- # ToolApproval {#overview} URL: https://docs.travila.ai/api/models/schema-1j7jbpfsda Approval decision for a specific tool call ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `toolCallId` | `string` | Optional | Identifier of the tool call whose execution is being approved or rejected. | | `toolName` | `string` | Optional | Name of the tool associated with the call or result. | | `approved` | `boolean` | Optional | Whether the caller approves execution of the identified tool call. | | `reason` | `string` | Optional | Optional rejection reason. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Approve or reject pending tool calls](/api/conversations/submit-tool-approvals) | `POST /api/v1/llm/submit-tool-approvals` | Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # AnnotationQueue {#overview} URL: https://docs.travila.ai/api/models/schema-1j9496mkdg Named work queue assigning score configurations to human annotation items. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `queueId` | `string` | Optional | Identifier of the annotation queue. | | `name` | `string` | Optional | Display name of the annotation work queue. | | `description` | `string` | Optional | Human-readable description of the resource. | | `scoreConfigIds` | Array of `string` | Optional | Score configurations available when annotating items in this queue. At least one configuration is required. | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | | `updatedAt` | `string (date-time)` | Optional | Time when this record was last updated. | | `pendingCount` | `string (int64)` | Optional | Number of queue items awaiting annotation. Pattern: `^-?\d+$`. | | `completedCount` | `string (int64)` | Optional | Number of queue items reported completed. Pattern: `^-?\d+$`. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [List annotation queues](/api/evals/list-annotation-queues) | `POST /api/v1/evals/list-annotation-queues` | Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # Dataset {#overview} URL: https://docs.travila.ai/api/models/schema-1ja63aqvqo Evaluation dataset metadata, item counts, run history, and input/output schemas. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `datasetId` | `string` | Optional | Identifier of the evaluation dataset. | | `name` | `string` | Optional | Name identifying the evaluation dataset. | | `description` | `string` | Optional | Human-readable description of the resource. | | `metadataJson` | `string` | Optional | Additional attributes serialized as a JSON object. | | `itemCount` | `string (int64)` | Optional | Number of dataset items reported for the dataset. Pattern: `^-?\d+$`. | | `runCount` | `string (int64)` | Optional | Number of runs reported for the evaluation dataset. Pattern: `^-?\d+$`. | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | | `lastRunAt` | `string (date-time)` | Optional | Time when the dataset was most recently evaluated. | | `inputSchemaJson` | `string` | Optional | JSON Schema describing dataset input values. | | `expectedOutputSchemaJson` | `string` | Optional | JSON Schema describing expected dataset output values. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [List datasets](/api/evals/list-datasets) | `POST /api/v1/evals/list-datasets` | Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # DatasetItem {#overview} URL: https://docs.travila.ai/api/models/schema-1jcdgbb5sm One evaluation input with its expected output and source trace references. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `itemId` | `string` | Optional | Identifier of the evaluation dataset item. | | `datasetId` | `string` | Optional | Identifier of the evaluation dataset. | | `datasetName` | `string` | Optional | Name of the evaluation dataset. | | `inputJson` | `string` | Optional | Evaluation input serialized as JSON. | | `expectedOutputJson` | `string` | Optional | Expected output serialized as JSON. Empty until a curator supplies an expected result. | | `metadataJson` | `string` | Optional | Additional attributes serialized as a JSON object. | | `sourceTraceId` | `string` | Optional | Identifier of the trace from which the dataset item originated. | | `sourceObservationId` | `string` | Optional | Identifier of the observation from which the dataset item originated. | | `status` | `string` (`DATASET_ITEM_STATUS_ACTIVE`, `DATASET_ITEM_STATUS_ARCHIVED`) or `integer (int32)` | Optional; explicit presence | State controlling whether the dataset item participates in evaluation. | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | | `updatedAt` | `string (date-time)` | Optional | Time when this record was last updated. | ### Values of `status` {#response-values-status} Whether a dataset item is active or retained as archived content.
| Value | No. | Form | Meaning | |---|---|---|---| | `DATASET_ITEM_STATUS_ACTIVE` | 0 | Canonical | The dataset item is active. | | `DATASET_ITEM_STATUS_ARCHIVED` | 1 | Canonical | The dataset item is archived and retained as historical content. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [List dataset items](/api/evals/list-dataset-items) | `POST /api/v1/evals/list-dataset-items` | Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # DatasetRun {#overview} URL: https://docs.travila.ai/api/models/schema-1jehhpchdc Metadata describing one execution of an evaluation dataset. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `runId` | `string` | Optional | Identifier of the evaluation dataset run. | | `datasetId` | `string` | Optional | Identifier of the evaluation dataset. | | `name` | `string` | Optional | Name assigned to this execution of the evaluation dataset. | | `description` | `string` | Optional | Human-readable description of the resource. | | `metadataJson` | `string` | Optional | Additional attributes serialized as a JSON object. | | `itemCount` | `string (int64)` | Optional | Number of dataset items reported for this run. Pattern: `^-?\d+$`. | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get a dataset run](/api/evals/get-dataset-run) | `POST /api/v1/evals/get-dataset-run` | | [List dataset runs](/api/evals/list-dataset-runs) | `POST /api/v1/evals/list-dataset-runs` | Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # LatencyPercentileRow {#overview} URL: https://docs.travila.ai/api/models/schema-1jgrpr157a Latency percentiles, in seconds, aggregated for one evaluation trace name. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `traceName` | `string` | Optional | Display name used to group or identify the evaluation trace. | | `p50` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | 50th-percentile latency for the trace group, in seconds. | | `p90` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | 90th-percentile latency for the trace group, in seconds. | | `p95` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | 95th-percentile latency for the trace group, in seconds. | | `p99` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | 99th-percentile latency for the trace group, in seconds. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get the eval overview](/api/evals/get-overview) | `POST /api/v1/evals/get-overview` |
Models containing this value | Model | Relationship | |---|---| | [EvalOverview](/api/models/schema-1js2bf073d#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # NamedCount {#overview} URL: https://docs.travila.ai/api/models/schema-1jiel5uim6 Count of evaluation records grouped under a shared label. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `name` | `string` | Optional | Grouping label associated with this record count. | | `count` | `string (int64)` | Optional | Number of evaluation records represented by this group. Pattern: `^-?\d+$`. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get the eval overview](/api/evals/get-overview) | `POST /api/v1/evals/get-overview` |
Models containing this value | Model | Relationship | |---|---| | [EvalOverview](/api/models/schema-1js2bf073d#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # ProfileQualityRow {#overview} URL: https://docs.travila.ai/api/models/schema-1jku9efe5c Aggregated evaluation results and usage for one agent profile. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `profileId` | `string` | Optional | Identifier of the agent profile associated with the generation. | | `traceCount` | `string (int64)` | Optional | Number of traces represented by this summary or group. Pattern: `^-?\d+$`. | | `avgEndUserRating` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Average end-user rating reported for the selected generation group. | | `avgJudgeScore` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Average automated judge score reported for the selected generation group. | | `thumbsDownCount` | `string (int64)` | Optional | Number of negative thumb ratings reported for the selected group. Pattern: `^-?\d+$`. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get the eval overview](/api/evals/get-overview) | `POST /api/v1/evals/get-overview` |
Models containing this value | Model | Relationship | |---|---| | [EvalOverview](/api/models/schema-1js2bf073d#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # Score {#overview} URL: https://docs.travila.ai/api/models/schema-1jm5lo00e7 Evaluation score with its value, source, target identity, and generation attribution. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `scoreId` | `string` | Optional | Identifier of the evaluation score. | | `targetType` | `string` (`EVAL_TARGET_TYPE_TRACE`, `EVAL_TARGET_TYPE_OBSERVATION`, `EVAL_TARGET_TYPE_DATASET_RUN`, `EVAL_TARGET_TYPE_SESSION`) or `integer (int32)` | Optional; explicit presence | Kind of evaluation object to which the score applies. | | `targetId` | `string` | Optional | Identifier of the evaluation object to which the score applies. | | `name` | `string` | Optional | Metric name identifying the recorded evaluation score. | | `dataType` | `string` (`SCORE_DATA_TYPE_NUMERIC`, `SCORE_DATA_TYPE_CATEGORICAL`, `SCORE_DATA_TYPE_BOOLEAN`, `SCORE_DATA_TYPE_TEXT`) or `integer (int32)` | Optional; explicit presence | Value type used to interpret numeric, categorical, Boolean, or text score values. | | `numericValue` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Numeric score value reported by the evaluator. | | `stringValue` | `string` | Optional | Category label recorded for a categorical evaluation score. | | `booleanValue` | `boolean` | Optional | Boolean value recorded for a Boolean evaluation score. | | `source` | `string` (`SCORE_SOURCE_JUDGE`, `SCORE_SOURCE_HUMAN`, `SCORE_SOURCE_USER`, `SCORE_SOURCE_HARNESS`, `SCORE_SOURCE_EVAL`) or `integer (int32)` | Optional; explicit presence | Source classification reported for the evaluation score. | | `comment` | `string` | Optional | Explanatory text attached to the evaluation score. | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | | `textValue` | `string` | Optional | Text value of the evaluation score. | | `authorUserId` | `string` | Optional | Identifier recorded for the user who authored the score. A stored author identifier alone does not attest to verified human provenance. | | `configId` | `string` | Optional | Identifier of the score configuration defining the score’s value domain. | | `queueId` | `string` | Optional | Identifier of the annotation queue. | | `traceId` | `string` | Optional | Identifier of the evaluation trace. | | `observationId` | `string` | Optional | Identifier of the evaluation observation. | | `sessionId` | `string` | Optional | Identifier of the evaluation session grouping related traces. | | `datasetRunId` | `string` | Optional | Identifier of the dataset run associated with the score. | | `environment` | `string` | Optional | Environment label attached to the evaluation record. | | `metadataJson` | `string` | Optional | Additional attributes serialized as a JSON object. | | `updatedAt` | `string (date-time)` | Optional | Time when this record was last updated. | | `timestamp` | `string (date-time)` | Optional | Timestamp associated with the evaluation score. | | `traceName` | `string` | Optional | Trace name included with the score for display in score listings. | | `userId` | `string` | Optional | User identifier recorded with the evaluation score. | | `sourceLabel` | `string` | Optional | Original evaluation-provider source label, such as API, ANNOTATION or EVAL. Interpret it alongside source and authorship: API alone does not distinguish an end-user rating from a harness, and a source label does not independently prove verified human provenance. | | `conversationId` | `string` | Optional | Conversation identifier recorded in the score’s own metadata. Scores authored directly in the evaluation store can lack platform attribution; an empty link is not repaired by retrying. | | `messageId` | `string` | Optional | Identifier of the conversation message associated with the evaluation record. | | `messageSequence` | `string (int64)` | Optional | Sequence number of the evaluated message within its conversation. Pattern: `^-?\d+$`. | | `profileId` | `string` | Optional | Identifier of the agent profile associated with the generation. | | `configHash` | `string` | Optional | Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation results. Other settings are excluded; this is not an immutable profile revision. | ### Values of `targetType` {#response-values-targettype} Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_TARGET_TYPE_TRACE` | 0 | Canonical | A complete trace identified by its trace identifier. | | `EVAL_TARGET_TYPE_OBSERVATION` | 1 | Canonical | A specific observation within a trace. | | `EVAL_TARGET_TYPE_DATASET_RUN` | 2 | Canonical | An evaluation run over a dataset. | | `EVAL_TARGET_TYPE_SESSION` | 3 | Canonical | A session grouping multiple traces. The evaluation harness attaches session-scoped judge scores directly; the provider does not expose a session-level evaluator target. |
### Values of `dataType` {#response-values-datatype} Scores Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_DATA_TYPE_NUMERIC` | 0 | Canonical | A numeric measurement or rating. | | `SCORE_DATA_TYPE_CATEGORICAL` | 1 | Canonical | A value chosen from a named set of categories. | | `SCORE_DATA_TYPE_BOOLEAN` | 2 | Canonical | A true-or-false evaluation result. | | `SCORE_DATA_TYPE_TEXT` | 3 | Canonical | Free-form text supplied by an evaluator or reviewer. The provider supports text values on score definitions and scores; support through this API depends on the operation. |
### Values of `source` {#response-values-source} Platform classification of who produced an evaluation score. The provider source label retains its original vocabulary: writes accept API or ANNOTATION, while EVAL is reserved for the provider's internal evaluators and is rejected through its public API. SCORE\_SOURCE\_HUMAN maps to ANNOTATION. SCORE\_SOURCE\_USER, SCORE\_SOURCE\_JUDGE and SCORE\_SOURCE\_HARNESS map to API. Reviewer and end-user scores also use separate name namespaces: reviewer scores do not use names beginning with user-feedback-.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_SOURCE_JUDGE` | 0 | Canonical | A score produced by an automated judge. | | `SCORE_SOURCE_HUMAN` | 1 | Canonical | A score entered by a human reviewer through the annotation path. | | `SCORE_SOURCE_USER` | 2 | Canonical | Feedback supplied by an end user. | | `SCORE_SOURCE_HARNESS` | 3 | Canonical | A score written by an evaluation harness or another API-based producer. | | `SCORE_SOURCE_EVAL` | 4 | Canonical | A read-only score produced by the evaluation provider's managed evaluators; it cannot be written through the public score API. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [Get the eval overview](/api/evals/get-overview) | `POST /api/v1/evals/get-overview` | | [Get a session](/api/evals/get-session) | `POST /api/v1/evals/get-session` | | [Get a trace](/api/evals/get-trace) | `POST /api/v1/evals/get-trace` | | [List observations](/api/evals/list-observations) | `POST /api/v1/evals/list-observations` | | [List scores](/api/evals/list-scores) | `POST /api/v1/evals/list-scores` | | [List sessions](/api/evals/list-sessions) | `POST /api/v1/evals/list-sessions` | | [List traces](/api/evals/list-traces) | `POST /api/v1/evals/list-traces` |
Models containing this value | Model | Relationship | |---|---| | [EvalOverview](/api/models/schema-1js2bf073d#response) | Nested in model | | [Observation](/api/models/schema-1ju9tclufp#response) | Nested in model | | [SessionSummary](/api/models/schema-pbibjr8tih#response) | Nested in model | | [TraceDetail](/api/models/schema-pha7gtif3l#response) | Nested in model | | [TraceSummary](/api/models/schema-1k4mjul65u#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # ScoreAggregate {#overview} URL: https://docs.travila.ai/api/models/schema-1jo37n9pqa Count and average for scores grouped by name and source. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `name` | `string` | Optional | Metric name shared by the aggregated scores. | | `source` | `string` (`SCORE_SOURCE_JUDGE`, `SCORE_SOURCE_HUMAN`, `SCORE_SOURCE_USER`, `SCORE_SOURCE_HARNESS`, `SCORE_SOURCE_EVAL`) or `integer (int32)` | Optional; explicit presence | Source classification reported for the evaluation score. | | `count` | `string (int64)` | Optional | Number of evaluation records represented by this group. Pattern: `^-?\d+$`. | | `average` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Average score value reported for the aggregate. | ### Values of `source` {#response-values-source} Platform classification of who produced an evaluation score. The provider source label retains its original vocabulary: writes accept API or ANNOTATION, while EVAL is reserved for the provider's internal evaluators and is rejected through its public API. SCORE\_SOURCE\_HUMAN maps to ANNOTATION. SCORE\_SOURCE\_USER, SCORE\_SOURCE\_JUDGE and SCORE\_SOURCE\_HARNESS map to API. Reviewer and end-user scores also use separate name namespaces: reviewer scores do not use names beginning with user-feedback-.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_SOURCE_JUDGE` | 0 | Canonical | A score produced by an automated judge. | | `SCORE_SOURCE_HUMAN` | 1 | Canonical | A score entered by a human reviewer through the annotation path. | | `SCORE_SOURCE_USER` | 2 | Canonical | Feedback supplied by an end user. | | `SCORE_SOURCE_HARNESS` | 3 | Canonical | A score written by an evaluation harness or another API-based producer. | | `SCORE_SOURCE_EVAL` | 4 | Canonical | A read-only score produced by the evaluation provider's managed evaluators; it cannot be written through the public score API. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [Get the eval overview](/api/evals/get-overview) | `POST /api/v1/evals/get-overview` |
Models containing this value | Model | Relationship | |---|---| | [EvalOverview](/api/models/schema-1js2bf073d#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # TimeSeriesPoint {#overview} URL: https://docs.travila.ai/api/models/schema-1jq6h5scn9 Numeric evaluation measurement associated with a time bucket and series. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `bucket` | `string (date-time)` | Optional | Time bucket identifying this point in the evaluation series. | | `value` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Numeric measurement recorded for this time bucket and series. | | `series` | `string` | Optional | Series key when the query is split — a score name, level, or profile id. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get the eval overview](/api/evals/get-overview) | `POST /api/v1/evals/get-overview` |
Models containing this value | Model | Relationship | |---|---| | [EvalOverview](/api/models/schema-1js2bf073d#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # EvalOverview {#overview} URL: https://docs.travila.ai/api/models/schema-1js2bf073d Aggregated trace, score, latency, and profile metrics for an evaluation window. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `totalTraces` | `string (int64)` | Optional | Total trace count reported for the selected evaluation window. Pattern: `^-?\d+$`. | | `tracesByName` | Array of [NamedCount](/api/models/schema-1jiel5uim6#response) | Optional | Trace counts grouped by trace name. | | `tracesOverTime` | Array of [TimeSeriesPoint](/api/models/schema-1jq6h5scn9#response) | Optional | Trace counts grouped into time buckets. | | `observationsByLevel` | Array of [TimeSeriesPoint](/api/models/schema-1jq6h5scn9#response) | Optional | Observation counts grouped by reported log level. | | `scores` | Array of [ScoreAggregate](/api/models/schema-1jo37n9pqa#response) | Optional | Score aggregates grouped separately by metric name and source. | | `scoreMovingAverage` | Array of [TimeSeriesPoint](/api/models/schema-1jq6h5scn9#response) | Optional | Moving-average score series returned for the selected window. | | `scoredTraceRatio` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Coverage card: share of traces carrying any score, and the annotated count. | | `annotatedTraceCount` | `string (int64)` | Optional | Number of traces reported to have annotations in the selected window. Pattern: `^-?\d+$`. | | `byProfile` | Array of [ProfileQualityRow](/api/models/schema-1jku9efe5c#response) | Optional | Evaluation metrics grouped by agent profile. | | `latencyPercentiles` | Array of [LatencyPercentileRow](/api/models/schema-1jgrpr157a#response) | Optional | Latency percentile summaries grouped by trace name. | | `recentLowScores` | Array of [Score](/api/models/schema-1jm5lo00e7#response) | Optional | Recent scores selected by the overview’s low-score query. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get the eval overview](/api/evals/get-overview) | `POST /api/v1/evals/get-overview` | Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # Observation {#overview} URL: https://docs.travila.ai/api/models/schema-1ju9tclufp Timed evaluation span or generation record with model usage, inputs, outputs, and scores. A generation observation originates the profile and configuration attribution promoted to its trace; callers can read those links directly on either record. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `observationId` | `string` | Optional | Identifier of the evaluation observation. | | `traceId` | `string` | Optional | Identifier of the evaluation trace. | | `parentObservationId` | `string` | Optional | Identifier of the parent observation within the trace. | | `type` | `string` (`OBSERVATION_TYPE_SPAN`, `OBSERVATION_TYPE_GENERATION`, `OBSERVATION_TYPE_EVENT`, `OBSERVATION_TYPE_TOOL`, `OBSERVATION_TYPE_RETRIEVER`, `OBSERVATION_TYPE_AGENT`, `OBSERVATION_TYPE_CHAIN`, `OBSERVATION_TYPE_EMBEDDING`, `OBSERVATION_TYPE_EVALUATOR`, `OBSERVATION_TYPE_GUARDRAIL`) or `integer (int32)` | Optional; explicit presence | Observation kind reported by the evaluation provider. | | `name` | `string` | Optional | Operation name recorded for the evaluation observation. | | `level` | `string` (`OBSERVATION_LEVEL_DEBUG`, `OBSERVATION_LEVEL_DEFAULT`, `OBSERVATION_LEVEL_WARNING`, `OBSERVATION_LEVEL_ERROR`) or `integer (int32)` | Optional; explicit presence | Observation log level reported by the evaluation provider. | | `statusMessage` | `string` | Optional | Diagnostic text explaining the reported state. | | `startTime` | `string (date-time)` | Optional | Beginning of the time interval represented by this operation. | | `endTime` | `string (date-time)` | Optional | End of the time interval represented by this operation. | | `completionStartTime` | `string (date-time)` | Optional | Time to first token, generations only. | | `latencySeconds` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Elapsed observation latency, in seconds. | | `inputJson` | `string` | Optional | Evaluation input serialized as JSON. | | `outputJson` | `string` | Optional | Evaluation output serialized as JSON. | | `metadataJson` | `string` | Optional | Additional attributes serialized as a JSON object. | | `model` | `string` | Optional | Model identifier recorded for the evaluated generation. | | `modelParametersJson` | `string` | Optional | Model parameters recorded as a serialized JSON object. | | `inputTokens` | `string (int64)` | Optional | Input-token usage reported for the evaluated generation. Pattern: `^-?\d+$`. | | `outputTokens` | `string (int64)` | Optional | Output-token usage reported for the evaluated generation. Pattern: `^-?\d+$`. | | `totalTokens` | `string (int64)` | Optional | Total token usage reported for the evaluated generation or aggregate. Pattern: `^-?\d+$`. | | `inputCost` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Cost attributed to model input by the evaluation provider. | | `outputCost` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Cost attributed to model output by the evaluation provider. | | `totalCost` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Total cost reported for the evaluated generation or aggregate. | | `environment` | `string` | Optional | Environment label attached to the evaluation record. | | `version` | `string` | Optional | Version of the resource represented by this message. | | `promptName` | `string` | Optional | Name of the versioned prompt associated with the generation. | | `promptVersion` | `string (int64)` | Optional | Version of the prompt associated with the generation. Pattern: `^-?\d+$`. | | `scores` | Array of [Score](/api/models/schema-1jm5lo00e7#response) | Optional | Evaluation scores returned for the selected objects or query. | | `commentCount` | `string (int64)` | Optional | Number of comments reported on the evaluation object. Pattern: `^-?\d+$`. | | `conversationId` | `string` | Optional | Identifier of the conversation associated with this evaluation observation, when recorded. | | `sourceUserMessageId` | `string` | Optional | Identifier of the user message that opened the evaluated generation turn. | | `profileId` | `string` | Optional | Identifier of the agent profile associated with the generation. | | `configHash` | `string` | Optional | Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation results. Other settings are excluded; this is not an immutable profile revision. | ### Values of `type` {#response-values-type} Semantic category of a trace observation, including categories accepted from upstream even when the platform does not emit them. Current emitters produce GENERATION, TOOL, RETRIEVER and SPAN; the other declared categories can still describe upstream observations.
| Value | No. | Form | Meaning | |---|---|---|---| | `OBSERVATION_TYPE_SPAN` | 0 | Canonical | A timed unit of work represented as a span. | | `OBSERVATION_TYPE_GENERATION` | 1 | Canonical | A model-generation operation and its recorded inputs, outputs and usage. | | `OBSERVATION_TYPE_EVENT` | 2 | Canonical | A point-in-time event rather than a timed operation. | | `OBSERVATION_TYPE_TOOL` | 3 | Canonical | Execution of a tool call. | | `OBSERVATION_TYPE_RETRIEVER` | 4 | Canonical | Retrieval of supporting documents or other context. | | `OBSERVATION_TYPE_AGENT` | 5 | Canonical | An agent-level operation reported in the trace. | | `OBSERVATION_TYPE_CHAIN` | 6 | Canonical | A sequence or chain of related processing steps. | | `OBSERVATION_TYPE_EMBEDDING` | 7 | Canonical | Computation of vector embeddings. | | `OBSERVATION_TYPE_EVALUATOR` | 8 | Canonical | An evaluator operation that assesses another result. | | `OBSERVATION_TYPE_GUARDRAIL` | 9 | Canonical | A guardrail check on inputs, outputs or processing. |
### Values of `level` {#response-values-level} Diagnostic severity attached to an evaluation observation.
| Value | No. | Form | Meaning | |---|---|---|---| | `OBSERVATION_LEVEL_DEBUG` | 0 | Canonical | Detailed diagnostic information intended for debugging. | | `OBSERVATION_LEVEL_DEFAULT` | 1 | Canonical | Ordinary observation information without an elevated warning or error level. | | `OBSERVATION_LEVEL_WARNING` | 2 | Canonical | A condition reported at warning severity. | | `OBSERVATION_LEVEL_ERROR` | 3 | Canonical | A condition reported at error severity. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [Get a trace](/api/evals/get-trace) | `POST /api/v1/evals/get-trace` | | [List observations](/api/evals/list-observations) | `POST /api/v1/evals/list-observations` |
Models containing this value | Model | Relationship | |---|---| | [TraceDetail](/api/models/schema-pha7gtif3l#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # ScoreConfigCategory {#overview} URL: https://docs.travila.ai/api/models/schema-1k0g6fhhqd Named category and associated numeric value in a categorical score definition. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `label` | `string` | Optional | Label identifying this score category. | | `value` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Numeric score value associated with this named category. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [List score configs](/api/evals/list-score-configs) | `POST /api/v1/evals/list-score-configs` | | [Update a score config](/api/evals/update-score-config) | `POST /api/v1/evals/update-score-config` |
Models containing this value | Model | Relationship | |---|---| | [ScoreConfig](/api/models/schema-1k2h0fdd77#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # ScoreConfig {#overview} URL: https://docs.travila.ai/api/models/schema-1k2h0fdd77 Score definition specifying its value type, bounds, and allowed categories. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `configId` | `string` | Optional | Identifier of the score configuration defining the score’s value domain. | | `name` | `string` | Optional | Name identifying the score definition. | | `dataType` | `string` (`SCORE_DATA_TYPE_NUMERIC`, `SCORE_DATA_TYPE_CATEGORICAL`, `SCORE_DATA_TYPE_BOOLEAN`, `SCORE_DATA_TYPE_TEXT`) or `integer (int32)` | Optional; explicit presence | Value type used to interpret numeric, categorical, Boolean, or text score values. | | `description` | `string` | Optional | Human-readable description of the resource. | | `minValue` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Minimum numeric score value allowed by the score configuration. | | `maxValue` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Maximum numeric score value allowed by the score configuration. | | `categories` | Array of [ScoreConfigCategory](/api/models/schema-1k0g6fhhqd#response) | Optional | Named score categories defined by the score configuration. | | `isArchived` | `boolean` | Optional | Whether the score configuration is archived. Archived configurations are retained so historical scores remain interpretable. | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | | `updatedAt` | `string (date-time)` | Optional | Time when this record was last updated. | ### Values of `dataType` {#response-values-datatype} Scores Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCORE_DATA_TYPE_NUMERIC` | 0 | Canonical | A numeric measurement or rating. | | `SCORE_DATA_TYPE_CATEGORICAL` | 1 | Canonical | A value chosen from a named set of categories. | | `SCORE_DATA_TYPE_BOOLEAN` | 2 | Canonical | A true-or-false evaluation result. | | `SCORE_DATA_TYPE_TEXT` | 3 | Canonical | Free-form text supplied by an evaluator or reviewer. The provider supports text values on score definitions and scores; support through this API depends on the operation. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [List score configs](/api/evals/list-score-configs) | `POST /api/v1/evals/list-score-configs` | | [Update a score config](/api/evals/update-score-config) | `POST /api/v1/evals/update-score-config` | Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # TraceSummary {#overview} URL: https://docs.travila.ai/api/models/schema-1k4mjul65u Evaluation summary for a conversation turn, including its recorded conversation, message and profile attribution. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `traceId` | `string` | Optional | Identifier of the evaluation trace. | | `name` | `string` | Optional | Name recorded for the evaluation trace. | | `timestamp` | `string (date-time)` | Optional | Timestamp associated with the evaluation trace. | | `inputJson` | `string` | Optional | Evaluation input serialized as JSON. | | `outputJson` | `string` | Optional | Evaluation output serialized as JSON. | | `latencySeconds` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Elapsed observation latency, in seconds. | | `totalCost` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Total cost reported for the evaluated generation or aggregate. | | `environment` | `string` | Optional | Environment label attached to the evaluation record. | | `tags` | Array of `string` | Optional | Labels associated with the resource for organization or filtering. | | `metadataJson` | `string` | Optional | Additional attributes serialized as a JSON object. | | `bookmarked` | `boolean` | Optional | Whether the evaluation object is bookmarked. | | `version` | `string` | Optional | Version of the resource represented by this message. | | `release` | `string` | Optional | Application release identifier attached to the trace. | | `userId` | `string` | Optional | Identifier of the user associated with the operation. | | `sessionId` | `string` | Optional | Identifier of the evaluation session grouping related traces. | | `observationCount` | `string (int64)` | Optional | Number of observations reported for the evaluation object. Pattern: `^-?\d+$`. | | `conversationId` | `string` | Optional | Identifier of the conversation associated with the trace. | | `sourceUserMessageId` | `string` | Optional | Identifier of the user message that opened the evaluated generation turn. | | `profileId` | `string` | Optional | Identifier of the agent profile associated with the generation. | | `configHash` | `string` | Optional | Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation results. Other settings are excluded; this is not an immutable profile revision. | | `inputTokens` | `string (int64)` | Optional | Input-token usage reported for the evaluated generation. Pattern: `^-?\d+$`. | | `outputTokens` | `string (int64)` | Optional | Output-token usage reported for the evaluated generation. Pattern: `^-?\d+$`. | | `totalTokens` | `string (int64)` | Optional | Total token usage reported for the evaluated generation or aggregate. Pattern: `^-?\d+$`. | | `errorCount` | `string (int64)` | Optional | Number of observations reported at error level. Pattern: `^-?\d+$`. | | `warningCount` | `string (int64)` | Optional | Number of observations reported at warning level. Pattern: `^-?\d+$`. | | `defaultCount` | `string (int64)` | Optional | Number of observations reported at the default level. Pattern: `^-?\d+$`. | | `debugCount` | `string (int64)` | Optional | Number of observations reported at debug level. Pattern: `^-?\d+$`. | | `scores` | Array of [Score](/api/models/schema-1jm5lo00e7#response) | Optional | Evaluation scores returned for the selected objects or query. | | `commentCount` | `string (int64)` | Optional | Number of comments reported on the evaluation object. Pattern: `^-?\d+$`. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get a session](/api/evals/get-session) | `POST /api/v1/evals/get-session` | | [Get a trace](/api/evals/get-trace) | `POST /api/v1/evals/get-trace` | | [List traces](/api/evals/list-traces) | `POST /api/v1/evals/list-traces` |
Models containing this value | Model | Relationship | |---|---| | [SessionDetail](/api/models/schema-ph83s78vr5#response) | Nested in model | | [TraceDetail](/api/models/schema-pha7gtif3l#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # Memory {#overview} URL: https://docs.travila.ai/api/models/schema-1k63a85bkp A memory is a stored statement associated with a user and, when recorded, an agent or conversation and a run or session. The `appId` field is the existing public wire name for the tenant identifier. The field name remains unchanged for compatibility. `metadata` is an object whose values are strings. A search can add a `score`; the provider determines its scale. The score does not measure factual truth. `createdAt` and `updatedAt` are RFC 3339 timestamp strings and may include fractional seconds. Absent timestamps mean that no value was returned. Memory text can be incomplete, stale or incorrect. Show the text and available timestamps to the user before acting on it. Search results are a selection by relevance, not a full account of stored memory. See the [memory cookbook](/managed-agents/memory-knowledge) for review and correction tasks. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | Optional | Unique memory identifier. | | `memory` | `string` | Optional | Stored fact text. It may be incomplete, stale or incorrect. | | `userId` | `string` | Optional | User associated with the memory. | | `agentId` | `string` | Optional | Agent or conversation associated with the memory. | | `appId` | `string` | Optional | Tenant identifier associated with the memory. | | `runId` | `string` | Optional | Associated run or session identifier. | | `metadata` | Map from string to `string` | Optional | Additional string-valued metadata attached to the memory. | | `score` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Relevance score returned by search. Its scale is provider-specific and is not a probability that the fact is correct. | | `createdAt` | `string (date-time)` | Optional | Creation time as an RFC 3339 timestamp; absent when unavailable. | | `updatedAt` | `string (date-time)` | Optional | Last update time as an RFC 3339 timestamp; absent when unavailable. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get a specific memory](/api/conversations/get-memory) | `POST /api/v1/llm/get-memory` | | [List user memories](/api/conversations/list-memories) | `POST /api/v1/llm/list-memories` | | [Semantic search over memories](/api/conversations/search-memories) | `POST /api/v1/llm/search-memories` | Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # Memory relation {#overview} URL: https://docs.travila.ai/api/models/schema-1k84aa8jbi A relation is a directed edge from `source` to `destination`, labeled by `relationship`. These are entity names and an open relationship string; no fixed relationship enumeration is enforced by this contract. Relationships may be absent even when memory records are returned. They describe extracted associations, not verified facts, ownership permissions or lifecycle transitions. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `source` | `string` | Optional | Source entity name. | | `relationship` | `string` | Optional | Open string describing the relationship. Example labels do not restrict the allowed values. | | `destination` | `string` | Optional | Destination entity name. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Semantic search over memories](/api/conversations/search-memories) | `POST /api/v1/llm/search-memories` | Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # ChannelRegistration {#overview} URL: https://docs.travila.ai/api/models/schema-1kaqut27uf Registration state and credential count for one notification channel. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `channel` | `string` (`CHANNEL_PUSH`, `CHANNEL_IN_APP`, `CHANNEL_EMAIL`, `CHANNEL_SMS`, `CHANNEL_CHAT`) or `integer (int32)` | Optional; explicit presence | Notification channel represented by this registration. | | `registered` | `boolean` | Optional | Whether the subscriber has a registration for this channel. | | `credentialCount` | `string (int64)` | Optional | See meaning below. Pattern: `^-?\d+$`. | **`credentialCount`** Number of delivery credentials registered for the channel. e.g., number of device tokens ### Values of `channel` {#response-values-channel} Delivery channel for a notification that does not expect a reply.
| Value | No. | Form | Meaning | |---|---|---|---| | `CHANNEL_PUSH` | 0 | Canonical | See meaning below. | | `CHANNEL_IN_APP` | 1 | Canonical | See meaning below. | | `CHANNEL_EMAIL` | 2 | Canonical | See meaning below. | | `CHANNEL_SMS` | 3 | Canonical | See meaning below. | | `CHANNEL_CHAT` | 4 | Canonical | See meaning below. | **`CHANNEL_PUSH`** Deliver a device push notification through the configured push provider. FCM/APNS push notifications **`CHANNEL_IN_APP`** Deliver the notification to the in-app inbox. Novu Inbox (notification center) **`CHANNEL_EMAIL`** Send a one-way email notification through the configured email provider. SendGrid/SES - do-not-reply only **`CHANNEL_SMS`** Send a one-way SMS notification, such as an alert or authentication message. Twilio - do-not-reply only (alerts, 2FA) **`CHANNEL_CHAT`** Send a one-way message to an integrated chat destination. Slack, Discord, MS Teams - one-way notifications
## Where used {#where-used} | Reference | Relationship | |---|---| | [Get registered notification channels](/api/notifications/get-registered-channels) | `POST /api/v1/notifications/get-registered-channels` | | [Get the caller's subscriber profile](/api/notifications/get-subscriber) | `POST /api/v1/notifications/manage/get-subscriber` | Download the [public reference contract](/reference/api-contract.json). - [notifications OpenAPI](/notifications.yaml) --- # InboxMessageAction {#overview} URL: https://docs.travila.ai/api/models/schema-1kcu6c9rot Interactive action attached to an inbox message, including completion state. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `actionId` | `string` | Optional | Identifier of an action attached to the inbox message. | | `label` | `string` | Optional | Display label for the inbox action. | | `url` | `string` | Optional | Destination URL opened by this inbox action. | | `isPrimary` | `boolean` | Optional | Whether the inbox action is designated as the primary action. | | `completed` | `boolean` | Optional | Whether the user has completed this action via CompleteInboxAction. | | `completedAt` | `string (date-time)` | Optional | Time when this inbox action was marked complete. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get inbox feed messages](/api/notifications/get-inbox-feed) | `POST /api/v1/notifications/get-inbox-feed` |
Models containing this value | Model | Relationship | |---|---| | [InboxMessage](/api/models/schema-1kescd68ar#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [notifications OpenAPI](/notifications.yaml) --- # InboxMessage {#overview} URL: https://docs.travila.ai/api/models/schema-1kescd68ar Notification content and interaction state displayed in a subscriber’s inbox. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `messageId` | `string` | Optional | Identifier of the message represented by this inbox entry. | | `notificationId` | `string` | Optional | Identifier of the notification represented by this inbox entry. | | `title` | `string` | Optional | Title displayed for the inbox notification. | | `body` | `string` | Optional | Body text of the inbox message. | | `data` | Map from string to `string` | Optional | Additional key-value attributes attached to the inbox notification. | | `deepLink` | `string` | Optional | Application deep link associated with the inbox message. | | `imageUrl` | `string` | Optional | Image URL associated with the inbox message. | | `status` | `string` (`MESSAGE_STATUS_UNSEEN`, `MESSAGE_STATUS_SEEN`, `MESSAGE_STATUS_READ`, `MESSAGE_STATUS_UNREAD`, `MESSAGE_STATUS_ARCHIVED`) or `integer (int32)` | Optional; explicit presence | Read, seen, or archived state recorded for the inbox message. | | `category` | `string` | Optional | Category assigned to the inbox message or workflow. | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | | `seenAt` | `string (date-time)` | Optional | Time when the inbox message was marked seen. | | `readAt` | `string (date-time)` | Optional | Time when the inbox message was marked read. | | `actions` | Array of [InboxMessageAction](/api/models/schema-1kcu6c9rot#response) | Optional | See meaning below. | | `tags` | Array of `string` | Optional | Workflow tags for tab assignment (OR-filtered in feed). | | `archived` | `boolean` | Optional | Whether this inbox notification is archived. | | `archivedAt` | `string (date-time)` | Optional | Time when the inbox message was archived. | **`actions`** Interactive actions attached to the inbox message. CTA buttons ### Values of `status` {#response-values-status} Inbox state or requested state transition for a notification message.
| Value | No. | Form | Meaning | |---|---|---|---| | `MESSAGE_STATUS_UNSEEN` | 0 | Canonical | The message has not been marked seen or read. | | `MESSAGE_STATUS_SEEN` | 1 | Canonical | The message has been marked seen and is not marked read or archived. | | `MESSAGE_STATUS_READ` | 2 | Canonical | The message has been marked read and is not archived. | | `MESSAGE_STATUS_UNREAD` | 3 | Canonical | Request clearing the read state; this is an update action rather than a distinct status emitted by message reads. | | `MESSAGE_STATUS_ARCHIVED` | 4 | Canonical | The message has been archived; this state takes precedence over seen and read when reported. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [Get inbox feed messages](/api/notifications/get-inbox-feed) | `POST /api/v1/notifications/get-inbox-feed` | Download the [public reference contract](/reference/api-contract.json). - [notifications OpenAPI](/notifications.yaml) --- # SubscriberData {#overview} URL: https://docs.travila.ai/api/models/schema-1kgdnn5p53 Contact, locale, and custom attributes used by notification delivery. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `firstName` | `string` | Optional | Subscriber’s given name. | | `lastName` | `string` | Optional | Subscriber’s family name. | | `email` | `string` | Optional | Email address used for subscriber contact and delivery. | | `phone` | `string` | Optional | Phone number used for subscriber contact and delivery. | | `avatarUrl` | `string` | Optional | URL of the subscriber’s avatar image. | | `locale` | `string` | Optional | See meaning below. | | `timezone` | `string` | Optional | See meaning below. | | `customData` | Map from string to `string` | Optional | Additional template variables. | **`locale`** Subscriber locale used when rendering notifications. e.g., "en-US" **`timezone`** Subscriber time zone used for notification presentation. e.g., "America/Los\_Angeles" ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `firstName` | `string` | Optional | Subscriber’s given name. | | `lastName` | `string` | Optional | Subscriber’s family name. | | `email` | `string` | Optional | Email address used for subscriber contact and delivery. | | `phone` | `string` | Optional | Phone number used for subscriber contact and delivery. | | `avatarUrl` | `string` | Optional | URL of the subscriber’s avatar image. | | `locale` | `string` | Optional | See meaning below. | | `timezone` | `string` | Optional | See meaning below. | | `customData` | Map from string to `string` | Optional | Additional template variables. | **`locale`** Subscriber locale used when rendering notifications. e.g., "en-US" **`timezone`** Subscriber time zone used for notification presentation. e.g., "America/Los\_Angeles" ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get the caller's subscriber profile](/api/notifications/get-subscriber) | `POST /api/v1/notifications/manage/get-subscriber` | | [Update subscriber profile data](/api/notifications/update-subscriber-data) | `POST /api/v1/notifications/manage/update-subscriber-data` | Download the [public reference contract](/reference/api-contract.json). - [notifications OpenAPI](/notifications.yaml) --- # DailyMeetingTokenProperties {#overview} URL: https://docs.travila.ai/api/models/schema-1kic2mada4 Daily meeting token configuration (subset of common fields) ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `isOwner` | `boolean` | Optional | Whether the issued Daily meeting token grants room-owner privileges. | | `enableAutoRecording` | `boolean` | Optional | Whether the Daily meeting token requests automatic recording. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `isOwner` | `boolean` | Optional | Whether the issued Daily meeting token grants room-owner privileges. | | `enableAutoRecording` | `boolean` | Optional | Whether the Daily meeting token requests automatic recording. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a voice session (in progress)](/api/conversations/create-daily-session) | `POST /api/v1/llm/create-daily-session` |
Models containing this value | Model | Relationship | |---|---| | [DailySession](/api/models/schema-1ktuo6mcah#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # RecordingBucketConfig {#overview} URL: https://docs.travila.ai/api/models/schema-1klrt9eoq8 Object-storage destination and access settings for Daily recordings. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `bucketName` | `string` | Optional | Object-storage bucket used for Daily recordings. | | `bucketRegion` | `string` | Optional | Region containing the Daily recordings bucket. | | `assumeRoleArn` | `string` | Optional | Role ARN Daily uses when accessing the storage bucket. | | `allowApiAccess` | `boolean` | Optional | Whether Daily API access to bucket content is enabled. | | `allowStreamingFromBucket` | `boolean` | Optional | Whether streaming directly from the recording bucket is enabled. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `bucketName` | `string` | Optional | Object-storage bucket used for Daily recordings. | | `bucketRegion` | `string` | Optional | Region containing the Daily recordings bucket. | | `assumeRoleArn` | `string` | Optional | Role ARN Daily uses when accessing the storage bucket. | | `allowApiAccess` | `boolean` | Optional | Whether Daily API access to bucket content is enabled. | | `allowStreamingFromBucket` | `boolean` | Optional | Whether streaming directly from the recording bucket is enabled. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a voice session (in progress)](/api/conversations/create-daily-session) | `POST /api/v1/llm/create-daily-session` |
Models containing this value | Model | Relationship | |---|---| | [DailyRoomProperties](/api/models/schema-1kp6t31pq7#response) | Nested in model | | [DailyRoomProperties](/api/models/schema-1kp6t31pq7#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # TranscriptionBucketConfig {#overview} URL: https://docs.travila.ai/api/models/schema-1knm9ns9ab Object-storage destination and access settings for Daily transcriptions. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `bucketName` | `string` | Optional | Object-storage bucket used for Daily transcriptions. | | `bucketRegion` | `string` | Optional | Region containing the Daily transcriptions bucket. | | `assumeRoleArn` | `string` | Optional | Role ARN Daily uses when accessing the storage bucket. | | `allowApiAccess` | `boolean` | Optional | Whether Daily API access to bucket content is enabled. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `bucketName` | `string` | Optional | Object-storage bucket used for Daily transcriptions. | | `bucketRegion` | `string` | Optional | Region containing the Daily transcriptions bucket. | | `assumeRoleArn` | `string` | Optional | Role ARN Daily uses when accessing the storage bucket. | | `allowApiAccess` | `boolean` | Optional | Whether Daily API access to bucket content is enabled. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a voice session (in progress)](/api/conversations/create-daily-session) | `POST /api/v1/llm/create-daily-session` |
Models containing this value | Model | Relationship | |---|---| | [DailyRoomProperties](/api/models/schema-1kp6t31pq7#response) | Nested in model | | [DailyRoomProperties](/api/models/schema-1kp6t31pq7#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # DailyRoomProperties {#overview} URL: https://docs.travila.ai/api/models/schema-1kp6t31pq7 Daily room configuration (subset of frequently used fields) ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `nbf` | `string (int64)` | Optional | Earliest time at which the Daily room can be joined, as Unix seconds. Pattern: `^-?\d+$`. | | `exp` | `string (int64)` | Optional | Expiration time of the Daily room, as Unix seconds. Pattern: `^-?\d+$`. | | `maxParticipants` | `string (int64)` | Optional | Maximum number of participants allowed in the Daily room. Pattern: `^-?\d+$`. | | `enablePeopleUi` | `boolean` | Optional | Whether the Daily room exposes participant-list controls. | | `enablePipUi` | `boolean` | Optional | Whether the Daily room enables picture-in-picture controls. | | `enableEmojiReactions` | `boolean` | Optional | Whether the Daily room enables emoji reactions. | | `enableHandRaising` | `boolean` | Optional | Whether the Daily room enables hand-raising controls. | | `enablePrejoinUi` | `boolean` | Optional | Whether the Daily room enables its prejoin screen. | | `enableLiveCaptionsUi` | `boolean` | Optional | Whether the Daily room exposes live-caption controls. | | `enableNetworkUi` | `boolean` | Optional | Whether the Daily room exposes network-information controls. | | `enableNoiseCancellationUi` | `boolean` | Optional | Whether the Daily room exposes noise-cancellation controls. | | `enableBreakoutRooms` | `boolean` | Optional | Whether the Daily room enables breakout rooms. | | `enableKnocking` | `boolean` | Optional | When true, requests Daily’s knocking feature for a private room, allowing a participant without a meeting token to ask a meeting owner for admission. It does not restrict a public room. The current room-property mapping forwards true only; false or omission does not explicitly disable a provider setting. | | `ownerOnlyBroadcast` | `boolean` | Optional | Whether broadcasting is restricted to Daily room owners. | | `enforceUniqueUserIds` | `boolean` | Optional | Whether the Daily room requires participant user identifiers to be unique. | | `enableScreenshare` | `boolean` | Optional | Whether screen sharing is enabled in the Daily room. | | `enableVideoProcessingUi` | `boolean` | Optional | Whether the Daily room exposes video-processing controls. | | `enableChat` | `boolean` | Optional | Whether chat is enabled in the Daily room. | | `enableSharedChatHistory` | `boolean` | Optional | Whether the Daily room enables shared chat history. | | `enableAdvancedChat` | `boolean` | Optional | Whether the Daily room enables advanced chat features. | | `enableHiddenParticipants` | `boolean` | Optional | Whether the Daily room allows hidden participants. | | `startVideoOff` | `boolean` | Optional | Whether participants join the Daily room with video initially off. | | `startAudioOff` | `boolean` | Optional | Whether participants join the Daily room with audio initially off. | | `enableRecording` | `string` (`RECORDING_MODE_CLOUD`, `RECORDING_MODE_LOCAL`, `RECORDING_MODE_RAW_TRACKS`, `RECORDING_MODE_DISABLED`) or `integer (int32)` | Optional; explicit presence | Recording mode configured for the Daily room. | | `ejectAtRoomExp` | `boolean` | Optional | Whether participants are removed when the Daily room expires. | | `ejectAfterElapsed` | `string (int64)` | Optional | Elapsed session duration after which participants are removed, in seconds. Pattern: `^-?\d+$`. | | `enableMeshSfu` | `boolean` | Optional | When true, forwards Daily’s `enable_mesh_sfu` room-topology option. Confirm provider support and its effect for your Daily account before relying on it. The current room-property mapping forwards true only; false or omission does not explicitly disable a provider setting. | | `sfuSwitchover` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Daily topology setting controlling the switch to SFU transport. | | `enableAdaptiveSimulcast` | `boolean` | Optional | Whether adaptive simulcast is enabled for the Daily room. | | `enableMultipartyAdaptiveSimulcast` | `boolean` | Optional | Whether multiparty adaptive simulcast is enabled for the Daily room. | | `experimentalOptimizeLargeCalls` | `boolean` | Optional | Whether Daily’s experimental large-call optimization is requested. | | `lang` | `string` | Optional | Language code configured for the Daily room interface, such as en, es, or pt-BR. | | `meetingJoinHook` | `string` | Optional | Webhook URL invoked by the Daily meeting-join hook. | | `geo` | `string` | Optional | Region selected for the Daily room media infrastructure, such as eu-west-2. | | `rtmpGeo` | `string` | Optional | Region selected for Daily RTMP streaming, such as us-west-2. | | `disableRtmpGeoFallback` | `boolean` | Optional | Whether automatic RTMP region fallback is disabled. | | `recordingsBucket` | [RecordingBucketConfig](/api/models/schema-1klrt9eoq8#request) | Optional | Storage destination configured for Daily recordings. | | `transcriptionBucket` | [TranscriptionBucketConfig](/api/models/schema-1knm9ns9ab#request) | Optional | Storage destination configured for Daily transcriptions. | | `recordingsTemplate` | `string` | Optional | Template used for recording object names in storage. | | `transcriptionTemplate` | `string` | Optional | Template used for transcription object names in storage. | ### Values of `enableRecording` {#request-values-enablerecording} Recording mode requested when configuring a Daily room.
| Value | No. | Form | Meaning | |---|---|---|---| | `RECORDING_MODE_CLOUD` | 0 | Canonical | See meaning below. | | `RECORDING_MODE_LOCAL` | 1 | Canonical | See meaning below. | | `RECORDING_MODE_RAW_TRACKS` | 2 | Canonical | See meaning below. | | `RECORDING_MODE_DISABLED` | 3 | Canonical | See meaning below. | **`RECORDING_MODE_CLOUD`** Request the provider's cloud recording mode. "cloud" **`RECORDING_MODE_LOCAL`** Request the provider's local recording mode. "local" **`RECORDING_MODE_RAW_TRACKS`** Request separate raw media tracks for recording. "raw-tracks" **`RECORDING_MODE_DISABLED`** Explicitly disable room recording. explicitly disabled
## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `nbf` | `string (int64)` | Optional | Earliest time at which the Daily room can be joined, as Unix seconds. Pattern: `^-?\d+$`. | | `exp` | `string (int64)` | Optional | Expiration time of the Daily room, as Unix seconds. Pattern: `^-?\d+$`. | | `maxParticipants` | `string (int64)` | Optional | Maximum number of participants allowed in the Daily room. Pattern: `^-?\d+$`. | | `enablePeopleUi` | `boolean` | Optional | Whether the Daily room exposes participant-list controls. | | `enablePipUi` | `boolean` | Optional | Whether the Daily room enables picture-in-picture controls. | | `enableEmojiReactions` | `boolean` | Optional | Whether the Daily room enables emoji reactions. | | `enableHandRaising` | `boolean` | Optional | Whether the Daily room enables hand-raising controls. | | `enablePrejoinUi` | `boolean` | Optional | Whether the Daily room enables its prejoin screen. | | `enableLiveCaptionsUi` | `boolean` | Optional | Whether the Daily room exposes live-caption controls. | | `enableNetworkUi` | `boolean` | Optional | Whether the Daily room exposes network-information controls. | | `enableNoiseCancellationUi` | `boolean` | Optional | Whether the Daily room exposes noise-cancellation controls. | | `enableBreakoutRooms` | `boolean` | Optional | Whether the Daily room enables breakout rooms. | | `enableKnocking` | `boolean` | Optional | When true, requests Daily’s knocking feature for a private room, allowing a participant without a meeting token to ask a meeting owner for admission. It does not restrict a public room. The current room-property mapping forwards true only; false or omission does not explicitly disable a provider setting. | | `ownerOnlyBroadcast` | `boolean` | Optional | Whether broadcasting is restricted to Daily room owners. | | `enforceUniqueUserIds` | `boolean` | Optional | Whether the Daily room requires participant user identifiers to be unique. | | `enableScreenshare` | `boolean` | Optional | Whether screen sharing is enabled in the Daily room. | | `enableVideoProcessingUi` | `boolean` | Optional | Whether the Daily room exposes video-processing controls. | | `enableChat` | `boolean` | Optional | Whether chat is enabled in the Daily room. | | `enableSharedChatHistory` | `boolean` | Optional | Whether the Daily room enables shared chat history. | | `enableAdvancedChat` | `boolean` | Optional | Whether the Daily room enables advanced chat features. | | `enableHiddenParticipants` | `boolean` | Optional | Whether the Daily room allows hidden participants. | | `startVideoOff` | `boolean` | Optional | Whether participants join the Daily room with video initially off. | | `startAudioOff` | `boolean` | Optional | Whether participants join the Daily room with audio initially off. | | `enableRecording` | `string` (`RECORDING_MODE_CLOUD`, `RECORDING_MODE_LOCAL`, `RECORDING_MODE_RAW_TRACKS`, `RECORDING_MODE_DISABLED`) or `integer (int32)` | Optional; explicit presence | Recording mode configured for the Daily room. | | `ejectAtRoomExp` | `boolean` | Optional | Whether participants are removed when the Daily room expires. | | `ejectAfterElapsed` | `string (int64)` | Optional | Elapsed session duration after which participants are removed, in seconds. Pattern: `^-?\d+$`. | | `enableMeshSfu` | `boolean` | Optional | When true, forwards Daily’s `enable_mesh_sfu` room-topology option. Confirm provider support and its effect for your Daily account before relying on it. The current room-property mapping forwards true only; false or omission does not explicitly disable a provider setting. | | `sfuSwitchover` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Daily topology setting controlling the switch to SFU transport. | | `enableAdaptiveSimulcast` | `boolean` | Optional | Whether adaptive simulcast is enabled for the Daily room. | | `enableMultipartyAdaptiveSimulcast` | `boolean` | Optional | Whether multiparty adaptive simulcast is enabled for the Daily room. | | `experimentalOptimizeLargeCalls` | `boolean` | Optional | Whether Daily’s experimental large-call optimization is requested. | | `lang` | `string` | Optional | Language code configured for the Daily room interface, such as en, es, or pt-BR. | | `meetingJoinHook` | `string` | Optional | Webhook URL invoked by the Daily meeting-join hook. | | `geo` | `string` | Optional | Region selected for the Daily room media infrastructure, such as eu-west-2. | | `rtmpGeo` | `string` | Optional | Region selected for Daily RTMP streaming, such as us-west-2. | | `disableRtmpGeoFallback` | `boolean` | Optional | Whether automatic RTMP region fallback is disabled. | | `recordingsBucket` | [RecordingBucketConfig](/api/models/schema-1klrt9eoq8#response) | Optional | Storage destination configured for Daily recordings. | | `transcriptionBucket` | [TranscriptionBucketConfig](/api/models/schema-1knm9ns9ab#response) | Optional | Storage destination configured for Daily transcriptions. | | `recordingsTemplate` | `string` | Optional | Template used for recording object names in storage. | | `transcriptionTemplate` | `string` | Optional | Template used for transcription object names in storage. | ### Values of `enableRecording` {#response-values-enablerecording} Recording mode requested when configuring a Daily room.
| Value | No. | Form | Meaning | |---|---|---|---| | `RECORDING_MODE_CLOUD` | 0 | Canonical | See meaning below. | | `RECORDING_MODE_LOCAL` | 1 | Canonical | See meaning below. | | `RECORDING_MODE_RAW_TRACKS` | 2 | Canonical | See meaning below. | | `RECORDING_MODE_DISABLED` | 3 | Canonical | See meaning below. | **`RECORDING_MODE_CLOUD`** Request the provider's cloud recording mode. "cloud" **`RECORDING_MODE_LOCAL`** Request the provider's local recording mode. "local" **`RECORDING_MODE_RAW_TRACKS`** Request separate raw media tracks for recording. "raw-tracks" **`RECORDING_MODE_DISABLED`** Explicitly disable room recording. explicitly disabled
## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a voice session (in progress)](/api/conversations/create-daily-session) | `POST /api/v1/llm/create-daily-session` |
Models containing this value | Model | Relationship | |---|---| | [DailySession](/api/models/schema-1ktuo6mcah#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # StartSessionUserData {#overview} URL: https://docs.travila.ai/api/models/schema-1kri473p8r Arbitrary user data passed when starting a session, as simple key/value pairs ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `fields` | Map from string to JSON value | Optional | Structured user data passed to the session-start request. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `fields` | Map from string to JSON value | Optional | Structured user data passed to the session-start request. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a voice session (in progress)](/api/conversations/create-daily-session) | `POST /api/v1/llm/create-daily-session` |
Models containing this value | Model | Relationship | |---|---| | [DailySession](/api/models/schema-1ktuo6mcah#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # DailySession {#overview} URL: https://docs.travila.ai/api/models/schema-1ktuo6mcah Session metadata for a Daily/Pipecat voice session ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `agentName` | `string` | Optional | Name of the Pipecat agent running this voice session. | | `sessionId` | `string` | Optional | Identifier of the Pipecat voice session. | | `dailyRoom` | `string` | Optional | Daily room address associated with the voice session. | | `dailyToken` | `string` | Optional | Daily meeting token issued for the voice session. | | `userData` | [StartSessionUserData](/api/models/schema-1kri473p8r#response) | Optional | Generic body payload used to start. | | `dailyRoomProperties` | [DailyRoomProperties](/api/models/schema-1kp6t31pq7#response) | Optional | Properties passed to Daily when configuring the session room. | | `dailyMeetingTokenProperties` | [DailyMeetingTokenProperties](/api/models/schema-1kic2mada4#response) | Optional | Properties passed to Daily when issuing the meeting token. | | `startedAt` | `string (date-time)` | Optional | Time when the operation started. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a voice session (in progress)](/api/conversations/create-daily-session) | `POST /api/v1/llm/create-daily-session` | Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # Location {#overview} URL: https://docs.travila.ai/api/models/schema-1kvbjenggb End-user coordinates and associated location metadata. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `latitude` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Latitude of the location in decimal degrees. | | `longitude` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Longitude of the location in decimal degrees. | | `city` | `string` | Optional | City associated with the location; currently left empty because reverse geocoding is not implemented. | | `timezone` | `string` | Optional | IANA time zone associated with the location, derived from its coordinates server-side. | | `updatedAt` | `string (date-time)` | Optional | Time this record was most recently updated. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | | [Update the caller's location](/api/end-users/update-location) | `POST /api/v1/enduser/update-location` |
Models containing this value | Model | Relationship | |---|---| | [EndUserState](/api/models/schema-1l1et4gp2i#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [end-users OpenAPI](/end-users.yaml) --- # EndUserState {#overview} URL: https://docs.travila.ai/api/models/schema-1l1et4gp2i Captured identity claims and editable profile values for a tenant's end user. Identity claims are copied from the verified token and are read-only through the profile update operations. Location, locale overrides, generation preferences and application metadata are set through their corresponding profile update operations. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `subject` | `string` | Optional | Subject claim identifying the end user within the identity provider. | | `tenantId` | `string` | Optional | Identifier of the tenant that owns or scopes this record. | | `issuer` | `string` | Optional | OIDC issuer identifying the identity provider. | | `projectId` | `string` | Optional | Identifier of the project within the tenant that scopes this record. | | `email` | `string` | Optional | Email address received from the identity provider. | | `emailVerified` | `boolean` | Optional | Whether the identity provider marked the email address as verified. | | `name` | `string` | Optional | Full name received from the identity provider. | | `givenName` | `string` | Optional | Given-name claim received from the identity provider. | | `familyName` | `string` | Optional | Family-name claim received from the identity provider. | | `preferredUsername` | `string` | Optional | Preferred username claim received from the identity provider. | | `picture` | `string` | Optional | Profile picture URL received from the identity provider. | | `phoneNumber` | `string` | Optional | Telephone number received from the identity provider. | | `phoneNumberVerified` | `boolean` | Optional | Whether the identity provider marked the telephone number as verified. | | `signInProvider` | `string` | Optional | Sign-in provider recorded with the captured identity. | | `authMethod` | `string` | Optional | Authentication method recorded with the captured identity. | | `locale` | `string` | Optional | Locale preference associated with the user or subscriber. IdP-sourced default (not the override). | | `zoneinfo` | `string` | Optional | Time zone claim received from the identity provider. IdP-sourced default. | | `customClaims` | Map from string to `string` | Optional | Additional identity claims represented as string key-value pairs. The current end-user store does not populate this field. | | `location` | [Location](/api/models/schema-1kvbjenggb#response) | Optional | Coordinates and derived location metadata selected by the end user. | | `localeOverride` | `string` | Optional | Locale explicitly selected by the end user. When set, takes precedence over the identity provider's locale; when empty, the identity-provider locale is used. | | `defaultGenerationConfig` | [GenerationConfig](/api/models/schema-1h82h7ri5p#response) | Optional | Default model generation settings associated with the end-user profile. | | `metadata` | Map from string to `string` | Optional | Application-defined key-value metadata associated with the end user. | | `firstSeenAt` | `string (date-time)` | Optional | Time the end-user identity was first captured. | | `lastSeenAt` | `string (date-time)` | Optional | Time the end user's identity was most recently observed. | | `updatedAt` | `string (date-time)` | Optional | Time this record was most recently updated. | | `createdAt` | `string (date-time)` | Optional | Time this record was created. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get the caller's end-user profile](/api/end-users/get-end-user) | `POST /api/v1/enduser/get` | Download the [public reference contract](/reference/api-contract.json). - [end-users OpenAPI](/end-users.yaml) --- # Execution {#overview} URL: https://docs.travila.ai/api/models/schema-1l7vrun3li Execution is a single firing record for a scheduled job. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `executionId` | `string (int64)` | Optional | Identifier of the scheduled job execution record. Pattern: `^-?\d+$`. | | `scheduleId` | `string` | Optional | Identifier of the scheduled job. | | `tenantId` | `string` | Optional | Identifier of the tenant that owns or scopes this record. | | `projectId` | `string` | Optional | Identifier of the project within the tenant that scopes this record. | | `scheduledTime` | `string (date-time)` | Optional | Instant for which this execution or trigger was scheduled. | | `startedAt` | `string (date-time)` | Optional | Time at which the scheduled execution started. | | `completedAt` | `string (date-time)` | Optional | Time at which the scheduled execution completed. | | `status` | `string` (`EXECUTION_STATUS_COMPLETED`, `EXECUTION_STATUS_FAILED`, `EXECUTION_STATUS_CANCELLED`) or `integer (int32)` | Optional; explicit presence | Execution outcome recorded for this scheduled attempt. | | `httpStatus` | `string (int64)` | Optional | HTTP status code returned by the target. Pattern: `^-?\d+$`. | | `attempt` | `string (int64)` | Optional | Attempt number (1-based) within this firing. Pattern: `^-?\d+$`. | | `durationMs` | `string (int64)` | Optional | End-to-end duration of the delivery attempt, in milliseconds. Pattern: `^-?\d+$`. | | `targetKind` | `string` | Optional | Kind of target invoked by the scheduled execution. | | `error` | `string` | Optional | Error message when status is FAILED. | | `responseBody` | `string` | Optional | Truncated HTTP response body captured on failed dispatches, with a 4 KiB cap. Empty for successful dispatches by design — only error responses are stored. May also be empty for binary content types or transport-level errors (see response\_size\_bytes / error). | | `responseHeaders` | Map from string to `string` | Optional | Allowlisted response headers from the failed dispatch. Allowlist: content-type, content-length, retry-after, x-request-id, date. | | `responseTruncated` | `boolean` | Optional | True when response\_body was clipped at the 4 KiB cap. | | `responseSizeBytes` | `string (int64)` | Optional | Original response size in bytes (from Content-Length when present, else total bytes read before truncation). Pattern: `^-?\d+$`. | | `endReason` | `string` | Optional | Explanation of an execution failure when status alone is insufficient. `discarded` means the job exhausted `maxAttempts` and will not be retried. Empty when there is no additional reason. | ### Values of `status` {#response-values-status} Terminal result of one scheduled-job firing. Use `end_reason` for additional information about a non-successful result. A firing that exhausts its delivery attempts has status FAILED and `end_reason` "discarded".
| Value | No. | Form | Meaning | |---|---|---|---| | `EXECUTION_STATUS_COMPLETED` | 0 | Canonical | The scheduled HTTP dispatch received a status below 400; this does not establish completion of downstream asynchronous work. | | `EXECUTION_STATUS_FAILED` | 1 | Canonical | The firing failed, including exhausted delivery attempts; inspect end\_reason. | | `EXECUTION_STATUS_CANCELLED` | 2 | Canonical | The firing was cancelled rather than completed, for example by an operator or a non-HTTP cancellation condition, such as a permanent failure to obtain dispatch credentials before the request is sent. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [List executions for a scheduled job](/api/scheduled-jobs/list-executions) | `POST /api/v1/scheduler/list-executions` | Download the [public reference contract](/reference/api-contract.json). - [scheduled-jobs OpenAPI](/scheduled-jobs.yaml) --- # RetryPolicy {#overview} URL: https://docs.travila.ai/api/models/schema-1l9ki2op1i RetryPolicy controls how failed executions are retried. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `maxAttempts` | `string (int64)` | Optional | Maximum delivery attempts (including the initial attempt). Default 10. Pattern: `^-?\d+$`. | | `initialBackoffMs` | `string (int64)` | Optional | Initial backoff before the first retry, in milliseconds. Default 5000. Pattern: `^-?\d+$`. | | `maxBackoffMs` | `string (int64)` | Optional | Maximum backoff cap, in milliseconds. Default 1800000 (30 min). Pattern: `^-?\d+$`. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `maxAttempts` | `string (int64)` | Optional | Maximum delivery attempts (including the initial attempt). Default 10. Pattern: `^-?\d+$`. | | `initialBackoffMs` | `string (int64)` | Optional | Initial backoff before the first retry, in milliseconds. Default 5000. Pattern: `^-?\d+$`. | | `maxBackoffMs` | `string (int64)` | Optional | Maximum backoff cap, in milliseconds. Default 1800000 (30 min). Pattern: `^-?\d+$`. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a scheduled job](/api/scheduled-jobs/create-job) | `POST /api/v1/scheduler/create-job` | | [Get a scheduled job](/api/scheduled-jobs/get-job) | `POST /api/v1/scheduler/get-job` | | [List scheduled jobs](/api/scheduled-jobs/list-jobs) | `POST /api/v1/scheduler/list-jobs` | | [Pause a scheduled job](/api/scheduled-jobs/pause-job) | `POST /api/v1/scheduler/pause-job` | | [Resume a scheduled job](/api/scheduled-jobs/resume-job) | `POST /api/v1/scheduler/resume-job` | | [Update a scheduled job](/api/scheduled-jobs/update-job) | `POST /api/v1/scheduler/update-job` |
Models containing this value | Model | Relationship | |---|---| | [Schedule](/api/models/schema-1ld0l8rmvg#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [scheduled-jobs OpenAPI](/scheduled-jobs.yaml) --- # ScheduleTarget {#overview} URL: https://docs.travila.ai/api/models/schema-1lbkptb5rj ScheduleTarget describes the HTTP endpoint that receives each job invocation. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `url` | `string (uri)` | **Required in requests** | Destination URL. Must be a valid absolute URI. Minimum length: 1. | | `method` | `string` | Optional | HTTP method to use. Defaults to "POST". | | `kind` | `string` | **Required in requests** | Logical kind used for routing and observability (e.g., "notification", "llm\_conversation", "metering"). Required. Minimum length: 1. | | `payload` | Map from string to JSON value | Optional | Arbitrary JSON payload forwarded verbatim to the target. | ## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `url` | Minimum length | `1` | | `url` | Uri | `true` | | `kind` | Minimum length | `1` | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `url` | `string` | **Required in requests** | Destination URL. Must be a valid absolute URI. | | `method` | `string` | Optional | HTTP method to use. Defaults to "POST". | | `kind` | `string` | **Required in requests** | Logical kind used for routing and observability (e.g., "notification", "llm\_conversation", "metering"). Required. | | `payload` | Map from string to JSON value | Optional | Arbitrary JSON payload forwarded verbatim to the target. | ## Request validation {#response-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `url` | Minimum length | `1` | | `url` | Uri | `true` | | `kind` | Minimum length | `1` | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a scheduled job](/api/scheduled-jobs/create-job) | `POST /api/v1/scheduler/create-job` | | [Get a scheduled job](/api/scheduled-jobs/get-job) | `POST /api/v1/scheduler/get-job` | | [List scheduled jobs](/api/scheduled-jobs/list-jobs) | `POST /api/v1/scheduler/list-jobs` | | [Pause a scheduled job](/api/scheduled-jobs/pause-job) | `POST /api/v1/scheduler/pause-job` | | [Resume a scheduled job](/api/scheduled-jobs/resume-job) | `POST /api/v1/scheduler/resume-job` | | [Update a scheduled job](/api/scheduled-jobs/update-job) | `POST /api/v1/scheduler/update-job` |
Models containing this value | Model | Relationship | |---|---| | [Schedule](/api/models/schema-1ld0l8rmvg#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [scheduled-jobs OpenAPI](/scheduled-jobs.yaml) --- # Schedule {#overview} URL: https://docs.travila.ai/api/models/schema-1ld0l8rmvg Schedule is the canonical representation of a scheduled job. Creating any schedule type returns the `Schedule` resource directly, with the same shape used by get, pause and resume operations. [`triggerCount`](/api/models/schema-1ld0l8rmvg#response-field-triggercount): Cumulative firings. [`failureCount`](/api/models/schema-1ld0l8rmvg#response-field-failurecount): Cumulative failed first attempts; a later successful retry does not erase the earlier failure. [`consecutiveFailureCount`](/api/models/schema-1ld0l8rmvg#response-field-consecutivefailurecount): Current sequence of failed firings; a successful attempt resets it. This counter drives auto-pause. Zero-valued counters can be omitted. Nonzero 64-bit counters are decimal JSON strings; preserve their integer precision. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `scheduleId` | `string` | Optional | Server-assigned identifier of the scheduled job, prefixed with "sched\_". | | `tenantId` | `string` | Optional | Identifier of the tenant that owns or scopes this record. | | `projectId` | `string` | Optional | Identifier of the project within the tenant that scopes this record. | | `ownerSubject` | `string` | Optional | Subject identifier of the owning user or service account. | | `name` | `string` | Optional | Human-readable name assigned to the scheduled job. | | `description` | `string` | Optional | Human-readable explanation of the scheduled job. | | `scheduleType` | `string` (`SCHEDULE_TYPE_CRON`, `SCHEDULE_TYPE_ONCE`, `SCHEDULE_TYPE_RECURRING_INTERVAL`) or `integer (int32)` | Optional; explicit presence | Schedule type and expression. | | `cronExpression` | `string` | Optional | Cron expression. Populated when schedule\_type is SCHEDULE\_TYPE\_CRON. | | `timezone` | `string` | Optional | IANA timezone for cron evaluation. Default "UTC". | | `scheduledAt` | `string (date-time)` | Optional | Exact fire time. Populated when schedule\_type is SCHEDULE\_TYPE\_ONCE. | | `intervalSeconds` | `string (int64)` | Optional | Interval between firings in seconds. Populated when schedule\_type is SCHEDULE\_TYPE\_RECURRING\_INTERVAL. Pattern: `^-?\d+$`. | | `target` | [ScheduleTarget](/api/models/schema-1lbkptb5rj#response) | Optional | Destination and invocation settings for the scheduled job. | | `state` | `string` (`SCHEDULE_STATUS_ACTIVE`, `SCHEDULE_STATUS_PAUSED`, `SCHEDULE_STATUS_DELETED`) or `integer (int32)` | Optional; explicit presence | Lifecycle status controlling whether the scheduled job can trigger. | | `retryPolicy` | [RetryPolicy](/api/models/schema-1l9ki2op1i#response) | Optional | Attempt limits and backoff settings for the scheduled target. | | `metadata` | Map from string to JSON value | Optional | Application-defined JSON metadata attached to the scheduled job. | | `autoPauseThreshold` | `string (int64)` | Optional | See meaning below. Pattern: `^-?\d+$`. | | `externalId` | `string` | Optional | Client-supplied external id. Echoed back when set; empty otherwise. Optional, immutable, unique within (tenant\_id, project\_id) among live schedules. Never starts with the reserved system-id prefix "sched\_". | | `createdAt` | `string (date-time)` | Optional | Time at which the scheduled job was created. | | `createdBySubject` | `string` | Optional | Subject identifier recorded when the schedule was created. | | `updatedAt` | `string (date-time)` | Optional | Time this record was most recently updated. | | `updatedBySubject` | `string` | Optional | Subject identifier recorded when the schedule was last updated. | | `pausedAt` | `string (date-time)` | Optional | Time at which the schedule was paused. | | `pausedBySubject` | `string` | Optional | Subject identifier recorded for the schedule pause. | | `pausedReason` | `string` | Optional | Explanation recorded for the schedule pause. | | `resumedAt` | `string (date-time)` | Optional | Time at which the schedule was most recently resumed. | | `resumedBySubject` | `string` | Optional | Subject identifier recorded for the schedule resume. | | `deletedAt` | `string (date-time)` | Optional | Time at which the schedule was deleted. | | `deletedBySubject` | `string` | Optional | Subject identifier recorded for the schedule deletion. | | `lastTriggeredAt` | `string (date-time)` | Optional | Time when the schedule was last triggered. Trigger and failure counters advance at most once per scheduled firing on its first attempt; retrying that firing does not inflate them. | | `nextTriggerAt` | `string (date-time)` | Optional | Time calculated for the next scheduled trigger. | | `triggerCount` | `string (int64)` | Optional | Scheduled times that ran, cumulative for the schedule's whole life. Pattern: `^-?\d+$`. | | `failureCount` | `string (int64)` | Optional | See meaning below. Pattern: `^-?\d+$`. | | `consecutiveFailureCount` | `string (int64)` | Optional | See meaning below. Pattern: `^-?\d+$`. | **`autoPauseThreshold`** If consecutive\_failure\_count reaches this threshold the job is auto-paused (state PAUSED, paused\_by\_subject "system\:auto-pause"). It is compared against consecutive\_failure\_count, NOT failure\_count. failure\_count is cumulative for the schedule's whole life, so a healthy schedule that collects scattered failures over months would eventually exceed any threshold and pause itself forever. A stored threshold of 0 disables auto-pause; otherwise the threshold is from 3 through 100. The public create request uses 0 or omission to select the default of 10, and the public update request uses 0 or omission to leave the current threshold unchanged. These public requests do not provide a disable control. **`failureCount`** Scheduled times whose first attempt failed, cumulative for the schedule's whole life. A firing that fails on attempt 1 and succeeds on retry still counts here — a failure was observed. This counter does NOT drive auto-pause. See consecutive\_failure\_count. **`consecutiveFailureCount`** Current run of consecutive failed firings. This is the counter auto\_pause\_threshold is compared against. Incremented when a firing's first attempt fails; reset to 0 as soon as any attempt of any firing succeeds. So a firing that fails on attempt 1 and succeeds on retry has net zero effect here while still advancing failure\_count — the target recovered, so the run is over. A non-success terminal outcome counts as a failure, including a firing cancelled on a terminal 4xx. ### Values of `scheduleType` {#response-values-scheduletype} Expression format that determines when a scheduled job fires.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCHEDULE_TYPE_CRON` | 0 | Canonical | Fire according to the configured cron expression and timezone. For example, `0 9 * * 1-5` selects 09:00 on weekdays in that timezone. | | `SCHEDULE_TYPE_ONCE` | 1 | Canonical | Fire once at the configured scheduled timestamp. | | `SCHEDULE_TYPE_RECURRING_INTERVAL` | 2 | Canonical | Fire repeatedly at the configured interval in seconds. |
### Values of `state` {#response-values-state} Lifecycle condition that determines whether a scheduled job may trigger: active, paused, or deleted. This is separate from the outcome of an individual scheduled-job execution.
| Value | No. | Form | Meaning | |---|---|---|---| | `SCHEDULE_STATUS_ACTIVE` | 0 | Canonical | The schedule is active and can trigger at its next matching time. | | `SCHEDULE_STATUS_PAUSED` | 1 | Canonical | The schedule is paused and does not trigger until resumed. | | `SCHEDULE_STATUS_DELETED` | 2 | Canonical | The schedule has been deleted; this is a schedule condition, not an execution outcome. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a scheduled job](/api/scheduled-jobs/create-job) | `POST /api/v1/scheduler/create-job` | | [Get a scheduled job](/api/scheduled-jobs/get-job) | `POST /api/v1/scheduler/get-job` | | [List scheduled jobs](/api/scheduled-jobs/list-jobs) | `POST /api/v1/scheduler/list-jobs` | | [Pause a scheduled job](/api/scheduled-jobs/pause-job) | `POST /api/v1/scheduler/pause-job` | | [Resume a scheduled job](/api/scheduled-jobs/resume-job) | `POST /api/v1/scheduler/resume-job` | | [Update a scheduled job](/api/scheduled-jobs/update-job) | `POST /api/v1/scheduler/update-job` | Download the [public reference contract](/reference/api-contract.json). - [scheduled-jobs OpenAPI](/scheduled-jobs.yaml) --- # SecretMetadata {#overview} URL: https://docs.travila.ai/api/models/schema-1lhjc44i8n Metadata returned by secret read operations. Secret values are not included. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `name` | `string` | Optional | Name identifying the secret within its project. | | `projectId` | `string` | Optional | Identifier of the project within the tenant that scopes this secret. `default` identifies the default project. | | `description` | `string` | Optional | Human-readable explanation of the secret. | | `labels` | Map from string to `string` | Optional | Free-form labels used to organize and identify secrets. Free-form, e.g. \{"kind": "mcp-auth"}. | | `version` | `string (int64)` | Optional | Version number of the stored secret metadata. Increments on every PutSecret. Pattern: `^-?\d+$`. | | `createdBy` | `string` | Optional | Subject identifier recorded for the creator of this record. Subject from the X-User-ID header, when present. | | `createdAt` | `string (date-time)` | Optional | Time this record was created. | | `updatedAt` | `string (date-time)` | Optional | Time this record was most recently updated. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get a secret's metadata](/api/secrets/get-secret-metadata) | `POST /api/v1/secrets/get-metadata` | | [List secrets](/api/secrets/list-secrets) | `POST /api/v1/secrets/list` | | [Create or update a secret](/api/secrets/put-secret) | `POST /api/v1/secrets/put` | Download the [public reference contract](/reference/api-contract.json). - [secrets OpenAPI](/secrets.yaml) --- # ObjectRef {#overview} URL: https://docs.travila.ai/api/models/schema-1lj1ellabu ObjectRef references an object in storage ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `bucket` | `string` | Optional | Storage bucket containing the object. | | `key` | `string` | Optional | Object key within the selected storage bucket. | | `provider` | `string` (`STORAGE_PROVIDER_GCS`, `STORAGE_PROVIDER_S3`, `STORAGE_PROVIDER_FILESYSTEM`, `STORAGE_PROVIDER_AZURE_BLOB`) or `integer (int32)` | Optional; explicit presence | Storage provider used to access the object. | ### Values of `provider` {#response-values-provider} Backend that stores the file bytes associated with a storage record.
| Value | No. | Form | Meaning | |---|---|---|---| | `STORAGE_PROVIDER_GCS` | 0 | Canonical | Google Cloud Storage. | | `STORAGE_PROVIDER_S3` | 1 | Canonical | See meaning below. | | `STORAGE_PROVIDER_FILESYSTEM` | 2 | Canonical | See meaning below. | | `STORAGE_PROVIDER_AZURE_BLOB` | 3 | Canonical | Azure Blob Storage. | **`STORAGE_PROVIDER_S3`** Amazon S3 or a storage service implementing the S3 interface. Amazon S3 (and compatibles) **`STORAGE_PROVIDER_FILESYSTEM`** A filesystem accessible to the storage service. Local filesystem
## Where used {#where-used} | Reference | Relationship | |---|---| | [Generate a pre-signed download URL](/api/storage/generate-download-url) | `POST /api/v1/storage/generate-download-url` | | [Get file metadata](/api/storage/get-file-metadata) | `POST /api/v1/storage/get-file-metadata` | | [Get storage state](/api/storage/get-state) | `POST /api/v1/storage/get-state` | | [List files and folders in a directory](/api/storage/list-files) | `POST /api/v1/storage/list-files` | | [Move or rename a file](/api/storage/move-file) | `POST /api/v1/storage/move-file` | | [Register a file uploaded via pre-signed URL](/api/storage/register-uploaded-file) | `POST /api/v1/storage/register-uploaded-file` | | [Search files](/api/storage/search-files) | `POST /api/v1/storage/search-files` | | [Update file metadata](/api/storage/update-file-metadata) | `POST /api/v1/storage/update-file-metadata` | | [Upload a file (deprecated)](/api/storage/upload-file) | `POST /api/v1/storage/upload-file` |
Models containing this value | Model | Relationship | |---|---| | [FileInfo](/api/models/schema-1lls6fo8p7#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [storage OpenAPI](/storage.yaml) --- # FileInfo {#overview} URL: https://docs.travila.ai/api/models/schema-1lls6fo8p7 FileInfo contains metadata about a file ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `fileId` | `string` | Optional | Stable identifier of the stored file. | | `name` | `string` | Optional | Name of the file within its containing folder. | | `path` | `string` | Optional | Full path (e.g., "/documents/report.pdf"). | | `folderPath` | `string` | Optional | Parent folder path. | | `sizeBytes` | `string (int64)` | Optional | Size of the file content, in bytes. Pattern: `^-?\d+$`. | | `contentType` | `string` | Optional | Media type of the file content. | | `uploadedAt` | `string` | Optional | RFC3339 timestamp. | | `modifiedAt` | `string` | Optional | RFC3339 timestamp. | | `metadata` | Map from string to `string` | Optional | Custom metadata. | | `tags` | Array of `string` | Optional | User-defined tags. | | `description` | `string` | Optional | Optional description. | | `storageRef` | [ObjectRef](/api/models/schema-1lj1ellabu#response) | Optional | Reference to actual storage location. | | `checksum` | `string` | Optional | File checksum (SHA256). | | `version` | `string (int64)` | Optional | Version number (for versioning support). Pattern: `^-?\d+$`. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Generate a pre-signed download URL](/api/storage/generate-download-url) | `POST /api/v1/storage/generate-download-url` | | [Get file metadata](/api/storage/get-file-metadata) | `POST /api/v1/storage/get-file-metadata` | | [Get storage state](/api/storage/get-state) | `POST /api/v1/storage/get-state` | | [List files and folders in a directory](/api/storage/list-files) | `POST /api/v1/storage/list-files` | | [Move or rename a file](/api/storage/move-file) | `POST /api/v1/storage/move-file` | | [Register a file uploaded via pre-signed URL](/api/storage/register-uploaded-file) | `POST /api/v1/storage/register-uploaded-file` | | [Search files](/api/storage/search-files) | `POST /api/v1/storage/search-files` | | [Update file metadata](/api/storage/update-file-metadata) | `POST /api/v1/storage/update-file-metadata` | | [Upload a file (deprecated)](/api/storage/upload-file) | `POST /api/v1/storage/upload-file` |
Models containing this value | Model | Relationship | |---|---| | [StorageManagerState](/api/models/schema-phpid7698e#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [storage OpenAPI](/storage.yaml) --- # FieldMask {#overview} URL: https://docs.travila.ai/api/models/schema-oh20e1g6e1 Standard JSON representation of this value. ## Meaning and usage {#meaning} `FieldMask` represents a set of symbolic field paths, for example: paths: "f.a" paths: "f.b.d" Here `f` represents a field in some root message, `a` and `b` fields in the message found in `f`, and `d` a field found in the message in `f.b`. Field masks are used to specify a subset of fields that should be returned by a get operation or modified by an update operation. Field masks also have a custom JSON encoding (see below). # Field Masks in Projections When used in the context of a projection, a response message or sub-message is filtered by the API to only contain those fields as specified in the mask. For example, if the mask in the previous example is applied to a response message as follows: f \{ a : 22 b \{ d : 1 x : 2 } y : 13 } z: 8 The result will not contain specific values for fields x,y and z (their value will be set to the default, and omitted in proto text output): f \{ a : 22 b \{ d : 1 } } A repeated field is not allowed except at the last position of a paths string. If a FieldMask object is not present in a get operation, the operation applies to all fields (as if a FieldMask of all fields had been specified). Note that a field mask does not necessarily apply to the top-level response message. In case of a REST get operation, the field mask applies directly to the response, but in case of a REST list operation, the mask instead applies to each individual message in the returned resource list. In case of a REST custom method, other definitions may be used. Where the mask applies will be clearly documented together with its declaration in the API. In any case, the effect on the returned resource/resources is required behavior for APIs. # Field Masks in Update Operations A field mask in update operations specifies which fields of the targeted resource are going to be updated. The API is required to only change the values of the fields as specified in the mask and leave the others untouched. If a resource is passed in to describe the updated values, the API ignores the values of all fields not covered by the mask. If a repeated field is specified for an update operation, new values will be appended to the existing repeated field in the target resource. Note that a repeated field is only allowed in the last position of a `paths` string. If a sub-message is specified in the last position of the field mask for an update operation, then new value will be merged into the existing sub-message in the target resource. For example, given the target message: f \{ b \{ d: 1 x: 2 } c: \[1] } And an update message: f \{ b \{ d: 10 } c: \[2] } then if the field mask is: paths: \["f.b", "f.c"] then the result will be: f \{ b \{ d: 10 x: 2 } c: \[1, 2] } An implementation may provide options to override this default behavior for repeated and message fields. In order to reset a field's value to the default, the field must be in the mask and set to the default value in the provided resource. Hence, in order to reset all fields of a resource, provide a default instance of the resource and set all fields in the mask, or do not provide a mask as described below. If a field mask is not present on update, the operation applies to all fields (as if a field mask of all fields has been specified). Note that in the presence of schema evolution, this may mean that fields the client does not know and has therefore not filled into the request will be reset to their default. If this is unwanted behavior, a specific service may require a client to always specify a field mask, producing an error if not. As with get operations, the location of the resource which describes the updated values in the request message depends on the operation kind. In any case, the effect of the field mask is required to be honored by the API. ## Considerations for HTTP REST The HTTP kind of an update operation which uses a field mask must be set to PATCH instead of PUT in order to satisfy HTTP semantics (PUT must only be used for full updates). # JSON Encoding of Field Masks In JSON, a field mask is encoded as a single string where paths are separated by a comma. Fields name in each path are converted to/from lower-camel naming conventions. As an example, consider the following message declarations: message Profile \{ User user = 1; Photo photo = 2; } message User \{ string display\_name = 1; string address = 2; } In proto a field mask for `Profile` may look as such: mask \{ paths: "user.display\_name" paths: "photo" } In JSON, the same mask is represented as below: \{ mask: "user.displayName,photo" } # Field Masks and Oneof Fields Field masks treat fields in oneofs just as regular fields. Consider the following message: message SampleMessage \{ oneof test\_oneof \{ string name = 4; SubMessage sub\_message = 9; } } The field mask can be: mask \{ paths: "name" } Or: mask \{ paths: "sub\_message" } Note that oneof type names ("test\_oneof" in this case) cannot be used in paths. ## Field Mask Verification The implementation of any API method which has a FieldMask type field in the request should verify the included field paths, and return an `INVALID_ARGUMENT` error if any path is unmappable. Use the published contract view for this imported type’s empty, null and text representation. An ordinary record field list alone does not define that representation. ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | ## In requests {#request} API JSON uses JSON field names (camelCase). JSON shape: `string`. ## Where used {#where-used} | Reference | Relationship | |---|---| | [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` | | [Update a prompt fragment](/api/agent-profiles/update-prompt-fragment) | `POST /api/v1/prompt-fragments/update` | | [Update prompt variables](/api/conversations/update-prompt-variables) | `POST /api/v1/llm/update-prompt-variables` | Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) - [conversations OpenAPI](/conversations.yaml) --- # AppCategory {#overview} URL: https://docs.travila.ai/api/models/schema-ohbp8u7c1i App category ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | Optional | Identifier of the app category record. | | `nameSlug` | `string` | Optional | Category slug identifying the entry in the Pipedream catalog. | | `name` | `string` | Optional | Display label of the app category in the Pipedream catalog. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [List app categories](/api/connected-apps/pipedream-list-app-categories) | `POST /api/v1/integrations/pipedream/list-app-categories` | Download the [public reference contract](/reference/api-contract.json). - [connected-apps OpenAPI](/connected-apps.yaml) --- # PipedreamPageInfo {#overview} URL: https://docs.travila.ai/api/models/schema-ohepdcsvjo Pagination information returned in list responses ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `count` | `string (int64)` | Optional | Items in current page. Pattern: `^-?\d+$`. | | `totalCount` | `string (int64)` | Optional | Total items matching query. Pattern: `^-?\d+$`. | | `startCursor` | `string` | Optional | Cursor for start of page. | | `endCursor` | `string` | Optional | Cursor for end of page. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [List the caller's connected accounts](/api/connected-apps/pipedream-list-accounts-for-current-user) | `POST /api/v1/integrations/pipedream/list-accounts` | | [List app categories](/api/connected-apps/pipedream-list-app-categories) | `POST /api/v1/integrations/pipedream/list-app-categories` | | [List connectable apps](/api/connected-apps/pipedream-list-apps) | `POST /api/v1/integrations/pipedream/list-apps` | Download the [public reference contract](/reference/api-contract.json). - [connected-apps OpenAPI](/connected-apps.yaml) --- # PaginationInfo {#overview} URL: https://docs.travila.ai/api/models/schema-ohggnansec Page position and aggregate counts accompanying a paginated provider listing. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `total` | `string (int64)` | Optional | Total number of entries reported by the listing. Pattern: `^-?\d+$`. | | `page` | `string (int64)` | Optional | Page number used by this listing operation. Pattern: `^-?\d+$`. | | `perPage` | `string (int64)` | Optional | Number of entries requested per page. Pattern: `^-?\d+$`. | | `totalPages` | `string (int64)` | Optional | Total number of pages reported for the current query. Pattern: `^-?\d+$`. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [List webhook event deliveries](/api/webhooks/list-webhook-deliveries) | `POST /api/v1/webhooks/list-deliveries` | | [List webhook endpoints](/api/webhooks/list-webhook-endpoints) | `POST /api/v1/webhooks/list-endpoints` | | [List webhook subscriptions](/api/webhooks/list-webhook-subscriptions) | `POST /api/v1/webhooks/list-subscriptions` | Download the [public reference contract](/reference/api-contract.json). - [webhooks OpenAPI](/webhooks.yaml) --- # AgentProfileMetadata {#overview} URL: https://docs.travila.ai/api/models/schema-ohmse4h323 Profile identity and selection hints for a picker or router. This projection excludes the system prompt, generation settings, tools and MCP configuration; retrieve AgentProfile to inspect the runtime configuration. These hints do not establish that routing is active. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `profileId` | `string` | Optional | Identifier of the agent profile associated with the operation or generation. | | `name` | `string` | Optional | Display name used when presenting an agent profile in the library. | | `description` | `string` | Optional | Human-readable description of the resource. | | `whenToUse` | `string` | Optional | Instructions describing when this agent profile should be selected. | | `keywords` | Array of `string` | Optional | Keywords associated with discovery or selection of the agent profile. | | `enabled` | `boolean` | Optional | Whether this configuration is enabled. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get the profile library](/api/agent-profiles/get-agent-profile-library) | `POST /api/v1/agent-profiles/library` |
Models containing this value | Model | Relationship | |---|---| | [AgentProfileLibrary](/api/models/schema-ou55jqfkih#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) --- # PromptParameter {#overview} URL: https://docs.travila.ai/api/models/schema-ohoj3j73c1 A parameter used by a prompt template ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `name` | `string` | Optional | Name used to bind a value to this prompt-template parameter. | | `description` | `string` | Optional | Explanation of the value expected for this prompt parameter. | | `type` | `string` | Optional | Free-form type hint, e.g. "string", "number" | | `required` | `boolean` | Optional | Whether the prompt parameter must be supplied by the caller. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get an MCP prompt template](/api/conversations/mcp-get-prompt) | `POST /api/v1/llm/mcp-get-prompt` | | [List MCP prompt templates](/api/conversations/mcp-list-prompts) | `POST /api/v1/llm/mcp-list-prompts` |
Models containing this value | Model | Relationship | |---|---| | [PromptDefinition](/api/models/schema-ou94n9qv48#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # SourcePromptFragment {#overview} URL: https://docs.travila.ai/api/models/schema-ohqh497pal Shared template block supplied for import. Its path resolves source include directives; fragment\_id supplies the stable output identity when shared fragments are emitted, or is derived from the path when omitted. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `fragmentId` | `string` | Optional | Identifier of the reusable prompt fragment. | | `name` | `string` | Optional | Display name for the imported reusable prompt fragment. | | `sourceDsl` | `string` | Optional | Raw source text (may itself contain @include / metadata comments). | | `path` | `string` | Optional | Include path, e.g. "\_shared/safety-module.txt" | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) --- # AgentProfileVersionInfo {#overview} URL: https://docs.travila.ai/api/models/schema-ohrdb6rrpn Version identifier and creation time for an immutable agent-profile revision. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `version` | `string (int64)` | Optional | Version of the resource represented by this message. Pattern: `^-?\d+$`. | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [List a profile's versions](/api/agent-profiles/list-agent-profile-versions) | `POST /api/v1/agent-profiles/versions` | Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) --- # CursorPageInfo {#overview} URL: https://docs.travila.ai/api/models/schema-oi1c4l4i8b Opaque-cursor pagination details. A cursor is used to request the next page; arbitrary page-number seeking is not supported. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `nextCursor` | `string` | Optional | Pass back as the request's `cursor` for the next page. Empty on the last page. | | `limit` | `string (int64)` | Optional | Maximum number of entries requested from the listing. Pattern: `^-?\d+$`. | | `totalItems` | `string (int64)` | Optional; explicit presence | Total number of matching items when it can be counted exactly. Absent when the selected filters do not support an exact total. Pattern: `^-?\d+$`. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [List dataset runs](/api/evals/list-dataset-runs) | `POST /api/v1/evals/list-dataset-runs` | | [List observations](/api/evals/list-observations) | `POST /api/v1/evals/list-observations` | | [List scores](/api/evals/list-scores) | `POST /api/v1/evals/list-scores` | | [List sessions](/api/evals/list-sessions) | `POST /api/v1/evals/list-sessions` | | [List traces](/api/evals/list-traces) | `POST /api/v1/evals/list-traces` | Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # EvaluationPageInfo {#overview} URL: https://docs.travila.ai/api/models/schema-oi3nhojaso One-based offset-pagination position, page size and result totals. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `page` | `string (int64)` | Optional | One-based page number. Pattern: `^-?\d+$`. | | `limit` | `string (int64)` | Optional | Maximum number of entries requested from the listing. Pattern: `^-?\d+$`. | | `totalItems` | `string (int64)` | Optional | Total item count reported for the current query. Pattern: `^-?\d+$`. | | `totalPages` | `string (int64)` | Optional | Total number of pages reported for the current query. Pattern: `^-?\d+$`. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [List annotation queue items](/api/evals/list-annotation-queue-items) | `POST /api/v1/evals/list-annotation-queue-items` | | [List annotation queues](/api/evals/list-annotation-queues) | `POST /api/v1/evals/list-annotation-queues` | | [List comments](/api/evals/list-comments) | `POST /api/v1/evals/list-comments` | | [List dataset items](/api/evals/list-dataset-items) | `POST /api/v1/evals/list-dataset-items` | | [List datasets](/api/evals/list-datasets) | `POST /api/v1/evals/list-datasets` | | [List score configs](/api/evals/list-score-configs) | `POST /api/v1/evals/list-score-configs` | Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # BulkTriggerEvent {#overview} URL: https://docs.travila.ai/api/models/schema-oiqb7f8bbv One notification workflow trigger included in a bulk submission. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `workflowId` | `string` | **Required in requests** | Identifier of the notification workflow to trigger. Minimum length: 1. | | `userId` | `string` | **Required in requests** | Identifier of the user associated with the operation. Minimum length: 1. | | `payload` | Map from string to JSON value | Optional | Template variables and event data passed to the notification workflow. | | `overrides` | Map from string to JSON value | Optional | Provider-specific overrides applied to the notification trigger. | | `transactionId` | `string` | Optional | Identifier correlating a notification trigger with later status or cancellation requests. | ## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `workflowId` | Minimum length | `1` | | `userId` | Minimum length | `1` | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Send a notification to multiple users](/api/notifications/send-bulk-notification) | `POST /api/v1/notifications/manage/send-bulk` | Download the [public reference contract](/reference/api-contract.json). - [notifications OpenAPI](/notifications.yaml) --- # BulkTriggerResult {#overview} URL: https://docs.travila.ai/api/models/schema-oisl2i7j7o Provider acknowledgement and errors for one bulk notification trigger. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `acknowledged` | `boolean` | Optional | Whether the notification provider acknowledged the trigger. | | `status` | `string` | Optional | Status reported by the notification provider. | | `transactionId` | `string` | Optional | Identifier correlating a notification trigger with later status or cancellation requests. | | `errors` | Array of `string` | Optional | Errors reported while processing notification requests. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Send a notification to multiple users](/api/notifications/send-bulk-notification) | `POST /api/v1/notifications/manage/send-bulk` | Download the [public reference contract](/reference/api-contract.json). - [notifications OpenAPI](/notifications.yaml) --- # ChannelToggles {#overview} URL: https://docs.travila.ai/api/models/schema-oj4cvo85fs Per-channel notification toggles. All fields are optional so callers can patch only the channels they want to change; omitted fields remain unchanged. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `inApp` | `boolean` | Optional; explicit presence | Whether in-app notification delivery is enabled. | | `push` | `boolean` | Optional; explicit presence | Whether push notification delivery is enabled. | | `email` | `boolean` | Optional; explicit presence | Whether email notification delivery is enabled. | | `sms` | `boolean` | Optional; explicit presence | Whether SMS notification delivery is enabled. | | `chat` | `boolean` | Optional; explicit presence | Whether chat notification delivery is enabled. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `inApp` | `boolean` | Optional; explicit presence | Whether in-app notification delivery is enabled. | | `push` | `boolean` | Optional; explicit presence | Whether push notification delivery is enabled. | | `email` | `boolean` | Optional; explicit presence | Whether email notification delivery is enabled. | | `sms` | `boolean` | Optional; explicit presence | Whether SMS notification delivery is enabled. | | `chat` | `boolean` | Optional; explicit presence | Whether chat notification delivery is enabled. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get notification preferences](/api/notifications/get-preferences) | `POST /api/v1/notifications/get-preferences` | | [Get the caller's subscriber profile](/api/notifications/get-subscriber) | `POST /api/v1/notifications/manage/get-subscriber` | | [Bulk-update per-workflow preferences](/api/notifications/bulk-update-preferences) | `POST /api/v1/notifications/bulk-update-preferences` | | [Update global notification preferences](/api/notifications/update-global-preference) | `POST /api/v1/notifications/update-global-preference` | | [Update per-workflow notification preferences](/api/notifications/update-workflow-preference) | `POST /api/v1/notifications/update-workflow-preference` |
Models containing this value | Model | Relationship | |---|---| | [GlobalPreferences](/api/models/schema-p20l2ff92r#response) | Nested in model | | [UpdateWorkflowPreferenceRequest](/api/models/schema-p38aqgjs3a#request) | Nested in model | | [WorkflowPreferences](/api/models/schema-p2jctrvcjc#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [notifications OpenAPI](/notifications.yaml) --- # InboxFeedFilter {#overview} URL: https://docs.travila.ai/api/models/schema-ojrenemkui Read-state, category, tag, and archive criteria selecting inbox entries. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `unseenOnly` | `boolean` | Optional | Whether the inbox filter selects only unseen messages. | | `unreadOnly` | `boolean` | Optional | Whether the inbox filter selects only unread messages. | | `feedIds` | Array of `string` | Optional | Filter by Novu feed identifiers. | | `categories` | Array of `string` | Optional | Categories used to select inbox messages. | | `tags` | Array of `string` | Optional | Filter by workflow tags (OR logic per Novu semantics). | | `archived` | `boolean` | Optional | When true, include archived messages. False or omission selects the live inbox and excludes archived messages. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get inbox feed messages](/api/notifications/get-inbox-feed) | `POST /api/v1/notifications/get-inbox-feed` | Download the [public reference contract](/reference/api-contract.json). - [notifications OpenAPI](/notifications.yaml) --- # InboxMessageSummary {#overview} URL: https://docs.travila.ai/api/models/schema-ojt6e86adl Summary of an inbox message after a mark operation. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `messageId` | `string` | Optional | Identifier of the inbox message represented by this summary. | | `channel` | `string` | Optional | Delivery channel reported for this inbox message. | | `read` | `boolean` | Optional | Whether the inbox message has been marked read. | | `seen` | `boolean` | Optional | Whether the inbox message has been marked seen. | | `archived` | `boolean` | Optional | Whether this inbox message is archived. | | `content` | `string` | Optional | Rendered notification content. | | `subject` | `string` | Optional | Subject text for the notification message. | | `status` | `string` | Optional | Status reported by the notification provider. | | `createdAt` | `string` | Optional | Time when this record was created. | | `lastReadDate` | `string` | Optional | Most recent timestamp recorded for reading inbox messages. | | `lastSeenDate` | `string` | Optional | Most recent timestamp recorded for seeing inbox messages. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Mark a single inbox message](/api/notifications/mark-inbox-message-as) | `POST /api/v1/notifications/mark-inbox-message` | Download the [public reference contract](/reference/api-contract.json). - [notifications OpenAPI](/notifications.yaml) --- # OperationStatus {#overview} URL: https://docs.travila.ai/api/models/schema-ok4lj6t1ka Mirrors Novu's common delete/mutate acknowledgement response. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `acknowledged` | `boolean` | Optional | Whether the provider acknowledged the requested operation. | | `status` | `string` | Optional | See meaning below. | **`status`** Status reported by the notification provider. e.g., "done", "deleted" ## Where used {#where-used} | Reference | Relationship | |---|---| | [Archive an inbox message](/api/notifications/archive-inbox-message) | `POST /api/v1/notifications/archive-inbox-message` | | [Complete an inbox message action](/api/notifications/complete-inbox-action) | `POST /api/v1/notifications/complete-inbox-action` | | [Delete an inbox message](/api/notifications/delete-inbox-message) | `POST /api/v1/notifications/delete-inbox-message` | | [Delete the caller's subscriber profile](/api/notifications/delete-subscriber) | `POST /api/v1/notifications/manage/delete-subscriber` | | [Delete a notification topic](/api/notifications/delete-topic) | `POST /api/v1/notifications/manage/delete-topic` | | [Revert an inbox message action](/api/notifications/revert-inbox-action) | `POST /api/v1/notifications/revert-inbox-action` | | [Unarchive an inbox message](/api/notifications/unarchive-inbox-message) | `POST /api/v1/notifications/unarchive-inbox-message` | Download the [public reference contract](/reference/api-contract.json). - [notifications OpenAPI](/notifications.yaml) --- # PendingChange {#overview} URL: https://docs.travila.ai/api/models/schema-ok6l245g8f Notification configuration change awaiting promotion to another provider environment. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `changeId` | `string` | Optional | Identifier of a pending notification configuration change. | | `type` | `string` | Optional | See meaning below. | | `entityName` | `string` | Optional | Name of the notification resource affected by the pending change. | | `entityId` | `string` | Optional | Identifier of the notification resource affected by the pending change. | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | | `createdBy` | `string` | Optional | Identifier of the actor that created the pending change. | **`type`** Kind of notification resource affected by the pending configuration change. "NotificationTemplate", "MessageTemplate", etc. ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get pending workflow changes](/api/notifications/get-pending-changes) | `POST /api/v1/notifications/manage/get-pending-changes` | Download the [public reference contract](/reference/api-contract.json). - [notifications OpenAPI](/notifications.yaml) --- # PromotionError {#overview} URL: https://docs.travila.ai/api/models/schema-okaelqap4k Failure associated with promotion of one notification configuration change. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `changeId` | `string` | Optional | Identifier of a pending notification configuration change. | | `error` | `string` | Optional | Error information reported for this operation or item. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Promote all pending workflow changes](/api/notifications/promote-all-changes) | `POST /api/v1/notifications/manage/promote-all-changes` | Download the [public reference contract](/reference/api-contract.json). - [notifications OpenAPI](/notifications.yaml) --- # SubscriberSummary {#overview} URL: https://docs.travila.ai/api/models/schema-okk1bp39s4 Contact and presence information returned in a subscriber listing. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `subscriberId` | `string` | Optional | Identifier of the notification subscriber. | | `email` | `string` | Optional | Email address used for subscriber contact and delivery. | | `firstName` | `string` | Optional | Subscriber’s given name. | | `lastName` | `string` | Optional | Subscriber’s family name. | | `isOnline` | `boolean` | Optional | Whether the provider reports the subscriber currently online. | | `lastOnlineAt` | `string (date-time)` | Optional | Time when the provider last observed the subscriber online. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [List all subscribers](/api/notifications/list-subscribers) | `POST /api/v1/notifications/manage/list-subscribers` | Download the [public reference contract](/reference/api-contract.json). - [notifications OpenAPI](/notifications.yaml) --- # TopicSubscriptionError {#overview} URL: https://docs.travila.ai/api/models/schema-okmh5pnenu Subscriber-specific failure reported while changing notification-topic membership. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `subscriberId` | `string` | Optional | Identifier of the notification subscriber. | | `code` | `string` | Optional | Provider error code for the topic subscription failure. | | `message` | `string` | Optional | Diagnostic or descriptive text returned by the operation. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Add subscribers to a topic](/api/notifications/add-subscribers-to-topic) | `POST /api/v1/notifications/manage/add-subscribers-to-topic` | | [Remove subscribers from a topic](/api/notifications/remove-subscribers-from-topic) | `POST /api/v1/notifications/manage/remove-subscribers-from-topic` |
Models containing this value | Model | Relationship | |---|---| | [TopicSubscriptionResult](/api/models/schema-p2eb0gb1ln#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [notifications OpenAPI](/notifications.yaml) --- # HeyGenElevenLabsSettings {#overview} URL: https://docs.travila.ai/api/models/schema-on0k8c8den ElevenLabs settings used within HeyGen voice configuration ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `stability` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | ElevenLabs voice-stability setting passed through HeyGen. | | `similarityBoost` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | ElevenLabs voice-similarity setting passed through HeyGen. | | `modelId` | `string` | Optional | ElevenLabs model identifier used for HeyGen voice synthesis. | | `style` | `string (int64)` | Optional | Integer style code. Pattern: `^-?\d+$`. | | `useSpeakerBoost` | `boolean` | Optional | Whether ElevenLabs speaker boost is requested for the HeyGen voice. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a voice session (in progress)](/api/conversations/create-daily-session) | `POST /api/v1/llm/create-daily-session` |
Models containing this value | Model | Relationship | |---|---| | [HeyGenVoiceSettings](/api/models/schema-p3askj7st1#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # TTSConfig {#overview} URL: https://docs.travila.ai/api/models/schema-on2m1c27d9 Cartesia Sonic-3 text-to-speech configuration for a Socayo agent. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `voiceId` | `string` | **Required in requests** | Provider-specific voice identifier (Cartesia voice\_id) Minimum length: 1. | | `model` | `string` | Optional | Optional Cartesia model identifier (e.g., "sonic-english") | | `sampleRate` | `string (int64)` | Optional | Optional sample rate override (Hz) Pattern: `^-?\d+$`. | | `volume` | `number (double)` | **Required in requests** | Volume multiplier (0.5..2.0) Minimum: 0.5. Maximum: 2. | | `speed` | `number (double)` | **Required in requests** | Speed multiplier (0.6..1.5) Minimum: 0.6. Maximum: 1.5. | | `emotion` | `string` | Optional | Single emotion string (e.g., "neutral", "excited") | | `language` | `string` | Optional | Cartesia language code (e.g., "EN") | ## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `voiceId` | Minimum length | `1` | | `volume` | At most | `2` | | `volume` | At least | `0.5` | | `speed` | At most | `1.5` | | `speed` | At least | `0.6` | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a voice session (in progress)](/api/conversations/create-daily-session) | `POST /api/v1/llm/create-daily-session` |
Models containing this value | Model | Relationship | |---|---| | [SocayoAgentConfig](/api/models/schema-phip2o3ju4#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # TransportConfig {#overview} URL: https://docs.travila.ai/api/models/schema-on4mqk0ok8 Transport audio configuration ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `audioInSampleRate` | `string (int64)` | Optional | Sample rate of incoming audio, in hertz. Pattern: `^-?\d+$`. | | `audioOutSampleRate` | `string (int64)` | Optional | Sample rate of outgoing audio, in hertz. Pattern: `^-?\d+$`. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a voice session (in progress)](/api/conversations/create-daily-session) | `POST /api/v1/llm/create-daily-session` |
Models containing this value | Model | Relationship | |---|---| | [SocayoAgentConfig](/api/models/schema-phip2o3ju4#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # SecretRef {#overview} URL: https://docs.travila.ai/api/models/schema-opqho625u2 Reference to a secret within the same tenant and project as the resource that uses it. Cross-project and cross-tenant secret references are not supported. Secret values are write-only through the project secret API: writes accept a value and return metadata, while read operations return metadata without the value. Resource references name a secret within their own scope rather than carrying its value or an alternate tenant or project. ### Input constraints ### name The name must contain one through 63 characters. Its first character must be a lowercase ASCII letter or digit. Every remaining character must be a lowercase ASCII letter, digit, period, underscore, or hyphen. ## Meaning and usage {#meaning} See the [definition above](#overview). ### Input constraints See the [definition above](#overview). ### name See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `name` | `string` | **Required in requests** | Name identifying the secret within its project. Pattern: `^[a-z0-9][a-z0-9._-]{0,62}$`. | ## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `name` | Pattern | `^[a-z0-9][a-z0-9._-]{0,62}$` | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `name` | `string` | **Required in requests** | Name identifying the secret within its project. | ## Request validation {#response-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `name` | Pattern | `^[a-z0-9][a-z0-9._-]{0,62}$` | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Register a custom MCP server](/api/mcp-servers/create-custom-mcp-server) | `POST /api/v1/mcp-servers/create` | | [Get a custom MCP server](/api/mcp-servers/get-custom-mcp-server) | `POST /api/v1/mcp-servers/get` | | [List custom MCP servers](/api/mcp-servers/list-custom-mcp-servers) | `POST /api/v1/mcp-servers/list` | | [Update a custom MCP server](/api/mcp-servers/update-custom-mcp-server) | `POST /api/v1/mcp-servers/update` |
Models containing this value | Model | Relationship | |---|---| | [CustomMCPServer](/api/models/schema-p1cuh9jgfq#response) | Nested in model | | [CustomMCPServer](/api/models/schema-p1cuh9jgfq#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [mcp-servers OpenAPI](/mcp-servers.yaml) --- # FolderInfo {#overview} URL: https://docs.travila.ai/api/models/schema-opsbitjge1 FolderInfo contains metadata about a folder ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `folderId` | `string` | Optional | Unique folder ID. | | `name` | `string` | Optional | See meaning below. | | `path` | `string` | Optional | Full path (e.g., "/documents/work"). | | `parentPath` | `string` | Optional | Parent folder path. | | `createdAt` | `string` | Optional | RFC3339 timestamp. | | `modifiedAt` | `string` | Optional | RFC3339 timestamp. | | `metadata` | Map from string to `string` | Optional | Custom metadata. | | `fileCount` | `string (int64)` | Optional | Number of files (direct children). Pattern: `^-?\d+$`. | | `subfolderCount` | `string (int64)` | Optional | Number of subfolders. Pattern: `^-?\d+$`. | | `totalSizeBytes` | `string (int64)` | Optional | Total size of all files in folder (recursive). Pattern: `^-?\d+$`. | **`name`** Name of the folder within its parent folder. Folder name ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a new folder](/api/storage/create-folder) | `POST /api/v1/storage/create-folder` | | [Get storage state](/api/storage/get-state) | `POST /api/v1/storage/get-state` | | [List files and folders in a directory](/api/storage/list-files) | `POST /api/v1/storage/list-files` |
Models containing this value | Model | Relationship | |---|---| | [StorageManagerState](/api/models/schema-phpid7698e#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [storage OpenAPI](/storage.yaml) --- # FileFilter {#overview} URL: https://docs.travila.ai/api/models/schema-oq26kmqtvq Name, extension, tag and size criteria for selecting stored files. Upload-time fields are accepted but are not applied by the current list and search handlers. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `extensions` | Array of `string` | Optional | File extensions used to restrict matching files. | | `tags` | Array of `string` | Optional | Labels associated with the resource for organization or filtering. | | `minSizeBytes` | `string (int64)` | Optional | Minimum file size included by the filter, in bytes. Pattern: `^-?\d+$`. | | `maxSizeBytes` | `string (int64)` | Optional | Maximum file size included by the filter, in bytes. Pattern: `^-?\d+$`. | | `uploadedAfter` | `string` | Optional | Declared lower upload-time bound. The current list-files and search-files handlers accept this field but do not apply it. Do not rely on it to exclude files by date; inspect returned timestamps and the operation’s result limits. | | `uploadedBefore` | `string` | Optional | Declared upper upload-time bound. The current list-files and search-files handlers accept this field but do not apply it. Do not rely on it to exclude files by date; inspect returned timestamps and the operation’s result limits. | | `nameContains` | `string` | Optional | Text that must occur in the selected file’s name. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [List files and folders in a directory](/api/storage/list-files) | `POST /api/v1/storage/list-files` | | [Search files](/api/storage/search-files) | `POST /api/v1/storage/search-files` | Download the [public reference contract](/reference/api-contract.json). - [storage OpenAPI](/storage.yaml) --- # FileUrlResult {#overview} URL: https://docs.travila.ai/api/models/schema-oq46sv4kha Signed download URL or item-specific error for one requested file. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `fileId` | `string` | Optional | Stable identifier of the stored file. | | `url` | `string` | Optional | Signed download URL for the requested file. | | `success` | `boolean` | Optional | Whether the operation reports a successful result. | | `error` | `string` | Optional | Error information reported for this operation or item. | | `contentType` | `string` | Optional | MIME type (e.g. "image/jpeg"); lets consumers pick the right content-part shape (IMAGE\_URL vs FILE\_URL). Empty when success = false or unknown. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Generate pre-signed download URLs for multiple files](/api/storage/batch-generate-download-urls) | `POST /api/v1/storage/batch-generate-download-urls` | Download the [public reference contract](/reference/api-contract.json). - [storage OpenAPI](/storage.yaml) --- # App {#overview} URL: https://docs.travila.ai/api/models/schema-oti80oaqc4 App metadata ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | Optional | Identifier of the app record. | | `nameSlug` | `string` | Optional | Unique slug identifier (e.g., "slack", "github"). | | `name` | `string` | Optional | Display name of the integration app in the Pipedream catalog. | | `authType` | `string` (`AUTH_TYPE_KEYS`, `AUTH_TYPE_OAUTH`, `AUTH_TYPE_NONE`) or `integer (int32)` | Optional; explicit presence | Authentication mechanism reported for the integration app. | | `description` | `string` | Optional | Human-readable description of the resource. | | `imgSrc` | `string` | Optional | Logo image URL supplied for the integration app. | | `customFieldsJson` | `string` | Optional | JSON string for custom fields. | | `categories` | Array of `string` | Optional | Categories assigned to the integration app. | | `featuredWeight` | `string (int64)` | Optional | Provider weight used to order featured apps. Pattern: `^-?\d+$`. | ### Values of `authType` {#response-values-authtype} Credential mechanism an integration app uses when connecting an account.
| Value | No. | Form | Meaning | |---|---|---|---| | `AUTH_TYPE_KEYS` | 0 | Canonical | See meaning below. | | `AUTH_TYPE_OAUTH` | 1 | Canonical | See meaning below. | | `AUTH_TYPE_NONE` | 2 | Canonical | See meaning below. | **`AUTH_TYPE_KEYS`** The app uses API-key credentials. API keys **`AUTH_TYPE_OAUTH`** The app uses an OAuth authorization flow. OAuth 2.0 **`AUTH_TYPE_NONE`** The app does not require authentication credentials. No auth required
## Where used {#where-used} | Reference | Relationship | |---|---| | [List connectable apps](/api/connected-apps/pipedream-list-apps) | `POST /api/v1/integrations/pipedream/list-apps` | | [Retrieve one app by slug](/api/connected-apps/pipedream-retrieve-app) | `POST /api/v1/integrations/pipedream/retrieve-app` | Download the [public reference contract](/reference/api-contract.json). - [connected-apps OpenAPI](/connected-apps.yaml) --- # AgentProfileLibrary {#overview} URL: https://docs.travila.ai/api/models/schema-ou55jqfkih Selection metadata for the project’s agent profiles. Retrieve an individual profile to read its complete model and tool configuration. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `profiles` | Array of [AgentProfileMetadata](/api/models/schema-ohmse4h323#response) | Optional | Profile identity and selection metadata. Full configurations are retrieved individually with GetAgentProfile. | | `defaultProfileId` | `string` | Optional | Project's nominated default profile. Native conversations do not automatically apply it when active\_profile\_id is empty; the client must explicitly select its intended profile. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get the profile library](/api/agent-profiles/get-agent-profile-library) | `POST /api/v1/agent-profiles/library` | Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) --- # MCPServerStatus {#overview} URL: https://docs.travila.ai/api/models/schema-ou7clc4l5s Status information returned for an MCP server. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `serverId` | `string` | Optional | Identifier of the MCP server whose status is reported. | | `name` | `string` | Optional | Display name of the MCP server. | | `status` | `string` (`MCP_SERVER_CONNECTION_STATUS_CONNECTED`, `MCP_SERVER_CONNECTION_STATUS_DISCONNECTED`, `MCP_SERVER_CONNECTION_STATUS_ERROR`, `MCP_SERVER_CONNECTION_STATUS_DISCOVERING`) or `integer (int32)` | Optional; explicit presence | Current connection status reported for the MCP server. | | `toolsDiscovered` | `string (int64)` | Optional | Number of tool definitions found during the last discovery. Pattern: `^-?\d+$`. | | `lastDiscoveryDuration` | `string` | Optional | Elapsed duration of the last MCP tool discovery. Pattern: `^-?(?:0\|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$`. | | `lastError` | `string` | Optional | Most recent error reported while contacting the MCP server. | | `lastDiscoveryTime` | `string (date-time)` | Optional | Time when MCP tool discovery last ran. | | `kind` | `string` (`MCP_SERVER_KIND_INTERNAL`, `MCP_SERVER_KIND_BUILT_IN`, `MCP_SERVER_KIND_CUSTOM`, `MCP_SERVER_KIND_EXTERNAL`, `MCP_SERVER_KIND_INTEGRATION`) or `integer (int32)` | Optional; explicit presence | Ownership of this server. Populated by ListAvailableServers for every source it merges. | ### Values of `status` {#response-values-status} Current connection or discovery condition reported for an MCP server.
| Value | No. | Form | Meaning | |---|---|---|---| | `MCP_SERVER_CONNECTION_STATUS_CONNECTED` | 0 | Canonical | A connection to the MCP server is established. | | `MCP_SERVER_CONNECTION_STATUS_DISCONNECTED` | 1 | Canonical | There is no active connection to the MCP server. | | `MCP_SERVER_CONNECTION_STATUS_ERROR` | 2 | Canonical | A connection or discovery attempt encountered an error. | | `MCP_SERVER_CONNECTION_STATUS_DISCOVERING` | 3 | Canonical | The platform is discovering the server's available capabilities. |
### Values of `kind` {#response-values-kind} Ownership and connection category of an MCP server available to the platform. INTERNAL servers use fully qualified server IDs; BUILT\_IN IDs start with `built-in:`, CUSTOM with `custom:`, and INTEGRATION with `pipedream:`. EXTERNAL identifies existing externally configured servers with unprefixed IDs. Use this category when displaying or filtering the server catalog.
| Value | No. | Form | Meaning | |---|---|---|---| | `MCP_SERVER_KIND_INTERNAL` | 0 | Canonical | See meaning below. | | `MCP_SERVER_KIND_BUILT_IN` | 1 | Canonical | See meaning below. | | `MCP_SERVER_KIND_CUSTOM` | 2 | Canonical | See meaning below. | | `MCP_SERVER_KIND_EXTERNAL` | 3 | Canonical | An existing externally configured server. New entries are not supported in this category; it does not designate a new tenant registration. | | `MCP_SERVER_KIND_INTEGRATION` | 4 | Canonical | See meaning below. | **`MCP_SERVER_KIND_INTERNAL`** A server compiled into the deployment and dispatched in-process. Compiled into the deployment and dispatched in-process. No vendor cost. **`MCP_SERVER_KIND_BUILT_IN`** A platform-owned catalog server invoked with platform-held vendor credentials. Platform-owned catalog entry, called with a platform-held vendor key and no end-user identity. Metered per call. **`MCP_SERVER_KIND_CUSTOM`** A tenant-registered server invoked with the tenant's credentials. Registered by a tenant, called with the tenant's own credential. **`MCP_SERVER_KIND_INTEGRATION`** An account-connected integration reached through Pipedream Connect. Account-bound integration reached through Pipedream Connect.
## Where used {#where-used} | Reference | Relationship | |---|---| | [List available MCP servers](/api/conversations/mcp-list-available-servers) | `POST /api/v1/llm/mcp-list-available-servers` | Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # PromptDefinition {#overview} URL: https://docs.travila.ai/api/models/schema-ou94n9qv48 A prompt definition exposed by an MCP server ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `name` | `string` | Optional | Name identifying the prompt template on the MCP server. | | `title` | `string` | Optional | Display title of the MCP prompt template. | | `description` | `string` | Optional | Description of the MCP prompt template’s purpose. | | `parameters` | Array of [PromptParameter](/api/models/schema-ohoj3j73c1#response) | Optional | Parameter definitions accepted by the prompt template. | | `template` | `string` | Optional | Template string; clients may render with parameters. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get an MCP prompt template](/api/conversations/mcp-get-prompt) | `POST /api/v1/llm/mcp-get-prompt` | | [List MCP prompt templates](/api/conversations/mcp-list-prompts) | `POST /api/v1/llm/mcp-list-prompts` | Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # AnnotationQueueItem {#overview} URL: https://docs.travila.ai/api/models/schema-ovc35nr9td Evaluation object assigned to an annotation queue with completion state and attribution. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `itemId` | `string` | Optional | Identifier of the annotation queue item. | | `queueId` | `string` | Optional | Identifier of the annotation queue. | | `objectId` | `string` | Optional | Identifier of the evaluation object addressed by the annotation queue item. | | `objectType` | `string` (`EVAL_TARGET_TYPE_TRACE`, `EVAL_TARGET_TYPE_OBSERVATION`, `EVAL_TARGET_TYPE_DATASET_RUN`, `EVAL_TARGET_TYPE_SESSION`) or `integer (int32)` | Optional; explicit presence | Kind of evaluation object addressed by the annotation queue item. | | `status` | `string` (`ANNOTATION_QUEUE_ITEM_STATUS_PENDING`, `ANNOTATION_QUEUE_ITEM_STATUS_COMPLETED`) or `integer (int32)` | Optional; explicit presence | Completion state of the annotation queue item. | | `completedAt` | `string (date-time)` | Optional | Time when the operation was marked complete. | | `completedBy` | `string` | Optional | Identifier of the user who completed the annotation queue item. | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | ### Values of `objectType` {#response-values-objecttype} Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_TARGET_TYPE_TRACE` | 0 | Canonical | A complete trace identified by its trace identifier. | | `EVAL_TARGET_TYPE_OBSERVATION` | 1 | Canonical | A specific observation within a trace. | | `EVAL_TARGET_TYPE_DATASET_RUN` | 2 | Canonical | An evaluation run over a dataset. | | `EVAL_TARGET_TYPE_SESSION` | 3 | Canonical | A session grouping multiple traces. The evaluation harness attaches session-scoped judge scores directly; the provider does not expose a session-level evaluator target. |
### Values of `status` {#response-values-status} Progress of a work item in a human annotation queue.
| Value | No. | Form | Meaning | |---|---|---|---| | `ANNOTATION_QUEUE_ITEM_STATUS_PENDING` | 0 | Canonical | The item is waiting for its annotation to be completed. | | `ANNOTATION_QUEUE_ITEM_STATUS_COMPLETED` | 1 | Canonical | Annotation of the queue item has been completed. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [Complete an annotation queue item](/api/evals/complete-annotation-queue-item) | `POST /api/v1/evals/complete-annotation-queue-item` | | [List annotation queue items](/api/evals/list-annotation-queue-items) | `POST /api/v1/evals/list-annotation-queue-items` | Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # Comment {#overview} URL: https://docs.travila.ai/api/models/schema-ove4pre5lb Authored text attached to a trace, observation, or other evaluation object. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `commentId` | `string` | Optional | Identifier of the evaluation comment. | | `objectType` | `string` (`COMMENT_OBJECT_TYPE_TRACE`, `COMMENT_OBJECT_TYPE_OBSERVATION`, `COMMENT_OBJECT_TYPE_SESSION`, `COMMENT_OBJECT_TYPE_PROMPT`) or `integer (int32)` | Optional; explicit presence | Kind of evaluation object addressed by the comment. | | `objectId` | `string` | Optional | Identifier of the evaluation object addressed by the comment. | | `content` | `string` | Optional | Text content of the evaluation comment. | | `authorUserId` | `string` | Optional | Identifier recorded for the user who authored the comment. A stored author identifier alone does not attest to verified human provenance. | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | | `updatedAt` | `string (date-time)` | Optional | Time when this record was last updated. | ### Values of `objectType` {#response-values-objecttype} Kind of evaluation object to which a reviewer comment is attached.
| Value | No. | Form | Meaning | |---|---|---|---| | `COMMENT_OBJECT_TYPE_TRACE` | 0 | Canonical | Attach the comment to a trace. | | `COMMENT_OBJECT_TYPE_OBSERVATION` | 1 | Canonical | Attach the comment to a particular observation. | | `COMMENT_OBJECT_TYPE_SESSION` | 2 | Canonical | Attach the comment to a session. | | `COMMENT_OBJECT_TYPE_PROMPT` | 3 | Canonical | Attach the comment to a specific prompt version using that version's UUID, not the prompt name. A comment on one version does not appear on later versions. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [List comments](/api/evals/list-comments) | `POST /api/v1/evals/list-comments` | Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # EvalFilter {#overview} URL: https://docs.travila.ai/api/models/schema-ovg7lvels1 Typed comparison operand and column selector for querying evaluation-provider records. The filter type selects which single value field is meaningful. ### Input constraints ### type Select a listed comparison type. ## Meaning and usage {#meaning} See the [definition above](#overview). ### Input constraints See the [definition above](#overview). ### type See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `type` | `string` (`EVAL_FILTER_TYPE_DATETIME`, `EVAL_FILTER_TYPE_STRING`, `EVAL_FILTER_TYPE_NUMBER`, `EVAL_FILTER_TYPE_STRING_OPTIONS`, `EVAL_FILTER_TYPE_CATEGORY_OPTIONS`, `EVAL_FILTER_TYPE_ARRAY_OPTIONS`, `EVAL_FILTER_TYPE_BOOLEAN`, `EVAL_FILTER_TYPE_NULL`, `EVAL_FILTER_TYPE_STRING_OBJECT`, `EVAL_FILTER_TYPE_NUMBER_OBJECT`, `EVAL_FILTER_TYPE_BOOLEAN_OBJECT`) or `integer (int32)` (`0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`) | **Required in requests** | Discriminator selecting the evaluation filter’s operand type. | | `column` | `string` | **Required in requests** | Evaluation filter column identifier, for example traceName, scores\_avg, metadata or level. Minimum length: 1. | | `operator` | `string` | **Required in requests** | Operator accepted for the selected filter type, for example contains, any of or >=. Minimum length: 1. | | `key` | `string` | Optional | Set only for the \*\_OBJECT types: the metadata key or score name. | | `stringValue` | `string` | Optional | Text operand used by a text-valued evaluation filter. | | `numberValue` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Numeric operand used by the evaluation filter. | | `booleanValue` | `boolean` | Optional | Boolean operand used by the selected evaluation filter type. | | `stringValues` | Array of `string` | Optional | Text values used by the \*\_OPTIONS comparison types. | | `timeValue` | `string (date-time)` | Optional | Timestamp operand used by the evaluation filter. | ### Values of `type` {#request-values-type} Operand shape and comparison vocabulary for an evaluation-record filter. Types and operators follow the provider's v3.224.1 filter vocabulary, including keyed object variants.
| Value | No. | Form | Meaning | |---|---|---|---| | `EVAL_FILTER_TYPE_DATETIME` | 0 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_STRING` | 1 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_NUMBER` | 2 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_STRING_OPTIONS` | 3 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_CATEGORY_OPTIONS` | 4 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_ARRAY_OPTIONS` | 5 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_BOOLEAN` | 6 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_NULL` | 7 | Canonical | See meaning below. | | `EVAL_FILTER_TYPE_STRING_OBJECT` | 8 | Canonical | Compare a string-valued member identified by a key, such as a metadata property. STRING\_OBJECT supports metadata filtering; NUMBER\_OBJECT and BOOLEAN\_OBJECT support score filtering keyed by score name. | | `EVAL_FILTER_TYPE_NUMBER_OBJECT` | 9 | Canonical | Compare a numeric member identified by a key, such as a named score. | | `EVAL_FILTER_TYPE_BOOLEAN_OBJECT` | 10 | Canonical | Compare a boolean member identified by a key. | **`EVAL_FILTER_TYPE_DATETIME`** Compare a date-time value using ordered comparisons. \> \< >= \<= **`EVAL_FILTER_TYPE_STRING`** Compare text using equality or supported substring and prefix or suffix operators. \= contains does not contain starts with ends with **`EVAL_FILTER_TYPE_NUMBER`** Compare a numeric value using equality or ordered comparisons. \= > \< >= \<= **`EVAL_FILTER_TYPE_STRING_OPTIONS`** Match a string against a set of allowed or excluded choices. any of none of **`EVAL_FILTER_TYPE_CATEGORY_OPTIONS`** Match a category against a set of allowed or excluded choices. any of none of **`EVAL_FILTER_TYPE_ARRAY_OPTIONS`** Match array contents using any-of, none-of or all-of selection. any of none of all of **`EVAL_FILTER_TYPE_BOOLEAN`** Compare a boolean value for equality or inequality. \= \<> **`EVAL_FILTER_TYPE_NULL`** Test whether the selected property is null or non-null. is null is not null
## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `type` | Required value | `true` | | `type` | Defined enum value | `true` | | `column` | Minimum length | `1` | | `operator` | Minimum length | `1` | ## Where used {#where-used} | Reference | Relationship | |---|---| | [List observations](/api/evals/list-observations) | `POST /api/v1/evals/list-observations` | | [List scores](/api/evals/list-scores) | `POST /api/v1/evals/list-scores` | | [List sessions](/api/evals/list-sessions) | `POST /api/v1/evals/list-sessions` | | [List traces](/api/evals/list-traces) | `POST /api/v1/evals/list-traces` | Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # ThreadSummary {#overview} URL: https://docs.travila.ai/api/models/schema-p16s9mefht Conversation summary returned by thread listing and detail operations. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `threadId` | `string` | Optional | Identifier of the conversation thread. | | `userId` | `string` | Optional | Identifier of the user associated with the conversation thread. | | `title` | `string` | Optional | Display title of the conversation thread. | | `tags` | Array of `string` | Optional | Labels associated with the conversation thread. | | `status` | `string` (`CONVERSATION_STATUS_ACTIVE`, `CONVERSATION_STATUS_ARCHIVED`) or `integer (int32)` | Optional; explicit presence | Lifecycle status recorded for the conversation thread. | | `messageCount` | `string (int64)` | Optional | Number of messages recorded in the thread summary. Pattern: `^-?\d+$`. | | `lastMessagePreview` | `string` | Optional | Text preview of the most recently projected message. | | `lastMessageAt` | `string (date-time)` | Optional | Timestamp of the most recently projected message. | | `createdAt` | `string (date-time)` | Optional | Timestamp when the conversation thread was created. | | `updatedAt` | `string (date-time)` | Optional | Timestamp when the conversation thread summary was last updated. | | `externalId` | `string` | Optional | Caller-supplied identifier associated with the conversation thread. | ### Values of `status` {#response-values-status} Lifecycle condition of a stored conversation: active or archived. This is separate from the execution status of an individual generation run.
| Value | No. | Form | Meaning | |---|---|---|---| | `CONVERSATION_STATUS_ACTIVE` | 0 | Canonical | The conversation is in its active lifecycle state. | | `CONVERSATION_STATUS_ARCHIVED` | 1 | Canonical | The conversation has been archived; this is a stored lifecycle condition, not a generation outcome. |
## Where used {#where-used} | Reference | Relationship | |---|---| | [List conversation threads](/api/conversations/list-threads) | `POST /api/v1/llm/list-threads` | Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # CustomMCPServer {#overview} URL: https://docs.travila.ai/api/models/schema-p1cuh9jgfq A project-scoped, HTTP-only MCP server definition, keyed (tenant\_id, project\_id, server\_id). Its wire ID is "custom:\{server\_id}". Credentials must be stored as secret references; inline tokens must not be persisted in this server definition. auth\_type selects the required credential fields. Authenticated modes require auth\_secret\_ref; NONE requires it to be empty. HEADER requires auth\_header\_name and QUERY requires auth\_query\_param; those names must be empty for every other mode. Inconsistent combinations are rejected before storage. Inline credentials are not accepted. ### Input constraints ### server\_id The server\_id must contain one through 63 characters. Its first character must be a lowercase ASCII letter or digit. Every remaining character must be a lowercase ASCII letter, digit, or hyphen. ### auth\_header\_name The auth\_header\_name may be empty text. Otherwise it must contain one through 128 characters, each an ASCII letter, digit, or one of these literal punctuation characters: ! # $ % & ' \* + . ^ \_ \` | \~ -. No other character is accepted. ### auth\_query\_param The auth\_query\_param may be empty text. Otherwise it must contain one through 128 characters, each an ASCII letter, digit, period, underscore, tilde, or hyphen. No other character is accepted. ### request\_timeout The request\_timeout duration must be no greater than 120 seconds. ## Meaning and usage {#meaning} See the [definition above](#overview). ### Input constraints See the [definition above](#overview). ### server\_id See the [definition above](#overview). ### auth\_header\_name See the [definition above](#overview). ### auth\_query\_param See the [definition above](#overview). ### request\_timeout See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `serverId` | `string` | **Required in requests** | Unique within the project. Pattern: `^[a-z0-9][a-z0-9-]{0,62}$`. | | `displayName` | `string` | Optional | Display name used for the registered MCP server. Maximum length: 200. | | `description` | `string` | Optional | Human-readable description of the resource. Maximum length: 1024. | | `endpoint` | `string (uri)` | **Required in requests** | HTTPS endpoint for Streamable HTTP; local and standard-input/output transports are unsupported. The egress guard also rejects prohibited destinations such as metadata, loopback, private-network and in-cluster addresses. HTTPS alone does not satisfy these destination checks. Maximum length: 2048. Pattern: `^https://`. | | `authType` | `string` (`CUSTOM_MCP_SERVER_AUTH_TYPE_NONE`, `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER`, `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER`, `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY`) or `integer (int32)` (`0`, `1`, `2`, `3`) | Optional; explicit presence | Authentication mechanism configured for the MCP server. | | `authSecretRef` | [SecretRef](/api/models/schema-opqho625u2#request) | Optional | Required credential reference for BEARER, HEADER and QUERY authentication. Resolves within this server's tenant and project; only the secret name is returned, never its value. | | `authHeaderName` | `string` | Optional | Name of the custom authentication header. The egress guard also rejects protected header names; satisfying the field's character pattern alone does not permit every header. Pattern: ``^([A-Za-z0-9!#$%&'*+.^_`\|~-]{1,128})?$``. | | `authQueryParam` | `string` | Optional | See meaning below. Pattern: `^([A-Za-z0-9._~-]{1,128})?$`. | | `enabled` | `boolean` | Optional | Whether this configuration is enabled. | | `requestTimeout` | `string` | Optional | Time allowed for a remote request. Omission or a nonpositive duration uses 30 seconds; positive durations below one second are raised to one second. Long waits can delay the conversation while the remote server is unavailable. Pattern: `^-?(?:0\|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$`. | | `version` | `string (int64)` | Optional | Output-only revision assigned by the store and incremented on updates. Ignored on writes. Pattern: `^-?\d+$`. | | `createdBy` | `string` | Optional | Output-only identity of the caller that registered the server. Ignored on writes. | | `createdAt` | `string (date-time)` | Optional | Output-only creation time assigned by the store. Ignored on writes. | | `updatedAt` | `string (date-time)` | Optional | Output-only last-update time assigned by the store. Ignored on writes. | **`authQueryParam`** Required for QUERY auth; the vendor's parameter name (e.g. "tavilyApiKey"). Restricted to RFC 3986 unreserved characters, which is NOT the same set as auth\_header\_name's RFC 7230 tchar: that set contains '&' (would append a second parameter), '#' (would truncate the URL at a fragment), '%' (would open a malformed escape) and '+' (decodes as a space). The query-parameter name uses its own character set. Empty is allowed — populated only for QUERY auth. ### Values of `authType` {#request-values-authtype} How credentials are attached to requests to a tenant-configured MCP server. Credentials are held by reference; inline credential values are neither accepted nor persisted.
| Value | No. | Form | Meaning | |---|---|---|---| | `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE` | 0 | Canonical | Send requests without attaching a secret for authentication. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER` | 1 | Canonical | See meaning below. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER` | 2 | Canonical | See meaning below. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` | 3 | Canonical | See meaning below. | **`CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER`** Send the secret as a Bearer token in the Authorization header. Authorization: Bearer \ ## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `serverId` | Pattern | `^[a-z0-9][a-z0-9-]{0,62}$` | | `displayName` | Maximum length | `200` | | `description` | Maximum length | `1024` | | `endpoint` | Maximum length | `2048` | | `endpoint` | Pattern | `^https://` | | `endpoint` | Uri | `true` | | `authType` | Defined enum value | `true` | | `authHeaderName` | Pattern | ``^([A-Za-z0-9!#$%&'*+.^_`\|~-]{1,128})?$`` | | `authQueryParam` | Pattern | `^([A-Za-z0-9._~-]{1,128})?$` | | `requestTimeout` | At most | `120s` | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `serverId` | `string` | **Required in requests** | Unique within the project. | | `displayName` | `string` | Optional | Display name used for the registered MCP server. | | `description` | `string` | Optional | Human-readable description of the resource. | | `endpoint` | `string` | **Required in requests** | HTTPS endpoint for Streamable HTTP; local and standard-input/output transports are unsupported. The egress guard also rejects prohibited destinations such as metadata, loopback, private-network and in-cluster addresses. HTTPS alone does not satisfy these destination checks. | | `authType` | `string` (`CUSTOM_MCP_SERVER_AUTH_TYPE_NONE`, `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER`, `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER`, `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY`) or `integer (int32)` | Optional; explicit presence | Authentication mechanism configured for the MCP server. | | `authSecretRef` | [SecretRef](/api/models/schema-opqho625u2#response) | Optional | Required credential reference for BEARER, HEADER and QUERY authentication. Resolves within this server's tenant and project; only the secret name is returned, never its value. | | `authHeaderName` | `string` | Optional | Name of the custom authentication header. The egress guard also rejects protected header names; satisfying the field's character pattern alone does not permit every header. | | `authQueryParam` | `string` | Optional | See meaning below. | | `enabled` | `boolean` | Optional | Whether this configuration is enabled. | | `requestTimeout` | `string` | Optional | Time allowed for a remote request. Omission or a nonpositive duration uses 30 seconds; positive durations below one second are raised to one second. Long waits can delay the conversation while the remote server is unavailable. Pattern: `^-?(?:0\|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$`. | | `version` | `string (int64)` | Optional | Output-only revision assigned by the store and incremented on updates. Ignored on writes. Pattern: `^-?\d+$`. | | `createdBy` | `string` | Optional | Output-only identity of the caller that registered the server. Ignored on writes. | | `createdAt` | `string (date-time)` | Optional | Output-only creation time assigned by the store. Ignored on writes. | | `updatedAt` | `string (date-time)` | Optional | Output-only last-update time assigned by the store. Ignored on writes. | **`authQueryParam`** Required for QUERY auth; the vendor's parameter name (e.g. "tavilyApiKey"). Restricted to RFC 3986 unreserved characters, which is NOT the same set as auth\_header\_name's RFC 7230 tchar: that set contains '&' (would append a second parameter), '#' (would truncate the URL at a fragment), '%' (would open a malformed escape) and '+' (decodes as a space). The query-parameter name uses its own character set. Empty is allowed — populated only for QUERY auth. ### Values of `authType` {#response-values-authtype} How credentials are attached to requests to a tenant-configured MCP server. Credentials are held by reference; inline credential values are neither accepted nor persisted.
| Value | No. | Form | Meaning | |---|---|---|---| | `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE` | 0 | Canonical | Send requests without attaching a secret for authentication. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER` | 1 | Canonical | See meaning below. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER` | 2 | Canonical | See meaning below. | | `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` | 3 | Canonical | See meaning below. | **`CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER`** Send the secret as a Bearer token in the Authorization header. Authorization: Bearer \ ## Request validation {#response-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `serverId` | Pattern | `^[a-z0-9][a-z0-9-]{0,62}$` | | `displayName` | Maximum length | `200` | | `description` | Maximum length | `1024` | | `endpoint` | Maximum length | `2048` | | `endpoint` | Pattern | `^https://` | | `endpoint` | Uri | `true` | | `authType` | Defined enum value | `true` | | `authHeaderName` | Pattern | ``^([A-Za-z0-9!#$%&'*+.^_`\|~-]{1,128})?$`` | | `authQueryParam` | Pattern | `^([A-Za-z0-9._~-]{1,128})?$` | | `requestTimeout` | At most | `120s` | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Register a custom MCP server](/api/mcp-servers/create-custom-mcp-server) | `POST /api/v1/mcp-servers/create` | | [Get a custom MCP server](/api/mcp-servers/get-custom-mcp-server) | `POST /api/v1/mcp-servers/get` | | [List custom MCP servers](/api/mcp-servers/list-custom-mcp-servers) | `POST /api/v1/mcp-servers/list` | | [Update a custom MCP server](/api/mcp-servers/update-custom-mcp-server) | `POST /api/v1/mcp-servers/update` | Download the [public reference contract](/reference/api-contract.json). - [mcp-servers OpenAPI](/mcp-servers.yaml) --- # GlobalPreferences {#overview} URL: https://docs.travila.ai/api/models/schema-p20l2ff92r Subscriber's global (all-workflow) notification preferences. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `enabled` | `boolean` | Optional | Master switch — false disables all non-critical notifications. | | `channels` | [ChannelToggles](/api/models/schema-oj4cvo85fs#response) | Optional | Channel switches recorded for these subscriber preferences. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get notification preferences](/api/notifications/get-preferences) | `POST /api/v1/notifications/get-preferences` | | [Get the caller's subscriber profile](/api/notifications/get-subscriber) | `POST /api/v1/notifications/manage/get-subscriber` | Download the [public reference contract](/reference/api-contract.json). - [notifications OpenAPI](/notifications.yaml) --- # ProviderInfo {#overview} URL: https://docs.travila.ai/api/models/schema-p28bvfiqrb Configured notification provider and its integration identifier and active state. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `provider` | `string` (`PROVIDER_TYPE_FCM`, `PROVIDER_TYPE_APNS`, `PROVIDER_TYPE_SENDGRID`, `PROVIDER_TYPE_SES`, `PROVIDER_TYPE_TWILIO`, `PROVIDER_TYPE_SLACK`, `PROVIDER_TYPE_DISCORD`) or `integer (int32)` | Optional; explicit presence | Notification delivery provider being configured or reported. | | `integrationId` | `string` | Optional | Identifier of the provider integration in Novu. | | `active` | `boolean` | Optional | Whether the resource is marked active. | ### Values of `provider` {#response-values-provider} Service used to deliver a notification through its selected channel.
| Value | No. | Form | Meaning | |---|---|---|---| | `PROVIDER_TYPE_FCM` | 0 | Canonical | See meaning below. | | `PROVIDER_TYPE_APNS` | 1 | Canonical | See meaning below. | | `PROVIDER_TYPE_SENDGRID` | 2 | Canonical | See meaning below. | | `PROVIDER_TYPE_SES` | 3 | Canonical | See meaning below. | | `PROVIDER_TYPE_TWILIO` | 4 | Canonical | See meaning below. | | `PROVIDER_TYPE_SLACK` | 5 | Canonical | See meaning below. | | `PROVIDER_TYPE_DISCORD` | 6 | Canonical | See meaning below. | **`PROVIDER_TYPE_FCM`** Firebase Cloud Messaging for device or web push delivery. Firebase Cloud Messaging (push) **`PROVIDER_TYPE_APNS`** Apple Push Notification service for Apple-device push delivery. Apple Push Notification Service **`PROVIDER_TYPE_SENDGRID`** SendGrid for email delivery. SendGrid (email) **`PROVIDER_TYPE_SES`** Amazon Simple Email Service for email delivery. AWS SES (email) **`PROVIDER_TYPE_TWILIO`** Twilio for SMS delivery. Twilio (SMS) **`PROVIDER_TYPE_SLACK`** Slack for chat-message delivery. Slack (chat) **`PROVIDER_TYPE_DISCORD`** Discord for chat-message delivery. Discord (chat)
## Where used {#where-used} | Reference | Relationship | |---|---| | [List configured providers](/api/notifications/get-providers) | `POST /api/v1/notifications/manage/get-providers` | Download the [public reference contract](/reference/api-contract.json). - [notifications OpenAPI](/notifications.yaml) --- # TopicSubscriptionResult {#overview} URL: https://docs.travila.ai/api/models/schema-p2eb0gb1ln Result of a topic subscription operation (add/remove subscribers). Novu returns partial success — some subscribers may fail while others succeed. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `totalCount` | `string (int64)` | Optional | Total number of subscribers reported for the membership-change result. Pattern: `^-?\d+$`. | | `successful` | `string (int64)` | Optional | Number of subscribers accepted by the topic subscription operation. Pattern: `^-?\d+$`. | | `failed` | `string (int64)` | Optional | Number of subscribers rejected by the topic subscription operation. Pattern: `^-?\d+$`. | | `errors` | Array of [TopicSubscriptionError](/api/models/schema-okmh5pnenu#response) | Optional | Errors reported while processing notification requests. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Add subscribers to a topic](/api/notifications/add-subscribers-to-topic) | `POST /api/v1/notifications/manage/add-subscribers-to-topic` | | [Remove subscribers from a topic](/api/notifications/remove-subscribers-from-topic) | `POST /api/v1/notifications/manage/remove-subscribers-from-topic` | Download the [public reference contract](/reference/api-contract.json). - [notifications OpenAPI](/notifications.yaml) --- # WorkflowPreferences {#overview} URL: https://docs.travila.ai/api/models/schema-p2jctrvcjc Per-workflow notification channel preferences for a subscriber. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `workflowId` | `string` | Optional | Novu workflow identifier (slug). | | `workflowName` | `string` | Optional | Human-readable display name. | | `critical` | `boolean` | Optional | If true, subscriber cannot opt out (admin-enforced). | | `tags` | Array of `string` | Optional | Workflow tags for grouping in settings UI. | | `channels` | [ChannelToggles](/api/models/schema-oj4cvo85fs#response) | Optional | Channel switches recorded for these subscriber preferences. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get notification preferences](/api/notifications/get-preferences) | `POST /api/v1/notifications/get-preferences` | | [Get the caller's subscriber profile](/api/notifications/get-subscriber) | `POST /api/v1/notifications/manage/get-subscriber` | Download the [public reference contract](/reference/api-contract.json). - [notifications OpenAPI](/notifications.yaml) --- # UpdateWorkflowPreferenceRequest {#overview} URL: https://docs.travila.ai/api/models/schema-p38aqgjs3a Inputs for changing the subscriber’s channel preferences for one notification workflow. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `workflowId` | `string` | **Required in requests** | Identifier of the notification workflow whose subscriber preferences are being changed. Minimum length: 1. | | `channels` | [ChannelToggles](/api/models/schema-oj4cvo85fs#request) | Optional | Channel switches to update for the subscriber. | ## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `workflowId` | Minimum length | `1` | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Bulk-update per-workflow preferences](/api/notifications/bulk-update-preferences) | `POST /api/v1/notifications/bulk-update-preferences` | | [Update per-workflow notification preferences](/api/notifications/update-workflow-preference) | `POST /api/v1/notifications/update-workflow-preference` | Download the [public reference contract](/reference/api-contract.json). - [notifications OpenAPI](/notifications.yaml) --- # HeyGenVoiceSettings {#overview} URL: https://docs.travila.ai/api/models/schema-p3askj7st1 HeyGen voice settings ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `voiceId` | `string` | Optional | Provider voice identifier used for speech synthesis. | | `rate` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Speech-rate setting passed to the HeyGen voice provider. | | `emotion` | `string` | Optional | See meaning below. | | `elevenlabsSettings` | [HeyGenElevenLabsSettings](/api/models/schema-on0k8c8den#request) | Optional | ElevenLabs synthesis settings associated with the HeyGen voice. | **`emotion`** Emotion setting passed to HeyGen voice synthesis. "EXCITED" | "SERIOUS" | "FRIENDLY" | "SOOTHING" | "BROADCASTER" ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a voice session (in progress)](/api/conversations/create-daily-session) | `POST /api/v1/llm/create-daily-session` |
Models containing this value | Model | Relationship | |---|---| | [HeyGenConfig](/api/models/schema-pd3vbf0eel#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # Resource {#overview} URL: https://docs.travila.ai/api/models/schema-pbf83hf239 A resource exposed by an MCP server ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `uri` | `string` | Optional | Canonical URI for the resource. | | `title` | `string` | Optional | Display title of the MCP resource. | | `description` | `string` | Optional | Description of the content available from the MCP resource. | | `mimeType` | `string` | Optional | Media type of the content exposed by the MCP resource. | | `content` | Array of [ContentPart](/api/models/schema-1hqi9r2bhh#response) | Optional | Optional embedded content. | | `annotations` | Map from string to `string` | Optional | Optional annotations/metadata. | | `lastModified` | `string (date-time)` | Optional | Time when this resource was last modified. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [List MCP resources](/api/conversations/mcp-list-resources) | `POST /api/v1/llm/mcp-list-resources` | | [Read an MCP resource](/api/conversations/mcp-read-resource) | `POST /api/v1/llm/mcp-read-resource` | Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # SessionSummary {#overview} URL: https://docs.travila.ai/api/models/schema-pbibjr8tih Aggregated trace, usage, and score information for an evaluation session. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `sessionId` | `string` | Optional | Identifier of the evaluation session grouping related traces. | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | | `durationSeconds` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Elapsed session duration, in seconds. | | `environment` | `string` | Optional | Environment label attached to the evaluation record. | | `userIds` | Array of `string` | Optional | User identifiers recorded for this evaluation session. | | `traceCount` | `string (int64)` | Optional | Number of traces represented by this session summary. Pattern: `^-?\d+$`. | | `totalCost` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Total cost reported for the evaluated generation or aggregate. | | `inputTokens` | `string (int64)` | Optional | Input-token usage reported for the evaluated generation. Pattern: `^-?\d+$`. | | `outputTokens` | `string (int64)` | Optional | Output-token usage reported for the evaluated generation. Pattern: `^-?\d+$`. | | `totalTokens` | `string (int64)` | Optional | Total token usage reported for the evaluated generation or aggregate. Pattern: `^-?\d+$`. | | `traceTags` | Array of `string` | Optional | Labels collected from the session’s evaluation traces. | | `scores` | Array of [Score](/api/models/schema-1jm5lo00e7#response) | Optional | Evaluation scores returned for the selected objects or query. | | `commentCount` | `string (int64)` | Optional | Number of comments reported on the evaluation object. Pattern: `^-?\d+$`. | | `metadataJson` | `string` | Optional | Additional attributes serialized as a JSON object. | | `bookmarked` | `boolean` | Optional | Whether the evaluation object is bookmarked. | | `conversationIds` | Array of `string` | Optional | Conversation identifiers observed on the session’s traces; a session may span multiple conversations. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get a session](/api/evals/get-session) | `POST /api/v1/evals/get-session` | | [List sessions](/api/evals/list-sessions) | `POST /api/v1/evals/list-sessions` |
Models containing this value | Model | Relationship | |---|---| | [SessionDetail](/api/models/schema-ph83s78vr5#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # HeyGenConfig {#overview} URL: https://docs.travila.ai/api/models/schema-pd3vbf0eel HeyGen avatar/video configuration ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `enabled` | `boolean` | Optional | Whether this configuration is enabled. | | `avatarId` | `string` | Optional | Identifier of the HeyGen avatar used for the session. | | `version` | `string` | Optional | Version of the resource represented by this message. | | `quality` | `string` | Optional | See meaning below. | | `videoEncoding` | `string` | Optional | See meaning below. | | `voice` | [HeyGenVoiceSettings](/api/models/schema-p3askj7st1#request) | Optional | Voice configuration used by the HeyGen avatar. | | `knowledgeId` | `string` | Optional | Identifier of the HeyGen knowledge resource associated with the avatar. | | `knowledgeBase` | `string` | Optional | Knowledge text supplied to the HeyGen avatar configuration. | | `disableIdleTimeout` | `boolean` | Optional | Whether HeyGen’s session idle timeout is disabled. | | `activityIdleTimeout` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | See meaning below. | **`quality`** Video-quality setting requested for the HeyGen avatar. "high" | "medium" | "low" **`videoEncoding`** Video codec requested for the HeyGen avatar stream. "H264" | "VP8" **`activityIdleTimeout`** HeyGen activity idle timeout, in seconds. seconds ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a voice session (in progress)](/api/conversations/create-daily-session) | `POST /api/v1/llm/create-daily-session` |
Models containing this value | Model | Relationship | |---|---| | [SocayoAgentConfig](/api/models/schema-phip2o3ju4#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # ConversationSettings {#overview} URL: https://docs.travila.ai/api/models/schema-ph6avse89k Conversation-level settings controlling behavior across sends [`maxLoops`](/api/models/schema-ph6avse89k#request-field-maxloops) caps the **total number of generations** in a run — not the number of tool round trips. Default is **2**, which is what one round trip costs: a first generation to emit the tool call, a second to synthesize its result. On the final generation the model is sent **no tools at all** (the request omits the [`tools`](/api/models/schema-1h82h7ri5p#request-field-tools) array), so it cannot emit a call there. `maxLoops: 1` therefore means a single tool-free reply — a valid way to ask for one, but not a way to get one tool round trip. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `interruptPolicy` | `string` (`INTERRUPT_POLICY_REJECT_NEW`, `INTERRUPT_POLICY_CANCEL_ONGOING`, `INTERRUPT_POLICY_QUEUE`, `INTERRUPT_POLICY_IGNORE`) or `integer (int32)` | Optional; explicit presence | Policy for an incoming message while another generation run is active. | | `maxLoops` | `string (int64)` | Optional | Default limit on agentic generation loops for the conversation. Pattern: `^-?\d+$`. | | `maxParallelTools` | `string (int64)` | Optional | Maximum number of tool executions allowed concurrently by this configuration. Pattern: `^-?\d+$`. | | `mcpServers` | Array of [MCPServerReference](/api/models/schema-1hik90rmo1#request) | Optional | MCP servers available to this conversation; used for tool discovery/filtering | | `toolPolicy` | [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#request) | Optional | Optional per-conversation tool execution policy applied to AgentConfig | | `promptVariables` | Map from string to JSON value | Optional | Typed values used when rendering profile prompt templates. Numbers, arrays, Boolean values and strings retain their respective JSON types. The values are shared by profiles in the conversation and can be refreshed with UpdatePromptVariables. Switching profiles renders the new template with the same values. | ### Values of `interruptPolicy` {#request-values-interruptpolicy} How a conversation handles a new send while another generation run is active.
| Value | No. | Form | Meaning | |---|---|---|---| | `INTERRUPT_POLICY_REJECT_NEW` | 0 | Canonical | See meaning below. | | `INTERRUPT_POLICY_CANCEL_ONGOING` | 1 | Canonical | See meaning below. | | `INTERRUPT_POLICY_QUEUE` | 2 | Canonical | See meaning below. | | `INTERRUPT_POLICY_IGNORE` | 3 | Canonical | Accept the send without persisting its message or starting a new run; let the ongoing run continue. | **`INTERRUPT_POLICY_REJECT_NEW`** Reject the new send with an error while a run is active; do not append its user message. Reject the new Send with an error if a run is active **`INTERRUPT_POLICY_CANCEL_ONGOING`** Cancel the ongoing run and start a new run for the incoming message. Cancel the ongoing run and immediately start a new one with the new message **`INTERRUPT_POLICY_QUEUE`** Queue the incoming message to run after the current run completes. Queue the new Send; it will run after the current run completes
## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `interruptPolicy` | `string` (`INTERRUPT_POLICY_REJECT_NEW`, `INTERRUPT_POLICY_CANCEL_ONGOING`, `INTERRUPT_POLICY_QUEUE`, `INTERRUPT_POLICY_IGNORE`) or `integer (int32)` | Optional; explicit presence | Policy for an incoming message while another generation run is active. | | `maxLoops` | `string (int64)` | Optional | Default limit on agentic generation loops for the conversation. Pattern: `^-?\d+$`. | | `maxParallelTools` | `string (int64)` | Optional | Maximum number of tool executions allowed concurrently by this configuration. Pattern: `^-?\d+$`. | | `mcpServers` | Array of [MCPServerReference](/api/models/schema-1hik90rmo1#response) | Optional | MCP servers available to this conversation; used for tool discovery/filtering | | `toolPolicy` | [ToolExecutionPolicy](/api/models/schema-1h2ji21uc4#response) | Optional | Optional per-conversation tool execution policy applied to AgentConfig | | `promptVariables` | Map from string to JSON value | Optional | Typed values used when rendering profile prompt templates. Numbers, arrays, Boolean values and strings retain their respective JSON types. The values are shared by profiles in the conversation and can be refreshed with UpdatePromptVariables. Switching profiles renders the new template with the same values. | ### Values of `interruptPolicy` {#response-values-interruptpolicy} How a conversation handles a new send while another generation run is active.
| Value | No. | Form | Meaning | |---|---|---|---| | `INTERRUPT_POLICY_REJECT_NEW` | 0 | Canonical | See meaning below. | | `INTERRUPT_POLICY_CANCEL_ONGOING` | 1 | Canonical | See meaning below. | | `INTERRUPT_POLICY_QUEUE` | 2 | Canonical | See meaning below. | | `INTERRUPT_POLICY_IGNORE` | 3 | Canonical | Accept the send without persisting its message or starting a new run; let the ongoing run continue. | **`INTERRUPT_POLICY_REJECT_NEW`** Reject the new send with an error while a run is active; do not append its user message. Reject the new Send with an error if a run is active **`INTERRUPT_POLICY_CANCEL_ONGOING`** Cancel the ongoing run and start a new run for the incoming message. Cancel the ongoing run and immediately start a new one with the new message **`INTERRUPT_POLICY_QUEUE`** Queue the incoming message to run after the current run completes. Queue the new Send; it will run after the current run completes
## Where used {#where-used} | Reference | Relationship | |---|---| | [Get full conversation state](/api/conversations/get-conversation-state) | `POST /api/v1/llm/conversation-state` | | [Update prompt variables](/api/conversations/update-prompt-variables) | `POST /api/v1/llm/update-prompt-variables` | | [Update conversation settings](/api/conversations/update-settings) | `POST /api/v1/llm/update-settings` | | [Create a new conversation thread](/api/conversations/create-thread) | `POST /api/v1/llm/create-thread` | Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # SessionDetail {#overview} URL: https://docs.travila.ai/api/models/schema-ph83s78vr5 Evaluation session summary together with the traces belonging to the session. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `summary` | [SessionSummary](/api/models/schema-pbibjr8tih#response) | Optional | Summary information for the evaluation session. | | `traces` | Array of [TraceSummary](/api/models/schema-1k4mjul65u#response) | Optional | Evaluation traces returned by the query. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get a session](/api/evals/get-session) | `POST /api/v1/evals/get-session` | Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # TraceDetail {#overview} URL: https://docs.travila.ai/api/models/schema-pha7gtif3l Evaluation trace summary together with its observations and attached scores. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `summary` | [TraceSummary](/api/models/schema-1k4mjul65u#response) | Optional | Summary information for the evaluation trace. | | `observations` | Array of [Observation](/api/models/schema-1ju9tclufp#response) | Optional | Observations associated with the evaluation trace. | | `scores` | Array of [Score](/api/models/schema-1jm5lo00e7#response) | Optional | Evaluation scores returned for the selected objects or query. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get a trace](/api/evals/get-trace) | `POST /api/v1/evals/get-trace` | Download the [public reference contract](/reference/api-contract.json). - [evals OpenAPI](/evals.yaml) --- # SocayoAgentConfig {#overview} URL: https://docs.travila.ai/api/models/schema-phip2o3ju4 Socayo-specific agent configuration (bundled) ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `conversationKey` | `string` | **Required in requests** | Conversation thread identifier associated with the voice session. Minimum length: 1. | | `userId` | `string` | **Required in requests** | Identifier of the user associated with the operation. Minimum length: 1. | | `provider` | `string` (`AGENT_PROVIDER_PIPECAT_CLOUD`, `AGENT_PROVIDER_CEREBRIUM`) or `integer (int32)` | Optional; explicit presence | Backend provider to use for session orchestration; defaults to PIPECAT\_CLOUD | | `tts` | [TTSConfig](/api/models/schema-on2m1c27d9#request) | Optional | Bundled sub-configs Speech-synthesis configuration supplied to the Socayo agent. | | `heygen` | [HeyGenConfig](/api/models/schema-pd3vbf0eel#request) | Optional | HeyGen avatar and voice configuration for the Socayo agent. | | `transport` | [TransportConfig](/api/models/schema-on4mqk0ok8#request) | Optional | Audio transport settings used by the Socayo agent. | | `extras` | Map from string to JSON value | Optional | Optional extras for forward-compat | ### Values of `provider` {#request-values-provider} Hosting backend used to deploy or start a voice agent.
| Value | No. | Form | Meaning | |---|---|---|---| | `AGENT_PROVIDER_PIPECAT_CLOUD` | 0 | Canonical | Use the Pipecat Cloud hosting backend. | | `AGENT_PROVIDER_CEREBRIUM` | 1 | Canonical | Use the Cerebrium hosting backend. |
## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `conversationKey` | Minimum length | `1` | | `userId` | Minimum length | `1` | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Create a voice session (in progress)](/api/conversations/create-daily-session) | `POST /api/v1/llm/create-daily-session` | Download the [public reference contract](/reference/api-contract.json). - [conversations OpenAPI](/conversations.yaml) --- # StorageManagerState {#overview} URL: https://docs.travila.ai/api/models/schema-phpid7698e Tracked files, folders and storage usage for the effective storage owner. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In responses | [View fields](#response) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `userId` | `string` | Optional | Identifier of the user associated with the operation. | | `folders` | Map from string to [FolderInfo](/api/models/schema-opsbitjge1#response) | Optional | Path -> FolderInfo. | | `files` | Map from string to [FileInfo](/api/models/schema-1lls6fo8p7#response) | Optional | Path -> FileInfo. | | `totalSizeBytes` | `string (int64)` | Optional | Combined size of the represented files, in bytes. Pattern: `^-?\d+$`. | | `quotaBytes` | `string (int64)` | Optional | Storage capacity allocated to the user, in bytes. Pattern: `^-?\d+$`. | | `totalFileCount` | `string (int64)` | Optional | Number of files tracked in the storage state. Pattern: `^-?\d+$`. | | `totalFolderCount` | `string (int64)` | Optional | Number of folders tracked in the storage state. Pattern: `^-?\d+$`. | | `createdAt` | `string` | Optional | When user's storage was initialized. | | `lastModified` | `string` | Optional | Last modification timestamp. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Get storage state](/api/storage/get-state) | `POST /api/v1/storage/get-state` | Download the [public reference contract](/reference/api-contract.json). - [storage OpenAPI](/storage.yaml) --- # SourcePromptTemplate {#overview} URL: https://docs.travila.ai/api/models/schema-pjk9r8rn5b Source persona template to convert into an agent profile during import. Its source\_dsl contains the original template syntax from which the importer derives the profile template and variable specifications. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `profileId` | `string` | Optional | Identifier of the agent profile associated with the operation or generation. | | `name` | `string` | Optional | Display name for the imported agent profile. | | `whenToUse` | `string` | Optional | Instructions describing when the imported agent profile should be selected. | | `keywords` | Array of `string` | Optional | Keywords associated with selection of the imported agent profile. | | `sourceDsl` | `string` | Optional | Raw source-DSL system prompt. | | `generationConfig` | [GenerationConfig](/api/models/schema-1h82h7ri5p#request) | Optional | Generation settings other than the prompt, such as temperature. Must not set model or models: import refuses a template that does, and the model is set afterwards with UpdateAgentProfile. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Import a prompt library](/api/agent-profiles/import-agent-profiles) | `POST /api/v1/agent-profiles/import` | Download the [public reference contract](/reference/api-contract.json). - [agent-profiles OpenAPI](/agent-profiles.yaml) --- # LLMGenerationCompletedEvent {#overview} URL: https://docs.travila.ai/api/models/schema-pntuu08p80 Event emitted when a generation run reaches a terminal state. The event context identifies the associated conversation. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `runId` | `string` | Optional | Unique identifier for the workflow run | | `status` | `string` (`WORKFLOW_STATUS_RUNNING`, `WORKFLOW_STATUS_COMPLETED`, `WORKFLOW_STATUS_FAILED`, `WORKFLOW_STATUS_TIMED_OUT`, `WORKFLOW_STATUS_CANCELED`) or `integer (int32)` | Optional; explicit presence | Terminal status of the run | | `loopCount` | `string (int64)` | Optional | Number of agent loops/steps executed Pattern: `^-?\d+$`. | | `durationMs` | `string (int64)` | Optional | End-to-end run duration in milliseconds Pattern: `^-?\d+$`. | | `usage` | [Usage](/api/models/schema-1j1vov2uoh#request) | Optional | Optional usage accounting for the run | | `error` | [RpcError](/api/models/schema-1fajlacjs0#request) | Optional | Structured error for FAILED/TIMED\_OUT/CANCELED runs. | | `usageByModel` | Array of [UsageByModel](/api/models/schema-po7orad6ac#request) | Optional | Per-model breakdown of the same usage `usage` aggregates. Additive: `usage` stays the run-level total so existing consumers are unaffected, while billing keys its charges on model. Empty when the producer predates it. | | `turnKey` | `string` | Optional | See meaning below. | **`turnKey`** Identifies the conversation turn this run served: the `message_id` of the opening user message. Messages produced by the run carry the same value as `source_user_message_id`. To derive the corresponding evaluation trace ID, trim surrounding whitespace from the turn key and the event context's `caller_key` and `correlation_id`. Let `conv_id` be the trimmed caller key, falling back to the trimmed correlation ID when the caller key is empty. Compute SHA-256 over `"trace|" + conv_id + "|msg:" + turn_key` using the trimmed turn key and use the first 16 digest bytes, represented as 32 hexadecimal characters. The literal `msg:` is part of this derivation, not part of `turn_key`. This identifies the trace when it has been ingested; the generation-completed event does not itself create an evaluation trace. An empty key means no turn attribution, including turns recorded before this field was available or whose opening message could not be resolved. Do not invent a key for those turns. ### Values of `status` {#request-values-status} Lifecycle state of a workflow execution, distinct from the reason a terminal execution ended.
| Value | No. | Form | Meaning | |---|---|---|---| | `WORKFLOW_STATUS_RUNNING` | 0 | Canonical | The workflow has started and has not reached a terminal outcome. | | `WORKFLOW_STATUS_COMPLETED` | 1 | Canonical | The workflow finished successfully. | | `WORKFLOW_STATUS_FAILED` | 2 | Canonical | The workflow ended because execution failed; inspect its error or end reason. | | `WORKFLOW_STATUS_TIMED_OUT` | 3 | Canonical | The workflow ended because its execution time limit elapsed. | | `WORKFLOW_STATUS_CANCELED` | 4 | Canonical | The workflow was cancelled before normal completion. This enum retains its existing CANCELED wire spelling. |
## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `runId` | `string` | Optional | Unique identifier for the workflow run | | `status` | `string` (`WORKFLOW_STATUS_RUNNING`, `WORKFLOW_STATUS_COMPLETED`, `WORKFLOW_STATUS_FAILED`, `WORKFLOW_STATUS_TIMED_OUT`, `WORKFLOW_STATUS_CANCELED`) or `integer (int32)` | Optional; explicit presence | Terminal status of the run | | `loopCount` | `string (int64)` | Optional | Number of agent loops/steps executed Pattern: `^-?\d+$`. | | `durationMs` | `string (int64)` | Optional | End-to-end run duration in milliseconds Pattern: `^-?\d+$`. | | `usage` | [Usage](/api/models/schema-1j1vov2uoh#response) | Optional | Optional usage accounting for the run | | `error` | [RpcError](/api/models/schema-1fajlacjs0#response) | Optional | Structured error for FAILED/TIMED\_OUT/CANCELED runs. | | `usageByModel` | Array of [UsageByModel](/api/models/schema-po7orad6ac#response) | Optional | Per-model breakdown of the same usage `usage` aggregates. Additive: `usage` stays the run-level total so existing consumers are unaffected, while billing keys its charges on model. Empty when the producer predates it. | | `turnKey` | `string` | Optional | See meaning below. | **`turnKey`** Identifies the conversation turn this run served: the `message_id` of the opening user message. Messages produced by the run carry the same value as `source_user_message_id`. To derive the corresponding evaluation trace ID, trim surrounding whitespace from the turn key and the event context's `caller_key` and `correlation_id`. Let `conv_id` be the trimmed caller key, falling back to the trimmed correlation ID when the caller key is empty. Compute SHA-256 over `"trace|" + conv_id + "|msg:" + turn_key` using the trimmed turn key and use the first 16 digest bytes, represented as 32 hexadecimal characters. The literal `msg:` is part of this derivation, not part of `turn_key`. This identifies the trace when it has been ingested; the generation-completed event does not itself create an evaluation trace. An empty key means no turn attribution, including turns recorded before this field was available or whose opening message could not be resolved. Do not invent a key for those turns. ### Values of `status` {#response-values-status} Lifecycle state of a workflow execution, distinct from the reason a terminal execution ended.
| Value | No. | Form | Meaning | |---|---|---|---| | `WORKFLOW_STATUS_RUNNING` | 0 | Canonical | The workflow has started and has not reached a terminal outcome. | | `WORKFLOW_STATUS_COMPLETED` | 1 | Canonical | The workflow finished successfully. | | `WORKFLOW_STATUS_FAILED` | 2 | Canonical | The workflow ended because execution failed; inspect its error or end reason. | | `WORKFLOW_STATUS_TIMED_OUT` | 3 | Canonical | The workflow ended because its execution time limit elapsed. | | `WORKFLOW_STATUS_CANCELED` | 4 | Canonical | The workflow was cancelled before normal completion. This enum retains its existing CANCELED wire spelling. |
## Examples {#examples} ### event-llm-generation-completed {#example-event-llm-generation-completed} Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event. ```json { "runId": "9d4c2e1f-27b1-4304-ae54-af7fe876df31", "status": "WORKFLOW_STATUS_COMPLETED", "loopCount": 1, "durationMs": "1250", "usage": { "promptTokens": 412, "completionTokens": 88, "totalTokens": 500 } } ``` Download the [public reference contract](/reference/api-contract.json). --- # LLMGenerationStartedEvent {#overview} URL: https://docs.travila.ai/api/models/schema-pnv14jb39g Event emitted when a generation run starts. The event context identifies the associated conversation. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `runId` | `string` | Optional | Unique identifier for the workflow run | | `config` | [GenerationConfig](/api/models/schema-1h82h7ri5p#request) | Optional | Optional snapshot of generation configuration used for this run | | `startingSequence` | `string (int64)` | Optional | Conversation sequence number at the moment the run started (if known) Pattern: `^-?\d+$`. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `runId` | `string` | Optional | Unique identifier for the workflow run | | `config` | [GenerationConfig](/api/models/schema-1h82h7ri5p#response) | Optional | Optional snapshot of generation configuration used for this run | | `startingSequence` | `string (int64)` | Optional | Conversation sequence number at the moment the run started (if known) Pattern: `^-?\d+$`. | ## Examples {#examples} ### event-llm-generation-started {#example-event-llm-generation-started} Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event. ```json { "runId": "9d4c2e1f-27b1-4304-ae54-af7fe876df31", "startingSequence": "1" } ``` Download the [public reference contract](/reference/api-contract.json). --- # LLMMessagePublishedEvent {#overview} URL: https://docs.travila.ai/api/models/schema-po1qsocerv Domain event published when a new assistant/tool message is produced. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `message` | [Message](/api/models/schema-1j3dcf7kvu#request) | Optional | The generated assistant/tool message | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `message` | [Message](/api/models/schema-1j3dcf7kvu#response) | Optional | The generated assistant/tool message | ## Examples {#examples} ### event-llm-message-published {#example-event-llm-message-published} Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event. ```json { "message": { "role": "ROLE_ASSISTANT", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Here is your daily briefing." } ], "messageId": "924ad207-f757-4b1f-bf41-8344ce32dd01", "sequence": "2", "generatedBy": "9d4c2e1f-27b1-4304-ae54-af7fe876df31" } } ``` Download the [public reference contract](/reference/api-contract.json). --- # ToolCallCompletedEvent {#overview} URL: https://docs.travila.ai/api/models/schema-po3pkfshjg A tool call has one pre-terminal lifecycle notification, for execution starting or approval being required, followed by one terminal outcome. This pairing includes calls that require human approval. The terminal outcome is COMPLETED, FAILED, CANCELLED or TIMED\_OUT. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `toolCall` | [ToolCall](/api/models/schema-1it6mqsqoo#request) | Optional | Final tool call. Its terminal status is COMPLETED, FAILED, CANCELLED or TIMED\_OUT; inspect the result and end reason for the outcome. | | `executionTimeMs` | `string (int64)` | Optional | Wall-clock execution time in milliseconds (0 when unknown, e.g. dispatch error). Pattern: `^-?\d+$`. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `toolCall` | [ToolCall](/api/models/schema-1it6mqsqoo#response) | Optional | Final tool call. Its terminal status is COMPLETED, FAILED, CANCELLED or TIMED\_OUT; inspect the result and end reason for the outcome. | | `executionTimeMs` | `string (int64)` | Optional | Wall-clock execution time in milliseconds (0 when unknown, e.g. dispatch error). Pattern: `^-?\d+$`. | ## Examples {#examples} ### event-llm-tool-call-completed {#example-event-llm-tool-call-completed} Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event. ```json { "executionTimeMs": 240, "toolCall": { "id": "call_123", "name": "send_briefing", "serverId": "briefing-tools", "argumentsJson": { "conversation_id": "b81d5345-c1f9-4fb9-b558-a6327c75b842" }, "status": "TOOL_EXECUTION_STATUS_COMPLETED", "resultJson": { "accepted": true } } } ``` Download the [public reference contract](/reference/api-contract.json). --- # ToolCallStartedEvent {#overview} URL: https://docs.travila.ai/api/models/schema-po5rioe4il Event for a tool call that has begun execution or is waiting for human approval. Check the event name and tool-call status to distinguish these cases; the event context identifies the conversation. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `toolCall` | [ToolCall](/api/models/schema-1it6mqsqoo#request) | Optional | Tool-call snapshot before a result is available, including its identity, name, server and arguments. For llm.tool\_call\_started the status is EXECUTING; for llm.tool\_call\_approval\_required it is REQUIRES\_CONFIRMATION and requires\_approval\_at is the decision deadline. result\_json is unset. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `toolCall` | [ToolCall](/api/models/schema-1it6mqsqoo#response) | Optional | Tool-call snapshot before a result is available, including its identity, name, server and arguments. For llm.tool\_call\_started the status is EXECUTING; for llm.tool\_call\_approval\_required it is REQUIRES\_CONFIRMATION and requires\_approval\_at is the decision deadline. result\_json is unset. | ## Examples {#examples} ### event-llm-tool-call-started {#example-event-llm-tool-call-started} Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event. ```json { "toolCall": { "id": "call_123", "name": "send_briefing", "serverId": "briefing-tools", "argumentsJson": { "conversation_id": "b81d5345-c1f9-4fb9-b558-a6327c75b842" }, "status": "TOOL_EXECUTION_STATUS_EXECUTING" } } ``` ### event-llm-tool-call-approval-required {#example-event-llm-tool-call-approval-required} Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event. ```json { "toolCall": { "id": "call_123", "name": "send_briefing", "serverId": "briefing-tools", "argumentsJson": { "conversation_id": "b81d5345-c1f9-4fb9-b558-a6327c75b842" }, "status": "TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION", "requiresApprovalAt": "2026-09-16T12:05:00Z" } } ``` Download the [public reference contract](/reference/api-contract.json). --- # UsageByModel {#overview} URL: https://docs.travila.ai/api/models/schema-po7orad6ac Usage attributed to a single model within one generation run. LLMGenerationCompletedEvent.usage is the run-level aggregate, summed across every model the run called. A tool-using turn routinely spans several models, and the rate card prices per model, so billing needs the breakdown alongside the aggregate rather than instead of it. One entry per distinct model. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `model` | `string` | Optional | Model identifier as recorded on the assistant message that produced it. | | `calls` | `string (int64)` | Optional | Provider completions attributed to this model within the run. Pattern: `^-?\d+$`. | | `usage` | [Usage](/api/models/schema-1j1vov2uoh#request) | Optional | Same shape as the run aggregate, scoped to this model. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `model` | `string` | Optional | Model identifier as recorded on the assistant message that produced it. | | `calls` | `string (int64)` | Optional | Provider completions attributed to this model within the run. Pattern: `^-?\d+$`. | | `usage` | [Usage](/api/models/schema-1j1vov2uoh#response) | Optional | Same shape as the run aggregate, scoped to this model. | ## Where used {#where-used}
Models containing this value | Model | Relationship | |---|---| | [LLMGenerationCompletedEvent](/api/models/schema-pntuu08p80#response) | Nested in model | | [LLMGenerationCompletedEvent](/api/models/schema-pntuu08p80#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). --- # AuthorizationModel {#overview} URL: https://docs.travila.ai/api/models/schema-pq9d837o76 AuthorizationModel represents the schema/DSL defining types, relations, and rules Models define what relationships are possible in the authorization system Type-reference view: `API Schema 6up6drbioc`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | Optional | Model ID/version identifier. | | `schemaVersion` | `string` | Optional | FGA schema version (e.g., "1.1"). | | `typeDefinitions` | `string` | Optional | FGA DSL defining types and relations. | | `createdAt` | `string (date-time)` | Optional | When this model was created. | | `metadata` | Map from string to JSON value | Optional | Additional metadata as key-value pairs. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | Optional | Model ID/version identifier. | | `schemaVersion` | `string` | Optional | FGA schema version (e.g., "1.1"). | | `typeDefinitions` | `string` | Optional | FGA DSL defining types and relations. | | `createdAt` | `string (date-time)` | Optional | When this model was created. | | `metadata` | Map from string to JSON value | Optional | Additional metadata as key-value pairs. | ## Where used {#where-used} | Reference | Relationship | |---|---| | AuthorizationModel | API JSON uses JSON field names (camelCase). | Download the [public reference contract](/reference/api-contract.json). --- # Store {#overview} URL: https://docs.travila.ai/api/models/schema-pqh3ei5p5l Store represents an OpenFGA authorization store (multi-tenancy boundary) Each store maintains its own authorization models, tuples, and data Type-reference view: `API Schema 6urseekt57`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | Optional | Store ID (unique identifier). | | `name` | `string` | Optional | Store name/label for reference. | | `createdAt` | `string (date-time)` | Optional | When store was created. | | `updatedAt` | `string (date-time)` | Optional | Last update time. | | `status` | `string` | Optional | Store status (active, archived, etc.). | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | Optional | Store ID (unique identifier). | | `name` | `string` | Optional | Store name/label for reference. | | `createdAt` | `string (date-time)` | Optional | When store was created. | | `updatedAt` | `string (date-time)` | Optional | Last update time. | | `status` | `string` | Optional | Store status (active, archived, etc.). | ## Where used {#where-used} | Reference | Relationship | |---|---| | Store | API JSON uses JSON field names (camelCase). | Download the [public reference contract](/reference/api-contract.json). --- # TupleKey {#overview} URL: https://docs.travila.ai/api/models/schema-pqjdejpl2g TupleKey represents a relationship tuple: user -relation-> object This is the fundamental data model in OpenFGA Type-reference view: `API Schema 62ajd5h7r5`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `user` | `string` | Optional | User identifier (e.g., "user\:alice", "team\:engineering"). | | `relation` | `string` | Optional | Relation name (e.g., "owner", "editor", "viewer"). | | `object` | `string` | Optional | Object identifier (e.g., "document\:doc1"). | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `user` | `string` | Optional | User identifier (e.g., "user\:alice", "team\:engineering"). | | `relation` | `string` | Optional | Relation name (e.g., "owner", "editor", "viewer"). | | `object` | `string` | Optional | Object identifier (e.g., "document\:doc1"). | ## Where used {#where-used} | Reference | Relationship | |---|---| | TupleKey | API JSON uses JSON field names (camelCase). | Download the [public reference contract](/reference/api-contract.json). --- # UserSet {#overview} URL: https://docs.travila.ai/api/models/schema-pql723cqr4 UserSet represents the expanded result of users with a specific relation to an object Type-reference view: `API Schema 62c40oktj2`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `users` | Array of `string` | Optional | Direct user relations. | | `teams` | Array of `string` | Optional | Team/group relations. | | `computed` | Array of `string` | Optional | Computed/derived relations through inheritance. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `users` | Array of `string` | Optional | Direct user relations. | | `teams` | Array of `string` | Optional | Team/group relations. | | `computed` | Array of `string` | Optional | Computed/derived relations through inheritance. | ## Where used {#where-used} | Reference | Relationship | |---|---| | UserSet | API JSON uses JSON field names (camelCase). | Download the [public reference contract](/reference/api-contract.json). --- # ReceiveMessageRequest {#overview} URL: https://docs.travila.ai/api/models/schema-q69v86pv94 Receives a new message event (e.g., from the generation workflow) Type-reference view: `API Schema 9frhv4euve`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `message` | [Message](/api/models/schema-1j3dcf7kvu#request) | Optional | The message to append (assistant/tool/system) | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `message` | [Message](/api/models/schema-1j3dcf7kvu#response) | Optional | The message to append (assistant/tool/system) | ## Where used {#where-used} | Reference | Relationship | |---|---| | ReceiveMessageRequest | API JSON uses JSON field names (camelCase). | Download the [public reference contract](/reference/api-contract.json). --- # BranchMetadata {#overview} URL: https://docs.travila.ai/api/models/schema-q7dt6t9g53 Reason, labels, and quality metadata recorded for an alternative conversation branch. Type-reference view: `API Schema 626klhca0u`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `createdReason` | `string` | Optional | See meaning below. | | `description` | `string` | Optional | Description of the conversation branch’s purpose. | | `tags` | Map from string to `string` | Optional | Key-value labels associated with the conversation branch. | | `qualityScore` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | 0-1, how good this branch is. | **`createdReason`** Reason recorded when creating the alternative conversation branch. "user\_request", "error\_recovery", "a\_b\_test" ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `createdReason` | `string` | Optional | See meaning below. | | `description` | `string` | Optional | Description of the conversation branch’s purpose. | | `tags` | Map from string to `string` | Optional | Key-value labels associated with the conversation branch. | | `qualityScore` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | 0-1, how good this branch is. | **`createdReason`** Reason recorded when creating the alternative conversation branch. "user\_request", "error\_recovery", "a\_b\_test" ## Where used {#where-used} | Reference | Relationship | |---|---| | [ConversationBranch](/api/models/schema-q7hl8fcm9r) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [ConversationBranch](/api/models/schema-q7hl8fcm9r#response) | Nested in model | | [ConversationBranch](/api/models/schema-q7hl8fcm9r#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). --- # ConversationBranch {#overview} URL: https://docs.travila.ai/api/models/schema-q7hl8fcm9r Conversation branching Type-reference view: `API Schema 626klhca0u`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `branchId` | `string` | Optional | Identifier of the conversation branch. | | `branchName` | `string` | Optional | See meaning below. | | `fromMessageId` | `string` | Optional | Identifier of the message from which the conversation branch diverged. | | `messageIds` | Array of `string` | Optional | Message identifiers associated with this conversation branch. | | `metadata` | [BranchMetadata](/api/models/schema-q7dt6t9g53#request) | Optional | Reason, labels, and quality metadata for this conversation branch. | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | | `isActive` | `boolean` | Optional | Whether this conversation branch is marked active. | **`branchName`** Name distinguishing this alternative branch of the conversation. "alternative\_approach", "retry\_attempt" ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `branchId` | `string` | Optional | Identifier of the conversation branch. | | `branchName` | `string` | Optional | See meaning below. | | `fromMessageId` | `string` | Optional | Identifier of the message from which the conversation branch diverged. | | `messageIds` | Array of `string` | Optional | Message identifiers associated with this conversation branch. | | `metadata` | [BranchMetadata](/api/models/schema-q7dt6t9g53#response) | Optional | Reason, labels, and quality metadata for this conversation branch. | | `createdAt` | `string (date-time)` | Optional | Time when this record was created. | | `isActive` | `boolean` | Optional | Whether this conversation branch is marked active. | **`branchName`** Name distinguishing this alternative branch of the conversation. "alternative\_approach", "retry\_attempt" ## Where used {#where-used} | Reference | Relationship | |---|---| | ConversationBranch | API JSON uses JSON field names (camelCase). | Download the [public reference contract](/reference/api-contract.json). --- # EmbeddingConfig {#overview} URL: https://docs.travila.ai/api/models/schema-q81ihe4v3e Generic embedding configuration for embedding-assisted upserts Type-reference view: `API Schema 6v7cprckcj`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `provider` | `string` | Optional | See meaning below. | | `model` | `string` | Optional | See meaning below. | | `options` | Map from string to JSON value | Optional | Provider-specific options. | **`provider`** Provider used to generate embeddings for the input text. e.g., "openrouter" **`model`** Embedding model used to convert input text into vectors. e.g., "openai/text-embedding-3-large" ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `provider` | `string` | Optional | See meaning below. | | `model` | `string` | Optional | See meaning below. | | `options` | Map from string to JSON value | Optional | Provider-specific options. | **`provider`** Provider used to generate embeddings for the input text. e.g., "openrouter" **`model`** Embedding model used to convert input text into vectors. e.g., "openai/text-embedding-3-large" ## Where used {#where-used} | Reference | Relationship | |---|---| | EmbeddingConfig | API JSON uses JSON field names (camelCase). | Download the [public reference contract](/reference/api-contract.json). --- # MCPServerConfig {#overview} URL: https://docs.travila.ai/api/models/schema-q8egnnm4a3 Full MCP server configuration used for server management. Type-reference view: `API Schema 62d20s50a7`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `serverId` | `string` | Optional | Unique identifier for this MCP server. | | `name` | `string` | Optional | Human-readable name (e.g., "GitHub Copilot MCP", "File System Tools"). | | `endpoint` | `string` | Optional | Server endpoint URL or connection string. | | `authConfig` | Map from string to `string` | Optional | Authentication configuration; for example, a token entry whose value is github\_token. | | `enabled` | `boolean` | Optional | Whether this server is enabled. | | `priority` | `string (int64)` | Optional | Default priority for tool selection (higher = preferred). Pattern: `^-?\d+$`. | | `discoveryTimeout` | `string` | Optional | Timeout for tool discovery. Pattern: `^-?(?:0\|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$`. | | `serverMetadata` | Map from string to `string` | Optional | Additional server-specific metadata. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `serverId` | `string` | Optional | Unique identifier for this MCP server. | | `name` | `string` | Optional | Human-readable name (e.g., "GitHub Copilot MCP", "File System Tools"). | | `endpoint` | `string` | Optional | Server endpoint URL or connection string. | | `authConfig` | Map from string to `string` | Optional | Authentication configuration; for example, a token entry whose value is github\_token. | | `enabled` | `boolean` | Optional | Whether this server is enabled. | | `priority` | `string (int64)` | Optional | Default priority for tool selection (higher = preferred). Pattern: `^-?\d+$`. | | `discoveryTimeout` | `string` | Optional | Timeout for tool discovery. Pattern: `^-?(?:0\|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$`. | | `serverMetadata` | Map from string to `string` | Optional | Additional server-specific metadata. | ## Where used {#where-used} | Reference | Relationship | |---|---| | MCPServerConfig | API JSON uses JSON field names (camelCase). | Download the [public reference contract](/reference/api-contract.json). --- # ScoredVector {#overview} URL: https://docs.travila.ai/api/models/schema-q8s584s888 Vector match with score and optional payloads Type-reference view: `API Schema 6vbcrt8mlp`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | Optional | Identifier of the vector record returned by the search. | | `score` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Similarity score reported by the vector search provider. | | `values` | Array of `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Present if include\_values=true. | | `metadata` | Map from string to JSON value | Optional | Present if include\_metadata=true. | | `namespace` | `string` | Optional | Namespace used to group vector records. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | Optional | Identifier of the vector record returned by the search. | | `score` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Similarity score reported by the vector search provider. | | `values` | Array of `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Present if include\_values=true. | | `metadata` | Map from string to JSON value | Optional | Present if include\_metadata=true. | | `namespace` | `string` | Optional | Namespace used to group vector records. | ## Where used {#where-used} | Reference | Relationship | |---|---| | ScoredVector | API JSON uses JSON field names (camelCase). | Download the [public reference contract](/reference/api-contract.json). --- # SparseValues {#overview} URL: https://docs.travila.ai/api/models/schema-q8ublbqo12 Optional sparse component for hybrid search Type-reference view: `API Schema 6vhb5mpe0m`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `indices` | Array of `string (int64)` | Optional | Positions of the nonzero components in the sparse vector. | | `values` | Array of `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Numeric components of the sparse vector. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `indices` | Array of `string (int64)` | Optional | Positions of the nonzero components in the sparse vector. | | `values` | Array of `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Numeric components of the sparse vector. | ## Where used {#where-used} | Reference | Relationship | |---|---| | [Vector](/api/models/schema-q9cp251mpk) | API JSON uses JSON field names (camelCase). |
Models containing this value | Model | Relationship | |---|---| | [Vector](/api/models/schema-q9cp251mpk#response) | Nested in model | | [Vector](/api/models/schema-q9cp251mpk#request) | Nested in model |
Download the [public reference contract](/reference/api-contract.json). --- # TextDocument {#overview} URL: https://docs.travila.ai/api/models/schema-q92tfl8qp2 Text and associated metadata submitted for an embedding-assisted upsert. `id` identifies the vector record, `text` supplies the content to embed, and `metadata` carries additional attributes. Type-reference view: `API Schema t0tqko5pgb`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | **Required in requests** | Identifier used to associate embedded text with its vector record. Minimum length: 1. | | `text` | `string` | **Required in requests** | Text content supplied for the embedding or document. Minimum length: 1. | | `metadata` | Map from string to JSON value | Optional | Additional attributes associated with the resource. | ## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `id` | Minimum length | `1` | | `text` | Minimum length | `1` | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | **Required in requests** | Identifier used to associate embedded text with its vector record. | | `text` | `string` | **Required in requests** | Text content supplied for the embedding or document. | | `metadata` | Map from string to JSON value | Optional | Additional attributes associated with the resource. | ## Request validation {#response-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `id` | Minimum length | `1` | | `text` | Minimum length | `1` | ## Where used {#where-used} | Reference | Relationship | |---|---| | TextDocument | API JSON uses JSON field names (camelCase). | Download the [public reference contract](/reference/api-contract.json). --- # Vector {#overview} URL: https://docs.travila.ai/api/models/schema-q9cp251mpk Canonical vector record shared across vector DB services Type-reference view: `API Schema 6vhb5mpe0m`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | **Required in requests** | Identifier used to address the vector record within its namespace. Minimum length: 1. | | `values` | Array of `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Dense vector values. | | `sparseValues` | [SparseValues](/api/models/schema-q8ublbqo12#request) | Optional | Optional sparse component. | | `metadata` | Map from string to JSON value | Optional | Provider metadata (JSON object). | | `namespace` | `string` | Optional | Optional namespace/bucket. | | `updatedAt` | `string (date-time)` | Optional | Time when this record was last updated. | ## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `id` | Minimum length | `1` | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `id` | `string` | **Required in requests** | Identifier used to address the vector record within its namespace. | | `values` | Array of `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Dense vector values. | | `sparseValues` | [SparseValues](/api/models/schema-q8ublbqo12#response) | Optional | Optional sparse component. | | `metadata` | Map from string to JSON value | Optional | Provider metadata (JSON object). | | `namespace` | `string` | Optional | Optional namespace/bucket. | | `updatedAt` | `string (date-time)` | Optional | Time when this record was last updated. | ## Request validation {#response-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `id` | Minimum length | `1` | ## Where used {#where-used} | Reference | Relationship | |---|---| | Vector | API JSON uses JSON field names (camelCase). | Download the [public reference contract](/reference/api-contract.json). --- # DatasetRunItem {#overview} URL: https://docs.travila.ai/api/models/schema-qbff0c5l2f One item of a dataset run links the dataset item that was executed to the trace it produced. Keeping this pairing lets you compare the same dataset item across runs. Type-reference view: `API Schema 6vk7rqoi5v`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `datasetItemId` | `string` | **Required in requests** | Identifier of the dataset item used by this evaluation run. Minimum length: 1. | | `traceId` | `string` | **Required in requests** | Identifier of the evaluation trace. Minimum length: 1. | | `observationId` | `string` | Optional | Optional: pin the run to one observation inside the trace rather than the whole turn, for a harness that scores a single generation. | ## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `datasetItemId` | Minimum length | `1` | | `traceId` | Minimum length | `1` | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `datasetItemId` | `string` | **Required in requests** | Identifier of the dataset item used by this evaluation run. | | `traceId` | `string` | **Required in requests** | Identifier of the evaluation trace. | | `observationId` | `string` | Optional | Optional: pin the run to one observation inside the trace rather than the whole turn, for a harness that scores a single generation. | ## Request validation {#response-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `datasetItemId` | Minimum length | `1` | | `traceId` | Minimum length | `1` | ## Where used {#where-used} | Reference | Relationship | |---|---| | DatasetRunItem | API JSON uses JSON field names (camelCase). | Download the [public reference contract](/reference/api-contract.json). --- # EvalCommentSuppressionState {#overview} URL: https://docs.travila.ai/api/models/schema-qbs1n8ja02 State identifying suppressed evaluation comments. Suppressed comment identifiers are filtered out of every ListComments response. Suppression does not delete the underlying comment from the evaluation provider. A platform operator may still see that comment there. Type-reference view: `API Schema e0ru3nm27c`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `commentIds` | Array of `string` | Optional | Identifiers of evaluation comments selected for suppression. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `commentIds` | Array of `string` | Optional | Identifiers of evaluation comments selected for suppression. | ## Where used {#where-used} | Reference | Relationship | |---|---| | EvalCommentSuppressionState | API JSON uses JSON field names (camelCase). | Download the [public reference contract](/reference/api-contract.json). --- # ClientToolDispatch {#overview} URL: https://docs.travila.ai/api/models/schema-qj0o2cvv4e A batch of client-tool calls awaiting execution for a conversation turn. Type-reference view: `API Schema 9ftjkkjhfa`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `toolCalls` | Array of [ToolCall](/api/models/schema-1it6mqsqoo#request) | Optional | Tool calls emitted by the model or returned by the operation. | | `dispatchSeq` | `string (int64)` | Optional | Client-tool dispatch sequence used to wait for a later dispatch batch. Pattern: `^-?\d+$`. | | `assistantMessage` | [Message](/api/models/schema-1j3dcf7kvu#request) | Optional | Assistant message that armed this batch. The finish reason can be the same for a client-tool turn and an MCP turn; use the run status to distinguish them. | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `toolCalls` | Array of [ToolCall](/api/models/schema-1it6mqsqoo#response) | Optional | Tool calls emitted by the model or returned by the operation. | | `dispatchSeq` | `string (int64)` | Optional | Client-tool dispatch sequence used to wait for a later dispatch batch. Pattern: `^-?\d+$`. | | `assistantMessage` | [Message](/api/models/schema-1j3dcf7kvu#response) | Optional | Assistant message that armed this batch. The finish reason can be the same for a client-tool turn and an MCP turn; use the run status to distinguish them. | ## Where used {#where-used} | Reference | Relationship | |---|---| | ClientToolDispatch | API JSON uses JSON field names (camelCase). | Download the [public reference contract](/reference/api-contract.json). --- # ScheduledTriggerEnvelope {#overview} URL: https://docs.travila.ai/api/models/schema-s6i1d2bv7o Declared context for a scheduled action: the schedule ID, tenant, project, beneficiary and scheduled time. These fields are intended to carry trusted context from the scheduler. Receiving support for this envelope is not currently implemented. Type-reference view: `API Schema i828te0das`. Request and response views describe this type; they do not declare an endpoint. ## Meaning and usage {#meaning} See the [definition above](#overview). ## Usage profiles {#fields} | Usage | Fields and validation | |---|---| | In requests | [View fields](#request) | | In responses | [View fields](#response) | ## In requests {#request} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `scheduleId` | `string` | **Required in requests** | Identifier of the scheduled job. Minimum length: 1. | | `tenantId` | `string` | **Required in requests** | Identifier of the tenant that owns or scopes this record. Minimum length: 1. | | `projectId` | `string` | **Required in requests** | Identifier of the project within the tenant that scopes this record. Minimum length: 1. | | `onBehalfOf` | `string` | **Required in requests** | Subject on whose behalf the scheduled trigger runs. Minimum length: 1. | | `scheduledTime` | `string (date-time)` | **Required in requests** | Instant for which this execution or trigger was scheduled. | ## Request validation {#request-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `scheduleId` | Minimum length | `1` | | `tenantId` | Minimum length | `1` | | `projectId` | Minimum length | `1` | | `onBehalfOf` | Minimum length | `1` | | `scheduledTime` | Required value | `true` | ## In responses {#response} API JSON uses JSON field names (camelCase). | Field | Type | Presence | Meaning | |---|---|---|---| | `scheduleId` | `string` | **Required in requests** | Identifier of the scheduled job. | | `tenantId` | `string` | **Required in requests** | Identifier of the tenant that owns or scopes this record. | | `projectId` | `string` | **Required in requests** | Identifier of the project within the tenant that scopes this record. | | `onBehalfOf` | `string` | **Required in requests** | Subject on whose behalf the scheduled trigger runs. | | `scheduledTime` | `string (date-time)` | **Required in requests** | Instant for which this execution or trigger was scheduled. | ## Request validation {#response-validation} These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules. | Applies to | Rule | Requirement | |---|---|---| | `scheduleId` | Minimum length | `1` | | `tenantId` | Minimum length | `1` | | `projectId` | Minimum length | `1` | | `onBehalfOf` | Minimum length | `1` | | `scheduledTime` | Required value | `true` | ## Where used {#where-used} | Reference | Relationship | |---|---| | ScheduledTriggerEnvelope | API JSON uses JSON field names (camelCase). | Download the [public reference contract](/reference/api-contract.json).